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
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/mcpSign in
Start a Claude Code session and run
/mcp. Choosespecsgraph, 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.
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.
{
"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.
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):
{
"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:
/plugin marketplace add SpecsGraph/specsgraph-skills
/plugin install specsgraphTell 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.
## 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
Next steps
- Working well with agents: habits that keep proposals small and easy to review.
- MCP tool reference: what each tool reads or stages.
- Agent skills: what each of the five skills does and how to ask for it.