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.
  • Your SpecsGraph server's MCP URL. The examples use https://specsgraph.example.com/mcp; see Find your server's MCP URL.
  • A personal access token in the SPECSGRAPH_TOKEN environment variable of the shell you use.
  • A terminal open in the repository you want the agent to work in.

Add the server

Run this from the root of your repository, with your server's MCP URL in place of the example. It registers the SpecsGraph MCP server over HTTP and sends your token in the Authorization header.

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

Your shell expands $SPECSGRAPH_TOKEN before Claude Code sees it, so Claude Code stores the token value in its own configuration on your machine. When you rotate the token, run claude mcp remove specsgraph and add the server again.

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 that refers to the token variable instead of containing it. Claude Code expands environment variables in this file when it loads, so each teammate connects with their own token.

.mcp.jsonJSON
{
  "mcpServers": {
    "specsgraph": {
      "type": "http",
      "url": "https://specsgraph.example.com/mcp",
      "headers": {
        "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, a file you are about to commit. Write the file by hand as shown instead.

Claude Code asks each person to approve servers from a project .mcp.json the first time they start a session in the repository.

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 tools. From a regular shell, claude mcp list shows the same status and claude mcp get specsgraph shows one server's details.

If the server shows as failed, check that SPECSGRAPH_TOKEN was set in the shell where you ran claude mcp add. An empty variable produces a header with no token and every request is rejected. Other MCP clients has a troubleshooting table for other errors.

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:

.claude/settings.jsonJSON
{
  "permissions": {
    "allow": [
      "mcp__specsgraph__get_project_overview",
      "mcp__specsgraph__list_contexts",
      "mcp__specsgraph__get_context",
      "mcp__specsgraph__search_graph",
      "mcp__specsgraph__get_requirement",
      "mcp__specsgraph__list_glossary_terms",
      "mcp__specsgraph__list_actors",
      "mcp__specsgraph__list_workstreams",
      "mcp__specsgraph__get_workstream",
      "mcp__specsgraph__list_decisions",
      "mcp__specsgraph__get_proposal"
    ]
  }
}

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.

CLAUDE.mdMarkdown
## Specs live in SpecsGraph

Requirements, domain terms and design decisions for this repository are in
SpecsGraph, available through the `specsgraph` MCP server.

- Before you change behavior, read the relevant context and its requirements
  with the specsgraph tools. Active requirements are the source of truth.
- Use glossary terms from SpecsGraph in code, tests and proposals.
- If a change alters behavior, propose the spec change in SpecsGraph and mention
  the proposal branch in your summary. A proposal is not part of the spec
  until a person approves it and its pull request is merged.
- Reference requirement IDs such as ORD-12 in commit messages.

If your repository already has an AGENTS.md for other clients, put the section there and add a line with @AGENTS.md to CLAUDE.md so Claude Code imports it.

Example prompts

GoalPrompt
Get context before coding"Read the Orders context from SpecsGraph and summarize ORD-12 and ORD-13 before you touch the checkout code."
Draft a requirement"Propose a requirement in Orders: release reservations after 15 minutes idle. Add scenarios for an idle cart and for a cart that completes checkout in time."
Answer review feedback"Read the review threads on the proposal for spec/checkout-reserve, revise the scenarios they question and reply in each thread."
Check impact"Search SpecsGraph for requirements that mention Reservation and list the ones this diff affects."

Next steps