Skip to content

MCP tool reference

Reference for every SpecsGraph MCP tool: the read tools agents use for context, the write tools that open proposals, and a sample get_requirement call.

How the tools are grouped

The SpecsGraph MCP server exposes 17 tools in two groups. Read tools return parts of the model and never change anything. Write tools add work to the review flow: proposals, thread replies, draft decisions and task updates.

Every call runs with the permissions of the token's owner, limited by the token's access level and projects. A tool the token cannot use fails with an error that names the missing access, and nothing changes. Some clients show it as an HTTP 403.

Read tools

Available to every token. Agents usually start with get_project_overview to orient themselves, then narrow down with get_context or search_graph.

ToolWhat it returnsMain inputs
get_project_overviewSummarize the project: contexts, relationships, open proposals and active workstreams.None
list_contextsList bounded contexts with their key, subdomain type and owning team.None
get_contextReturn one context with its services, requirements, glossary terms and relationships.A context key, such as ORD
search_graphSearch contexts, requirements, glossary terms and decisions by text.Search text, optionally limited to one context or one kind of node
get_requirementReturn one requirement with its scenarios, state and revision history.A requirement ID, such as ORD-12
list_glossary_termsList glossary terms, optionally filtered to one context.Optionally, a context key
list_actorsList the people, systems and agents that interact with the system.Optionally, a context key
list_workstreamsList workstreams with their number, status and open tasks.Optionally, a workstream status
get_workstreamReturn one workstream with its tasks and linked proposals.A workstream number, such as WS-3
list_decisionsList recorded decisions, newest first.None
get_proposalReturn a proposal with its diff, status and review threads.The proposal's branch, such as spec/checkout-reserve

Write tools

Need a Read and write token. The token owner's role still applies: a Viewer can reply in threads, while opening proposals, drafting decisions and updating tasks need Editor or above.

ToolWhat it doesMain inputs
propose_requirementDraft a new requirement, a change to one or its retirement, including its scenarios.The context, the title, statement and scenarios, and the ID when changing or retiring a requirement
propose_termAdd a glossary term or refine an existing definition.The term, its definition, its scope and any aliases to avoid
propose_structure_changeAdd, rename, move or reclassify contexts, services and relationships.The contexts, services or relationships to add or change
comment_on_proposalReply in an existing review thread on a proposal.The proposal's branch, the thread and the reply
record_decisionDraft a decision entry and link it to a proposal or requirement.The title, the context section, the decision and its consequences, and the requirements it explains
update_taskCreate a task in a workstream or change a task's status.A workstream number, the task title and the new status

Write tools never publish

Tools that change the model, such as propose_requirement, propose_term, propose_structure_change and record_decision, open a new proposal or add to one that is still under review. The proposal appears in Reviews with the agent shown as author and a branch under spec/, for example spec/checkout-reserve.

  • No tool approves, publishes or merges. A person approves in the web app, SpecsGraph opens a pull request, and merging it publishes the change.
  • comment_on_proposal only adds replies to threads on an existing proposal.
  • update_task changes workstream tasks, which track the work. It never changes requirements, terms or structure.

Open or extend a proposal

A proposal is referred to by its branch, such as spec/checkout-reserve. A proposal tool call that names a proposal still in Open or Changes requested adds to it; a call that names none opens a new one. Keep extending the same proposal across several calls, so one piece of work arrives as one proposal for review. Once a proposal is Approved, it takes no more changes, so a follow-up opens a new one.

Example: get_requirement

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 field names are illustrative. 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": "get_requirement",
    "arguments": { "id": "ORD-12" }
  }
}
Example structured result (illustrative)JSON
{
  "id": "ORD-12",
  "title": "Reserve stock for every line item at checkout",
  "context": { "key": "ORD", "name": "Orders" },
  "state": "active",
  "revision": 3,
  "terms": ["Reservation", "Line item", "Checkout"],
  "actors": ["Customer"],
  "background": ["Given the Catalog has 5 units of \"Trail mug\" in stock","And the Catalog has 1 unit of \"Canvas tote\" in stock"],
  "scenarios": [
    {
      "name": "Every line item gets a reservation",
      "steps": [
        "Given a Customer has a cart with 2 \"Trail mug\" and 1 \"Canvas tote\"",
        "When the Customer starts checkout",
        "Then a reservation holds 2 \"Trail mug\" for the order",
        "And a reservation holds 1 \"Canvas tote\" for the order",
        "And the Catalog shows 3 units of \"Trail mug\" available"
      ]
    }
  ],
  "related": ["ORD-13", "BIL-04"],
  "history": [
    { "revision": 3, "proposal": "spec/checkout-reserve", "publishedAt": "2026-09-14T10:32:00Z" }
  ]
}

Alongside the structured result, the server returns the same requirement as readable text, so clients that ignore structured content still get something the model can use.

Tool versions

Your client asks the server for its tool list each time it connects, so the list always matches the SpecsGraph version you are talking to. Your install offers the tools of the version it runs, which can differ from this page until you upgrade.

New tools and new optional fields appear after your client reconnects. Renamed or removed tools are listed in the release notes (opens in a new tab). Pin tool names in permission rules and instructions with that in mind.

Next steps