Skip to content

Claude Code

Connect Claude Code to the SpecsGraph MCP server with claude mcp add, choose a local, project or user scope, and check the connection with /mcp.

Before you start

  • Claude Code installed and signed in.
  • A SpecsGraph account in an organisation, with the Editor role or above if the agent should stage changes. A Viewer's agent reads, comments and asks questions.
  • The SpecsGraph MCP URL, https://mcp.specsgraph.io/mcp; see The MCP URL.
  • A terminal open in the repository you want the agent to work in.

Add the server

  1. Add the server

    Run this from the root of your repository. It registers the SpecsGraph MCP server over HTTP, with no token.

    Shell
    claude mcp add --transport http specsgraph https://mcp.specsgraph.io/mcp
  2. Sign in

    Start a Claude Code session and run /mcp. Choose specsgraph, then Authenticate. Your browser opens SpecsGraph; pick the organisation, access and projects, and choose Allow.

Note

Claude Code's own documentation is the authority on its commands and flags. The examples here reflect Claude Code at the time of writing.

Choose a scope

Claude Code keeps MCP servers at one of three scopes. Pass --scope to pick one; without it, the server is added at local scope.

ScopeFlagStored inUse it when
Local--scope localYour user configuration, for this project onlyYou are trying SpecsGraph, or only you use it in this repository.
Project--scope project.mcp.json at the repository root, committedThe whole team uses SpecsGraph in this repository.
User--scope userYour user configuration, for every projectYou use SpecsGraph across many repositories.

Share the server with your team

For project scope, commit a .mcp.json file. With sign-in it holds only the URL, so it is safe to commit, and each teammate signs in from /mcp with their own account. Claude Code asks each person to approve servers from a project .mcp.json the first time they start a session in the repository.

.mcp.jsonJSON
{
  "mcpServers": {
    "specsgraph": {
      "type": "http",
      "url": "https://mcp.specsgraph.io/mcp"
    }
  }
}

Use a personal access token instead

For CI or a machine without a browser, create a personal access token and send it in a header. Your shell expands $SPECSGRAPH_TOKEN before Claude Code sees it, so Claude Code stores the value in its own configuration on your machine. To rotate, run claude mcp remove specsgraph and add the server again.

Shell
claude mcp add --transport http specsgraph https://mcp.specsgraph.io/mcp \
  --header "Authorization: Bearer $SPECSGRAPH_TOKEN"

Warning

Do not combine project scope with a shell-expanded header

Running the command above with --scope project writes your actual token into .mcp.json. For a shared file with tokens, write "Authorization": "Bearer ${SPECSGRAPH_TOKEN}" under headers by hand; Claude Code expands the variable when it loads the file, so each teammate connects with their own token.

Check the connection

Inside a Claude Code session, run /mcp. It lists your servers with their status. specsgraph should show as connected; select it to see its 52 tools, starting with project_list. From a regular shell, claude mcp list shows the same status and claude mcp get specsgraph shows one server's details.

Skip prompts for read tools

Claude Code asks before it calls an MCP tool. Read tools only fetch data, so many teams allow them up front and keep the prompt for write tools. Add rules to .claude/settings.json (the web app's Connect an agent panel generates this list from the server's catalogue):

.claude/settings.jsonJSON
{
  "permissions": {
    "allow": [
      "mcp__specsgraph__project_list",
      "mcp__specsgraph__spec_schema",
      "mcp__specsgraph__spec_get",
      "mcp__specsgraph__workstream_list",
      "mcp__specsgraph__workstream_get",
      "mcp__specsgraph__workstream_listChanges",
      "mcp__specsgraph__task_list",
      "mcp__specsgraph__task_get",
      "mcp__specsgraph__proposal_get",
      "mcp__specsgraph__thread_list",
      "mcp__specsgraph__artefact_list",
      "mcp__specsgraph__artefact_get",
      "mcp__specsgraph__member_list",
      "mcp__specsgraph__work_item_next",
      "mcp__specsgraph__build_status",
      "mcp__specsgraph__roadmap_get"
    ]
  }
}

Install the SpecsGraph skills

The optional SpecsGraph skills teach Claude Code when to read the spec, what to ask before it changes anything and how to stage a proposal the team will accept. They ship as a Claude Code plugin. Inside a session, add the marketplace and install the plugin:

Text
/plugin marketplace add SpecsGraph/specsgraph-skills
/plugin install specsgraph

Tell Claude Code to consult SpecsGraph first

Claude Code reads CLAUDE.md at the start of every session. A short section there makes the agent look up the spec before it writes code, without you naming the server in every prompt. If your repository already has an AGENTS.md, put the section there and add a line with @AGENTS.md to CLAUDE.md.

CLAUDE.mdMarkdown
## Specs live in SpecsGraph

This repository's spec (bounded contexts, aggregates, use cases, features, glossary terms) is in
SpecsGraph, available through the `specsgraph` MCP server. Main is the spec that shipped; a workstream
(WS-3) holds the spec in flight until one of its tasks publishes.

Before you change behaviour, read first:
1. `project_list` to find the project, then `spec_get` for the documents you touch (selector `kind/Name`):
   `scope: workstream:WS-n` while the spec is in flight in that workstream, `scope: main` for what shipped.
2. `workstream_list` and `workstream_listChanges` to see what a workstream already changes.
3. `task_list` and `thread_list` for the task and the review threads (open questions) you are working on.

When behaviour changes:
- Stage the spec change with `spec_apply` into the workstream. It lands in a proposal that a person
  reviews: accepted into the workstream; Main after a task publishes. In a project with Agent autonomy on, it is
  written to the workstream directly, and you may accept, route and submit tasks as Ready yourself.
- One small proposal per change. Do not treat an open proposal as final; read the workstream, not Main,
  for what was accepted.
- People publish a task; publishing moves it on and the landing marks it done.
- Cite display ids such as WS-3 and T-4 (or the task's tracker key, such as KAN-43) in commit
  messages and pull request descriptions.

When you implement agreed work (work items):
1. `work_item_next` for the ready items you may take, then `work_item_claim` the one you start.
2. `spec_get` at the item's `read.scope` for exactly what was agreed, then implement it.
3. Open a pull request whose title names the item, such as T-12.1, and link it with `work_item_update` (`codeRef`).
4. Send `work_item_update` with `heartbeat` within 2 hours while you work, or your claim lapses; `release` it if you stop.
- Stuck on the spec? Ask with `thread_ask` on the item (`item`, `blocking: true`). The merge, not you, marks the item done.

Example prompts

GoalPrompt
Get context before coding"Read the Ordering bounded context and the Reserve stock use case from SpecsGraph (spec_get on Main) and summarise them before you touch the checkout code."
Stage a change"In WS-3, stage a change to the Reserve stock use case: release reservations after 15 minutes idle. Add a scenario to the Checkout feature for an idle cart."
Answer review feedback"Read the threads in WS-3 (thread_list), revise the staged documents they question with spec_apply and reply in each thread."
Check impact"List the artefacts on Main that mention Reservation (artefact_list with q) and tell me which ones this diff affects."

Next steps