MCP tool reference
Every SpecsGraph MCP tool: read tools for context and build status, write tools that stage revisions and plans, run tasks, threads and work items.
How the tools are grouped
The SpecsGraph MCP server exposes 52 tools in two groups: 16 read tools that return parts of the spec and never change anything, and 36 write tools that add work to the review flow (staged revisions and plans in a proposal, tasks, threads and questions) and claim work items. Every connection sees the same list; the web app's Connect an agent panel reads it too.
Every call runs inside your organisation with your permissions, limited by the access and projects you chose. A tool the connection cannot use fails with a tool error (code forbidden) that names the missing access and where to fix it, and nothing changes. The tools carry the standard MCP annotations: read tools are marked read-only, and proposal_discard, workstream_abandon, workstream_discardChange and task_abandon are marked destructive. Clients use these to decide when to ask you before a call.
Common inputs
projectis a project key, such asORD, orprojectIdits id, on every tool exceptproject_listandspec_schema. It is optional when the connection reaches one project. Reads without it read every project you allowed; writes must name one when you allowed several.- Every workstream, task and proposal in a result carries both its id and its display id. Tools accept workstreams as
WS-3,ws-3,3or the id, tasks asT-4,4, the id or a tracker key such asKAN-43, work items asT-12.1,12.1, the id or a tracker key, and milestones asM-3,3, the id or a tracker key. - List tools page with
cursorandlimit: pass thenextCursorof an answer back ascursor.modechooses a summary or every field, andmaxBytesbounds the size of an answer (64 KB by default). - Write tools take an optional
idempotencyKey. Repeating a call with the same key returns the stored result instead of acting twice, which is how an agent recovers from a cancelled call.
Read tools
Available to every connection, including Read only access and Viewers. Agents usually start with project_list, then read the documents they need with spec_get: from the workstream while the spec is in flight, from Main for what shipped.
Write tools
Need Read and write access and the Editor role or above, with exceptions for review: thread_open, thread_ask, thread_reply are open to every member and to Read only access, so any agent can take part in review. thread_reopen needs Read and write access. Every write returns the full object it changed.
Agent autonomy tools
proposal_accept, workstream_complete, workstream_abandon, workstream_discardChange, workstream_resolveConflict, task_route, task_submitReady, task_markDone, thread_resolve and thread_answer need Agent autonomy on the project and Read and write access; otherwise they answer person-required and nothing changes. task_assign and member_list work in every project. The fast path for an agent is one proposal_accept call with all (or revisionIds), a newTask, an assignee (a user id or email from member_list) and ready: true.
Plans
An agent groups what it stages into plans, one per task, that a person accepts as a group into that task in the Proposals page. spec_apply takes a plan with a label; the first call with a label also names the task, a new Draft task (name, description, tracker key) or an open task of the workstream by number. proposal_plan creates a plan or changes its task, and proposal_assign moves revisions you staged into a plan or out of every plan. Staging an artefact that is pending in another plan fails that document with artefact-staged-in-other-plan; move it with proposal_assign first.
A proposal completes itself once nothing in it is pending after an accept or a withdraw, and the next spec_apply opens a new one.
Questions
thread_ask asks the people of a workstream a question about an artefact, with two to six options to choose from and a person (askUser) or a team (askTeam) to ask. With blocking, a person cannot accept the revisions the agent staged on that artefact before the question is answered. With workstream: main it asks about an artefact of Main: it must name a person or a team, and cannot block. With item it asks about a work item the agent is stuck on, and blocking holds that item. thread_open and thread_list take workstream: main and item too. A person answers in SpecsGraph and the question resolves; the agent collects answers with thread_list and kind: "question" plus answeredSince. Threads carry their kind: comment, question, change_request or conflict. Threads and questions has the details.
Work items
An agent implements agreed work in a loop. work_item_next lists the ready implement, docs, regression and other items it may take, its own first, each with read.scope: the spec to code against, the workstream until the task is Done, then main. work_item_claim takes one and moves it to Doing. The claim lasts 2 hours; work_item_update with heartbeat: true keeps it, codeRef records the pull request and release: true gives the item back. Name the item, such as T-12.1, in the pull request title or branch, so its merge completes it.
Claims need Read and write access. Deploy, verify and uat items answer person-required: CI reports deployments and people record results. Other refusals name the reason: work-item-claimed when someone holds it, work-item-blocked when it waits on other work or a blocking question, work-item-not-claimed when the claim lapsed or another token holds it. No tool marks an item done, records a result or edits the items of a task. proposal_plan and the plan of spec_apply take workItems, the items the task gets at Ready, which a person accepts with the plan. Work items and delivery has the details.
Build status and the roadmap
build_status reads the derived build status of artefacts on Main, with the item that delivered each one, to find what still needs code or to check that a change reached an environment. roadmap_get reads the milestones in order, with their progress and warnings, or one milestone's artefacts. Both only read: people mark code as implemented and manage milestones. When nothing is ready, work_item_next answers the roadmap's Up next, and the agent proposes work with proposal_plan.
Write tools never publish
spec_apply and the workstream_edit* tools stage revisions into a proposal. The proposal appears in the workstream's Proposals page with the agent shown as author (an Agent badge with the client's name). Nothing reaches the workstream until a person accepts each revision, nor Main until a task publishes it. With Agent autonomy on, these tools write the workstream directly, and Main still waits for a person to publish.
- Some acts are for people only. No tool can publish a task, record a verify or uat result, mark a work item done or edit the work items of a task, mark code as implemented, change the roadmap, or change project, organisation or account settings. The server lists no such tool, whatever the access.
- Some acts need Agent autonomy. With Agent autonomy off, an agent never can accept a revision or a plan, choose what a task covers, submit a task as Ready, mark a task done, answer a question, resolve a thread, discard a change, resolve a conflict directly, or complete or abandon a workstream. With it on (an Admin turns it on in Project settings), an agent with Read and write access can, and writes the workstream directly; see Agent autonomy.
- Threads only add.
thread_open,thread_askandthread_replyonly add to review threads. Only a person reopens a question or a change request, or an agent with Agent autonomy on. - Agents claim, never complete.
work_item_claimandwork_item_updatehold and link a work item; a merge or a person completes it. - Tasks track the work.
task_open,task_assignandtask_startchange tasks, never spec documents.task_startmoves a Ready task to In progress; a successful publish starts a task too, and its landing marks it done. - Conflict merges are staged.
task_resolveConflictstages a complete merged document in the open proposal. The conflict is resolved when that revision is accepted; keeping one side as is stays a person's choice, or usesworkstream_resolveConflictwith Agent autonomy on.
Errors name what went wrong: proposal-changed when the revision counter you sent is stale, version-conflict on a workstream field, revision-conflict when Main moved under a staged document, rate-limited with retryAfterSeconds after 60 writes in a minute, and validation-failed with the path of each bad input.
Destructive tools
proposal_discarddiscards the open proposal and its pending revisions. It is refused withproposal-sharedwhile another agent or a person has pending revisions in it; to take back one revision of your own, useproposal_withdraw.task_abandonends a task for good. Its changes stay in the workstream, a publication in flight ends, and its open pull request closes. It cannot be undone.workstream_abandon(Agent autonomy only) abandons a workstream and its open tasks; what it changed never reaches Main.workstream_discardChange(Agent autonomy only) puts one changed artefact back to its Main version in the workstream.
Revisions and stale reads
Every document spec_get or artefact_get returns carries a revision. Send it back with spec_apply, so a concurrent edit is reported instead of overwritten. The proposal tools take the revision counter proposal_get reports, and the workstream edits take the version workstream_get reports, for the same reason.
Prompts
The server also offers prompts: short working procedures a client can insert, which tell the agent which tools to call in which order.
Example: spec_get
Your client builds these messages for you; you never write them by hand. They are shown here so you know what an agent receives. The input schema your client receives from tools/list is the authority.
{
"jsonrpc": "2.0",
"id": 7,
"method": "tools/call",
"params": {
"name": "spec_get",
"arguments": { "project": "ord", "scope": "main", "selectors": ["use-case/Reserve stock"] }
}
}{
"scope": "main",
"documents": [
{
"id": "0192f3a1-4c2e-7c8a-9d0b-6e5f4a3b2c1d",
"kind": "use-case",
"name": "Reserve stock",
"revision": "0192f3a1-5d3f-7e9b-8c1a-7f6e5d4c3b2a",
"document": "kind: use-case\nname: Reserve stock\nbounded-context: Ordering\nactor: Customer\nscenarios:\n - name: Every line item gets a reservation\n given: ...\n"
}
],
"notFound": [],
"truncated": false,
"nextCursor": null
}Alongside the structured result, the server returns the same documents as readable text, so clients that ignore structured content still get something the model can use. A result larger than maxBytes is cut at an item boundary and says so, with the cursor to continue from.
Tool versions
Your client asks the server for its tool list each time it connects, and SpecsGraph always runs the current release, so the list matches this page. Renamed or removed tools are listed in the release notes. Pin tool names in permission rules and instructions with that in mind: an agent instruction that still names a removed tool, such as one that submitted a task as Ready, should be dropped.
Next steps
- Proposals, plans and review: what reviewers see when an agent stages a revision or a plan.
- Working well with agents: use these tools in a way reviewers appreciate.
- Sign-in and access tokens: the access each tool needs.