MCP tools

The server is https://app.openscaffold.ai/api/mcp/mcp (streamable HTTP). It sees one workspace: the one picked when the agent signed in. Every tool except list_deployments, use_deployment and create_deployment works on one deployment and takes its deployment_id (the briefing’s Deployment id: dep_… line, or list_deployments). No tool ever returns two deployments’ data. The tools call the plan and profile together the harness (as in generate_harness); in the app it’s the deployment’s Build (the plan) and Customer tabs. Read-only tools are marked readOnlyHint: true, so clients that ask before writes (for example Codex’s writes approval mode) only ask for the rest. No tool deletes anything, and nothing an agent sends changes the plan directly: plan changes wait for a person under Needs you on the deployment’s Customer tab (or on Build, when they only move work items’ status).

Workspace tools

`list_deployments` · read-only

The workspace’s active deployments, names and ids only. Call it first when there’s no briefing in context. An empty list means a new user: offer to set up their first customer. No arguments.

[{ "id": "dep_01J…", "name": "Acme Logistics", "customer_name": "Acme Logistics", "harness_version": 3, "created_at": "2026-10-20T14:02:11.000Z" }]

`use_deployment`

Switch this session to a deployment by id or name (part of the name works). Returns its briefing. Announce the switch. If several match, it lists them and switches nothing.

Argument	Type
`deployment`	string	Id, or (part of) its name or customer name

`create_deployment`

Create a deployment for a new customer; it becomes this session’s. Check list_deployments first: one deployment per customer.

Argument	Type
`name`	string	e.g. “Acme Logistics”
`customer_name`	string, optional	Defaults to `name`
`customer_domains`	string[], optional	Their email domains, e.g. `["acme.com"]`. Connected email and chat feed the deployment by these

{ "deployment": { "id": "dep_01J…", "name": "Acme Logistics" }, "next": "Add the customer's material with add_documents (every file, in as few calls as fit). The plan starts on its own once they are read; call get_briefing about once a minute until it exists." }

`add_document`

Add one of the customer’s documents the person has locally. For more than one file, use add_documents. Same processing as an upload in the app: parsed, searchable, read for findings. Adding the same text twice returns “Already uploaded (same content).” Once the deployment has a plan, anything these documents would change in it waits for a person: text your agent sends never counts as the customer’s own words.

Argument	Type
`deployment_id`	string
`source_type`	`transcript` \| `ticket` \| `email` \| `doc`	`.vtt` / `.srt` text as is, as `transcript`
`title`	string
`author`	string, optional
`occurred_at`	ISO date, optional	When it was said or written
`text`	string	Up to 4 MB

{ "document_id": "doc_01J…", "status": "processing" }

`add_documents`

Add many of the customer’s documents in one call: the way to send a folder or a ticket export (one document per row). They’re read as one batch, so the first plan waits for all of them, and a deployment that already has a plan gets one plan change for the lot. A document with the same title and text as one already there is skipped.

Argument	Type
`deployment_id`	string
`documents`	array, 1–200	Each `{source_type, title, author?, occurred_at?, text}`, as in `add_document`. Up to 4 MB of text per call

{ "added": 151, "already_uploaded": 2, "document_ids": ["doc_01J…"], "status": "processing" }

`generate_harness`

Build the deployment’s first plan from its documents. Usually not needed: the first plan starts on its own once every document is read. Use it when get_briefing shows no plan and nothing reading or building (e.g. after a failed build). Runs for a minute or two in the background. Says so if documents are still being read or if a plan already exists.

Argument	Type
`deployment_id`	string

{ "job_id": "job_01J…", "status": "generating", "next": "Call get_briefing in a minute or two." }

Deployment tools

`get_briefing` · read-only

The deployment’s briefing, as markdown: goal, must-haves (each with its action, as in get_plan), rules, what to check before relying on it (facts only documentation or the FDE state), what we don’t know yet and who to ask, open questions, what changed since the person last looked, playbooks. The same text the Claude Code session hook prints. Before the first plan exists it shows progress instead.

Argument	Type
`deployment_id`	string

Loaded: Acme Logistics (requested by the agent). Wrong customer? Say "switch to <name>".
Deployment id: dep_01J… (pass it to every openscaffold tool)

# OpenScaffold — Acme Logistics

## Goal
Cut late deliveries by 30% before the Q2 renewal. [Kickoff call, 00:14:22]

## In scope (must)
- goal Cut late deliveries by 30% before the Q2 renewal. — every requirement below serves this
- req_1 Delivery-time report, split by warehouse — building
…

`search` · read-only

Search everything this customer said or wrote: calls, tickets, emails, docs. Use it before assuming anything about their requirements, systems or wording, and cite results by title. Ranked by relevance (with the deployment’s vocabulary), weighted by its search rules (preferred and demoted authors, recency), with its source-type order breaking ties.

Argument	Type
`deployment_id`	string
`query`	string
`source_types`	string[], optional	Any of `transcript`, `ticket`, `email`, `doc`
`since`	ISO date, optional	Only documents from this date on
`limit`	number, optional	Up to 20
`author`	string, optional	Only what this person said or wrote (sender, or speaker in a call)

Each hit has a quote: exact words from the source you can paste into propose_change citations.

[{ "document_id": "doc_01J…", "title": "Kickoff call", "source_type": "transcript", "source_system": "upload", "author": "Priya Shah", "occurred_at": "2026-10-03T00:00:00.000Z", "url": null, "snippet": "…we can't send anything to the cloud, it all stays on-prem…", "locator": { "start_char": 18233, "end_char": 18301, "ts": "00:31:05", "speaker": "Priya Shah" } }]

`get_document` · read-only

Read one document, in full or a slice around a search locator (±1,000 characters). Up to 20,000 characters per call.

Argument	Type
`deployment_id`	string
`document_id`	string
`start_char`, `end_char`	number, optional

Returns the document’s metadata, start_char, end_char, total_chars and text.

`get_plan` · read-only

The plan as markdown, under one legend line (do = build it; check = verify in the system first; ask = don’t build, ask the FDE, who asks the customer; leave = don’t touch): goal, in-scope requirements (id, priority, status, action, what exists today vs. what to build), out of scope (leave), what we don’t know yet (up to 5 areas the customer’s material covers thinly, each with who to ask, only ever a person named in the material), open questions. Each requirement’s action is computed from its evidence: do for the customer’s word or an FDE decision on a must-have or agreed item, check for anything documentation, the FDE or nobody said (check: not agreed yet — confirm priority with the FDE for a should/could the customer said but nobody agreed), ask only when an open question or gap names an item that has no quote of its own. An open question that names a requirement, or quotes the same passage as one, shows ”⚠ Unsettled: <question> (ask the FDE before building this part)” right under it; the requirement keeps its action. Every question and gap says “blocks <id>” or “doesn’t block a plan item (ask only if your work needs it)”; the gaps list always ends by asking what rules the system doesn’t enforce that only people know. Every item ends with its citations, [document title, 00:14:22], or [added by FDE]. An item that isn’t the customer’s own word starts with a tag: [documented, unverified: check it in the system or a sandbox] (only product, API or vendor documentation says it), [FDE said; the customer hasn't confirmed], or [unverified: nobody at the customer said it]. A value that replaced an earlier one says (replaces X, which no longer holds): X is history, never the current value.

Argument	Type
`deployment_id`	string

`get_profile` · read-only

The customer: summary, stakeholders, systems, constraints, vocabulary, each cited and tagged the same way as get_plan. Check constraints before proposing an architecture.

Argument	Type
`deployment_id`	string

`get_playbooks` · read-only

Your team’s recipes for this kind of work, from the playbooks this deployment uses: setup, environments, domain knowledge, caveats, references. Guidance from past work, never facts about this customer.

Argument	Type
`deployment_id`	string

`what_changed` · read-only

What changed since a plan version (default: since this person last read the briefing): plan changes, new documents, plan changes waiting for a person.

Argument	Type
`deployment_id`	string
`since_version`	number, optional

`propose_change`

Propose a change to the plan or profile when the customer’s material shows something new or different. Every citation must quote this deployment’s documents word for word (at least 4 words); a quote that isn’t in the document is refused. It waits under Needs you on the deployment’s Customer tab; nothing changes until a person approves.

Argument	Type
`deployment_id`	string
`summary`	string	One line, e.g. “Goal raised to 30%“
`rationale`	string
`ops`	Op[]	`upsert_item`, `remove_item` (with `section`: `plan.in_scope`, `plan.out_of_scope`, `plan.delta`, `plan.open_questions`, `profile.stakeholders`, `profile.systems`, `profile.constraints`, `profile.vocabulary`, `commands`), `set_goal`, `set_summary`, `set_search_rules`
`citations`	`{document_id, quote}[]`	At least one

{ "proposal_id": "prp_01J…", "status": "pending", "note": "Nothing changed yet. To put it in front of the FDE: call what_changed and show them its lines; they decide it in OpenScaffold (decide_change gives the link)." }

`record_decision`

Record a decision the person just made in your conversation: answer one of the plan’s open questions, and/or save it as a rule your agents follow (optionally only somewhere, with applies_to) or as an agreed requirement. Only their own words, never your guess or the customer’s documents (use propose_change for those). It doesn’t change the plan: the decision waits for them to approve it in OpenScaffold, and becomes theirs only then. Tell them it’s waiting.

Argument	Type
`deployment_id`	string
`decision`	string	The decision in their words
`question_id`	string, optional	The open question (`q_…`) it answers
`save_as`	`rule` \| `requirement` \| `answer_only`	`answer_only` needs `question_id`
`applies_to`	string, optional	Where a rule holds, e.g. `the internal dashboard`. Omit when it holds everywhere

{ "recorded": false, "status": "waiting_for_fde", "proposal_id": "prp_01J…", "review_url": "https://app.openscaffold.ai/w/acme-team/d/dep_01J…", "applies_to": "the internal dashboard" }

`record_conversation`

Record what someone at the customer told you during the work: their reply in this chat, an email or message the person pasted, an answer to a question you asked. OpenScaffold keeps it as a document (a transcript titled “Conversation with <person> (<role>), <date>”), reads it like any other, and the plan learns from it, so the next session and teammates don’t ask again. Call it straight away when a person settles a fact, rule or decision. The person’s own decisions go to record_decision; files to add_documents. A recorded conversation is your report of what was said: you write who spoke, their email and their side. So it never counts as the customer’s own words. Every plan change it implies waits for the FDE under Needs you, and an item that rests only on it is never marked as the customer’s word: it is unverified, documented or the FDE’s, by side (table below). With verbatim: true the answers are written as that person’s lines; with verbatim: false they are your notes. There’s no approval prompt: saving a note takes no click, so it works in auto mode and headless runs.

Argument	Type
`deployment_id`	string
`person`	string	Full name of who answered
`email`	string, optional	Their address, shown with the conversation
`role`	string, optional	e.g. `Head of dispatch`
`channel`	string, optional	e.g. `chat`, `email`, `Slack`, `call`
`occurred_at`	string, optional	ISO date it was said; default now
`verbatim`	boolean	`true` only if every answer is their exact words
`side`	`customer` \| `vendor` \| `fde` \| `other`	Who the person is: `customer` only for someone who works for or speaks for the customer. An item resting only on a `customer` conversation is unverified; on `vendor` or `other`, documented; on `fde`, the FDE’s. Required
`exchanges`	array, 1–50	Each `{asked?, answer}`

{ "document_id": "doc_01J…", "status": "processing", "note": "Recorded. OpenScaffold reads it now; …" }

`propose_playbook_entries`

Before finishing: propose what you learned that would help on another customer doing the same kind of work. Never anything about this customer; the leak guard refuses names, people, domains, systems, their terms and copied passages, and says which entry and why. An admin approves.

Argument	Type
`deployment_id`	string
`playbook_id`	string	One `get_playbooks` lists
`entries`	1–10 of `{type, title, body, image?, url?}`	`type`: `setup`, `environment` (needs `image`), `domain`, `caveat`, `reference` (needs `url`)

`report_session`

Before the session ends: what you did, in 2–4 sentences, and any requirements whose status you moved. The summary shows in the deployment’s Activity (⋯ menu); status moves become one plan change under Needs you on Build.

Argument	Type
`deployment_id`	string
`summary`	string	What was built or changed, what’s left
`progress`	`{requirement_id, status}[]`, optional	`status`: `agreed`, `building`, `done`

{ "saved": true, "proposal_id": "prp_01J…", "note": "Requirement progress waits for the FDE on Build in OpenScaffold; nothing changed yet." }

`request_review`

Ask for an independent review of your change. Use it when the person asks you to check, review or verify your work, and before you finish any change. A separate reviewer on OpenScaffold’s side (not you) checks that the change does what the customer asked: the work items it claims, the customer’s rules and terms, what’s out of scope, and the caveats in the playbooks this deployment uses. It doesn’t review code quality or hunt for bugs. See The review. With the CLI signed in (not with the plugin or OAuth alone), npx -y @openscaffold/cli@latest review --req req_1,req_2 does all of this in one shell command: it collects the diff itself (or the listed files, in a folder git doesn’t track), waits and prints the verdict, or after about 2 minutes the review id to pass to get_review. See CLI.

Argument	Type
`deployment_id`	string
`title`	string	One line, e.g. “Daily on-time report: lane query”
`requirement_ids`	string[], optional	The plan’s in-scope item ids this change works on (from `get_plan`)
`diff`	string	Unified diff, exactly as git prints it: `git diff HEAD`, and each new file as `git diff --no-index /dev/null <file>` (that also works in a folder that isn’t a git repo). Up to 400 KB; larger is refused, and so is a diff shortened with placeholder comments

{ "review_id": "rev_01J…", "status": "queued", "next": "Call get_review with this review_id now: it waits for the verdict (reviews take 30–50 s)." }

`get_review` · read-only

The result of a request_review, as markdown: the verdict, a short summary, whether each claimed work item is met, and findings with file:line and the customer’s quotes. A running review is waited on for up to 50 seconds before the call answers (reviews take 30–50 s), so call it straight after request_review and one call usually returns the verdict. If it’s still running it says “Still reviewing (started N s ago…). Call get_review again now”. Findings come in sections: blockers, issues, “Ask before changing code — leave it as it is” (questions for the FDE, with who to ask), and notes; a work item can be open when it depends on something the customer hasn’t settled. Follow the last line: fix blockers (and issues, or say why not), put asks in report_session without changing code, and stop after 3 reviews of the same items. Only this deployment’s reviews.

Argument	Type
`deployment_id`	string
`review_id`	string

`get_test_scenarios` · read-only

Acceptance scenarios to test before handover, written from this customer’s own rules and requirements: single steps and multi-turn conversations (for example, show a list and then act on one item from it), boundary cases (just inside, exactly at and just outside a limit the customer stated), consent before actions that charge money or can’t be undone, and failures the customer described. Each scenario has steps, the expected outcome (or what to check), the plan items it tests, and the customer’s quote it comes from; a scenario whose quote isn’t found word for word in the customer’s documents is never shown. Nothing is invented: when the customer’s words don’t settle an outcome, there’s no scenario for it. Always run every scenario whose tests ids include an item you built or changed, plus any that test only rules or systems your change must obey, and again after your last code change; a failing Check: is a question for the FDE, not a bug. It never changes the plan, so it’s marked read-only, but if the current plan version has no scenarios yet the call starts writing them in the background. They’re written once per plan version, as soon as that version exists (the plan is built, a change applies, or someone edits or restores it). If they’re still being written, the call waits up to 50 seconds; if a newer plan version’s are still on their way, you get the previous version’s with a note. Always run every scenario for what you built or changed (each names the plan items it tests), plus any that test only rules or systems your change must obey, and again after your last code change. An Expected: outcome comes only from the customer’s words or an FDE decision, and is followed by Customer said: "…" with the quote; a scenario testing anything documented, second-hand or blocked by an open question is a Check:: find out what the real system does, or ask the FDE. A failing Check: is a question, not a bug. There’s no minimum count: little settled means few scenarios.

Argument	Type
`deployment_id`	string

`answer_question`

Your agent asks you one of the plan’s open questions in a form, with its best guess already filled in. Press Enter if it’s right, or edit it. Your answer waits for you to approve it in OpenScaffold, as a rule, an agreed requirement, or just the answer; only then is it your decision. Skip the form and nothing changes.

`decide_change`

Points you at a plan change that is waiting for you. It never approves or rejects anything: your agent shows you the change’s lines and the review link, and you decide it in OpenScaffold.

`mark_done`

A passing review marks the work items it graded met as done on its own (Undo is in Activity). get_review lists what’s left to mark (partly met → building), and your agent calls this with those ids. There’s no approval prompt.

`use_playbooks`

Start using team playbooks on this deployment, by id. Adds to what the deployment already uses, never removes; unknown ids change nothing. get_playbooks and the next briefing then include them. There’s no approval prompt: playbooks hold no customer data and only add guidance. OpenScaffold also starts using the playbooks it suggests for a deployment on its own after the first plan; remove any under Playbooks.

Argument	Type
`deployment_id`	string
`playbook_ids`	string[]	1–10

{ "using": ["Computer-use agents"] }

`get_person` · read-only

Who someone is on the customer side (role, stance, notes) and their most recent words, quoted. Arguments: deployment_id, name.

`get_thread` · read-only

The whole Slack thread a message belongs to, oldest first (up to 50 messages). Arguments: deployment_id, document_id (a Slack search hit).

`run_command` · read-only

The prompt for a command this customer’s plan adds (listed in the briefing under “Commands for this customer”), or one of the four defaults. Arguments: deployment_id, name.

`list_feeds` · read-only

Which connected tools feed this deployment, and, for Slack channels or Linear projects, only the ones that look like this customer’s. For a tool the workspace hasn’t connected, it returns a connect_url for the person to click. Arguments: deployment_id.

`add_feed`

Feeds channels or projects into this deployment, by id or name (#acme-ops). History starts arriving at once. Arguments: deployment_id, provider (slack, linear, …), values.

Staying current

When the plan changes or new sources arrive during a session, deployment tool results end with one line: “Since your briefing: plan updated, 2 new sources. Call what_changed.”

Prompts

The server also serves the four commands as MCP prompts (requirements, what-changed, check-plan, demo-check); in Claude Code they appear as /mcp__openscaffold__<name>.

Get started

For coding agents

Reference

Workspace tools

`list_deployments` · read-only

`use_deployment`

`create_deployment`

`add_document`

`add_documents`

`generate_harness`

Deployment tools

`get_briefing` · read-only

`search` · read-only

`get_document` · read-only

`get_plan` · read-only

`get_profile` · read-only

`get_playbooks` · read-only

`what_changed` · read-only

`propose_change`

`record_decision`

`record_conversation`

`propose_playbook_entries`

`report_session`

`request_review`

`get_review` · read-only

`get_test_scenarios` · read-only

`answer_question`

`decide_change`

`mark_done`

`use_playbooks`

`get_person` · read-only

`get_thread` · read-only

`run_command` · read-only

`list_feeds` · read-only

`add_feed`

Staying current

Prompts

​Workspace tools

​list_deployments · read-only

​use_deployment

​create_deployment

​add_document

​add_documents

​generate_harness

​Deployment tools

​get_briefing · read-only

​search · read-only

​get_document · read-only

​get_plan · read-only

​get_profile · read-only

​get_playbooks · read-only

​what_changed · read-only

​propose_change

​record_decision

​record_conversation

​propose_playbook_entries

​report_session

​request_review

​get_review · read-only

​get_test_scenarios · read-only

​answer_question

​decide_change

​mark_done

​use_playbooks

​get_person · read-only

​get_thread · read-only

​run_command · read-only

​list_feeds · read-only

​add_feed

​Staying current

​Prompts

Workspace tools

`list_deployments` · read-only

`use_deployment`

`create_deployment`

`add_document`

`add_documents`

`generate_harness`

Deployment tools

`get_briefing` · read-only

`search` · read-only

`get_document` · read-only

`get_plan` · read-only

`get_profile` · read-only

`get_playbooks` · read-only

`what_changed` · read-only

`propose_change`

`record_decision`

`record_conversation`

`propose_playbook_entries`

`report_session`

`request_review`

`get_review` · read-only

`get_test_scenarios` · read-only

`answer_question`

`decide_change`

`mark_done`

`use_playbooks`

`get_person` · read-only

`get_thread` · read-only

`run_command` · read-only

`list_feeds` · read-only

`add_feed`

Staying current

Prompts