Skip to content

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

  • project is a project key, such as ORD, or projectId its id, on every tool except project_list and spec_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, 3 or the id, tasks as T-4, 4, the id or a tracker key such as KAN-43, work items as T-12.1, 12.1, the id or a tracker key, and milestones as M-3, 3, the id or a tracker key.
  • List tools page with cursor and limit: pass the nextCursor of an answer back as cursor. mode chooses a summary or every field, and maxBytes bounds 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.

ToolWhat it returnsMain inputs
project_listList the projects the connection can reach, with their key, name and whether they are archived. Call it first.Optionally search text, sort order and archived
spec_schemaReturn the JSON Schema of spec format 1, with one definition per artefact kind.None
spec_getRead spec documents as YAML, one per artefact, each with the id and revision a later edit must send back. Read workstream:WS-3 while the spec is in flight; Main holds what shipped.Optionally a scope (main, workstream:WS-3 or proposal:<id>) and selectors: a kind, kind/Name or an id
workstream_listList workstreams (WS-n) with their state and the number of changes no task covers yet.Optionally the states to list
workstream_getRead one workstream: title, description, goals, out of scope, state, task counts and its open proposal.A workstream, such as WS-3
workstream_listChangesList what a workstream changed against Main: each artefact added, modified or archived, its task and any conflict.A workstream; optionally all changes, kinds, sort order and the field-level diff
task_listList tasks (T-n) with their state and workstream, newest first.Optionally a workstream, states or search text
task_getRead one task: description, state, tracker key, workstream, the artefacts in its scope, its publication state, the actions allowed, and its work items, flow (standard or hotfix) and delivery.A task, such as T-4, or a tracker key such as KAN-43
proposal_getRead a proposal: its state, the revisions staged in it and what blocks each one, optionally with each document and its diff.A proposal id, or a workstream for its open proposal; optionally the diff
thread_listList the threads of a workstream, of Main or of a work item with their comments and kind (comment, question, change request or conflict), open threads by default.A workstream, main or a work item; optionally status, an artefact, search text, a kind and answered since
artefact_listList the artefacts of a scope, filtered by kind, bounded context, text, state against Main or archived.Optionally a scope, kinds, a context, search text and states
artefact_getRead one artefact: its document as JSON and YAML, revision, state against Main and thread counts.An artefact id; optionally a scope
member_listList the people of the organisation (user id, name, email, role), to pick the assignee of a task.Optionally search text
work_item_nextList the ready implement, docs, regression and other items you may take, yours first, each with the scope to read the spec at. With nothing ready, it answers the roadmap's Up next.Optionally a task, a kind, a limit (1 to 10) and includeNextUp
build_statusRead the derived build status of artefacts on Main (not started, planned, in dev, merged, on an environment, verified, outdated, rolled back), with the work item that delivered each one.Optionally states, kinds, a context or feature (id or name), a milestone, an environment or artefact ids
roadmap_getRead the open milestones in order, each with its progress, phase, target date and warnings, and how many buildable artefacts no milestone plans. Read only: people create and order milestones.Optionally a milestone (M-3, its id or tracker key) for its detail, and closed or dropped

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.

ToolWhat it doesMain inputs
spec_applyStage spec documents as revisions in the open proposal of a workstream, opening one if needed, optionally into a plan for one task. A person accepts them into the workstream; Main after a task publishes. With Agent autonomy on, the documents are written to the workstream directly unless you ask to stage them.A workstream and the documents, as JSON or YAML; optionally a plan (label, task and work items), stage, prune and a dry run
proposal_openOpen the proposal of a workstream, where staged revisions wait for review.A workstream
proposal_readyMark the open proposal Ready, telling the people of the workstream it is worth reviewing.A proposal and the revision counter you read
proposal_finishClose a proposal once every revision in it has been accepted or withdrawn.A proposal and the revision counter you read
proposal_discard (destructive)Discard the open proposal and its pending revisions. Refused while another agent or a person has pending revisions in it.A proposal and the revision counter you read
proposal_withdrawWithdraw one pending revision you staged.A proposal, the revision id and the revision counter you read
proposal_planCreate a plan in the open proposal, or change its task. A plan groups staged revisions that a person accepts together into one task: a new Draft task, or an open task of the workstream. It can name the work items the task gets at Ready.A proposal, a label and the task: a new one (name, optionally description and tracker key) or an existing one by number; optionally work items
proposal_assignMove pending revisions you staged into a plan of the proposal, or out of every plan.A proposal, the revision ids and a plan label, or null
proposal_acceptAccept staged revisions into the workstream: some, all, or a plan as a group. In the same call, route them into a new or existing task, assign it and submit it as Ready. Needs Agent autonomy.A proposal and revision ids, all, or a plan id; optionally a task or a new task, an assignee and ready
workstream_openOpen a new workstream (WS-n) in the project, optionally linked to a tracker issue and with its first Draft task.A title; optionally a tracker key and a first task
workstream_renameStage a new title for a workstream. It changes when a person accepts the revision, or at once with Agent autonomy on.A workstream, the version you read and the new title
workstream_editDescriptionStage a new description for a workstream. It changes when a person accepts the revision, or at once with Agent autonomy on.A workstream, the version you read and the whole description
workstream_editGoalsStage the goals of a workstream. They change when a person accepts the revision, or at once with Agent autonomy on.A workstream, the version you read and the whole list of goals
workstream_editOutOfScopeStage the out-of-scope notes of a workstream. They change when a person accepts the revision, or at once with Agent autonomy on.A workstream, the version you read and the whole list of notes
workstream_completeComplete a workstream whose tasks are done or abandoned, optionally discarding the changes no task covers. Needs Agent autonomy.A workstream; optionally discard unrouted changes
workstream_abandon (destructive)Abandon a workstream and its open tasks; what it changed never reaches Main. It cannot be undone. Needs Agent autonomy.A workstream and a reason
workstream_discardChange (destructive)Put one changed artefact of a workstream back to its Main version. Needs Agent autonomy.A workstream and the artefact id; optionally the revision you read
workstream_resolveConflictResolve a conflict directly: keep Main, keep the workstream, or write the merged document. Needs Agent autonomy.A workstream, the artefact id, the resolution and, for a merge, the document
task_openOpen a Draft task (T-n) in a workstream, optionally with an assignee. A person chooses what it covers and submits it as Ready, or the agent with Agent autonomy on.A workstream, a name and optionally a description, a tracker key, an assignee and (Agent autonomy) artefact ids
task_renameRename an open task.A task and the new name
task_editDescriptionReplace the description of an open task.A task and the whole description
task_startMove a Ready task to In progress. A Draft task waits to be submitted as Ready.A task
task_abandon (destructive)Abandon an open task. Its changes go back to the workstream, a publication in flight ends and its open pull request closes. It cannot be undone.A task and a reason
task_routeAdd changes of the workstream to a task's scope, or take them out, in one call. Needs Agent autonomy.A task and the artefact ids to add, to remove, or both
task_assignSet the person responsible for a task, or clear it.A task and a user id or email, or null
task_submitReadyMove a Draft task with a scope to Ready, recording its agreement. Needs Agent autonomy.A task
task_markDoneMark an In progress task done once its publication is published. Needs Agent autonomy.A task
task_resolveConflictStage the complete merged document of an artefact that conflicts with Main. The conflict is resolved when the revision is accepted. With Agent autonomy, workstream_resolveConflict resolves it directly.A workstream, the artefact id and the merged document
thread_openOpen a comment thread on an artefact in a workstream or on Main, or on a work item, to explain a change or raise a point.A workstream, main or a work item; an artefact id (unless a work item) and the comment; optionally the part of the document it is about
thread_askAsk a question about an artefact in a workstream or on Main, or about a work item you are stuck on, with answers to choose from, a person or team to ask and whether it blocks. A person answers it.A workstream, main or a work item; an artefact id (unless a work item) and the question; optionally the part of the document, two to six options, blocking, a person (askUser) and a team
thread_replyAdd a comment to an existing thread.A thread id and the comment
thread_reopenReopen a comment thread a person resolved. Only a person, or an agent with Agent autonomy on, reopens a question or a change request; a conflict thread is never reopened.A thread id
thread_resolveResolve an open thread; a question or change request closed this way ends as withdrawn. Needs Agent autonomy.A thread id
thread_answerAnswer an open question with one of its options, a text, or both. Needs Agent autonomy.A thread id and an option id, a text or both
work_item_claimClaim a ready implement, docs, regression or other item: it moves to doing and the claim lasts 2 hours unless you heartbeat. Deploy, verify and uat items are for CI and people.A work item: T-12.1, its id or its tracker key
work_item_updateKeep your claim for 2 more hours, record the pull request, or give the item back. Never marks it done: the merge of a pull request naming it, or a person, does.A work item you claimed and codeRef, heartbeat or release

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_ask and thread_reply only 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_claim and work_item_update hold and link a work item; a merge or a person completes it.
  • Tasks track the work. task_open, task_assign and task_start change tasks, never spec documents. task_start moves a Ready task to In progress; a successful publish starts a task too, and its landing marks it done.
  • Conflict merges are staged. task_resolveConflict stages 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 uses workstream_resolveConflict with 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_discard discards the open proposal and its pending revisions. It is refused with proposal-shared while another agent or a person has pending revisions in it; to take back one revision of your own, use proposal_withdraw.
  • task_abandon ends 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.

PromptWhat it doesArguments
read-then-proposeRead the relevant documents first, stage one small proposal and tell people what to review.A workstream and the goal; optionally a project
review-my-proposalCheck the open proposal of a workstream the way a reviewer would, and fix what you can before marking it ready.A workstream; optionally a project
pick-up-taskUnderstand a task, its scope and its workstream, start it and propose the spec work it needs.A task; optionally a project
resolve-conflictMerge the workstream and Main versions of one artefact into a document that keeps both intents.A workstream and the artefact id; optionally a project

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.

Example request (illustrative)JSON
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "spec_get",
    "arguments": { "project": "ord", "scope": "main", "selectors": ["use-case/Reserve stock"] }
  }
}
Example structured result (illustrative)JSON
{
  "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