Connect your AI coding agent to SpecsGraph over MCP

SpecsGraph keeps your team's living specification: bounded contexts, the glossary, roles, use cases, features with Given, When, Then scenarios, and the contracts between them. The SpecsGraph MCP server is how coding agents reach it. A connected agent reads the part of the spec it needs before it writes code, and proposes changes to the spec that a person then accepts.

This guide connects the agents teams use most: Claude Code, Claude on the web and desktop, and VS Code with GitHub Copilot. It also covers any other client that speaks the Model Context Protocol↗ (opens in a new tab). Each takes a few minutes.

Before you start#

You need a SpecsGraph account in an organization with at least one project. Then choose how the agent proves who it is.

Sign in (recommended). Add the server without a token. The first time the agent connects, it opens SpecsGraph in your browser. After you sign in, a consent page names the agent and asks which organization and projects it may use, whether it can only read or also propose changes, and how long the access lasts. The agent's access token lasts an hour and renews itself in the background. You can revoke a signed-in agent at any time under Settings, Access tokens, Signed-in agents.

Personal access token. Use a token for CI, remote machines, or clients that cannot sign in. In SpecsGraph, open Settings, Access tokens and choose Create token. Then set up the token:

• Name: the agent and the machine, such as claude-code-laptop.
• Expiry: 30 days, 90 days, 1 year or no expiry.
• Access: Read only, or Read and write.
• Projects: the ones it can reach.

Copy the token when it appears, because you will not see it again. Tokens start with sgp_, and SpecsGraph stores only a hash of each one. The access tokens guide has the details.

Keep the token out of files you commit. The examples below read it from an environment variable named SPECSGRAPH_TOKEN:

export SPECSGRAPH_TOKEN="sgp_..."

Claude Code#

With the SpecsGraph plugin#

The plugin adds the MCP server and the SpecsGraph agent skills in one step. Inside Claude Code, run:

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

Then run /mcp, select the SpecsGraph server and choose Authenticate to sign in.

Last, run /specsgraph:setup in your repository. It asks which project the repository belongs to. Once you approve the diff, it adds a short "Specs live in SpecsGraph" section to AGENTS.md, so every session starts from the spec. The skills are open source, and you can read them on GitHub↗ (opens in a new tab) before you install them.

Without the plugin#

Add the server from your terminal:

claude mcp add --transport http specsgraph https://mcp.specsgraph.io/mcp

Start Claude Code, run /mcp, select specsgraph and choose Authenticate. From a shell, claude mcp login specsgraph does the same.

To use a token instead, pass it as a header:

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

To share the setup with your team, commit a .mcp.json at the root of the repository. Claude Code expands the variable when it starts, so each person uses their own token. Leave out headers if your team signs in instead.

{
  "mcpServers": {
    "specsgraph": {
      "type": "http",
      "url": "https://mcp.specsgraph.io/mcp",
      "headers": { "Authorization": "Bearer ${SPECSGRAPH_TOKEN}" }
    }
  }
}

Check the connection with claude mcp list, which should show SpecsGraph as connected. Inside a session, /mcp lists its tools. The Claude Code guide in the docs covers every option.

Claude on the web and desktop#

Custom connectors connect SpecsGraph to claude.ai and to the Claude desktop app in one place:

1. Open Customize, Connectors and choose Add custom connector.
2. Name it SpecsGraph and enter https://mcp.specsgraph.io/mcp as the URL, exactly as written.
3. Choose Connect, sign in to SpecsGraph and allow access.

On Team and Enterprise plans, an Owner adds the connector under Organization settings, Connectors, and each member then connects their own account. The Free plan allows one custom connector. A connector you add here also shows up in Claude Code when you use it with the same Claude account. The Claude connector guide walks through the same steps.

VS Code with GitHub Copilot#

Add the server to .vscode/mcp.json in your workspace:

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

The first time the server starts, VS Code registers itself with SpecsGraph and opens your browser so you can sign in. To use a token instead, let VS Code prompt for it once and keep it in its secure storage:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "specsgraph-token",
      "description": "SpecsGraph access token",
      "password": true
    }
  ],
  "servers": {
    "specsgraph": {
      "type": "http",
      "url": "https://mcp.specsgraph.io/mcp",
      "headers": { "Authorization": "Bearer ${input:specsgraph-token}" }
    }
  }
}

Copilot calls the tools from chat in agent mode. On Copilot Business and Enterprise, an administrator must first enable the MCP servers in Copilot policy, which is off by default. MCP: List Servers in the Command Palette shows whether SpecsGraph is running. The GitHub Copilot guide has the full setup.

Other clients#

Any client that speaks MCP over streamable HTTP connects with the same URL. It either signs in, if it supports MCP authorization, or sends Authorization: Bearer <token>.

• Gemini CLI: gemini mcp add --transport http specsgraph https://mcp.specsgraph.io/mcp. It signs in on first use, and /mcp auth specsgraph signs in again.
• Windsurf, Zed and JetBrains Junie: add a remote server with the same URL in their MCP settings. Each of them can sign in, or send the header.
• Clients that only run local servers: bridge them with mcp-remote↗ (opens in a new tab), which signs in through your browser:

{
  "mcpServers": {
    "specsgraph": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.specsgraph.io/mcp"]
    }
  }
}

To send a token through mcp-remote, add "--header", "Authorization:${AUTH_HEADER}" to args, and set AUTH_HEADER to Bearer sgp_… in the server's env. Leaving out the space after the colon avoids a quoting bug in some clients. The docs cover more setups under other clients.

Check that it works#

Ask your agent something only SpecsGraph can answer:

List my SpecsGraph projects and the active workstreams in each.

The agent should call project_list and answer with the projects your sign-in or token can reach. If it cannot, the table under Troubleshooting matches the server's messages to their fixes.

What your agent can do#

The server describes each tool to your agent and says when to use it, so you rarely name a tool yourself. The tools fall into two groups:

• Reading. An agent can read the projects, the spec itself as YAML documents (one per artefact), artefacts by kind or context, and workstreams and what they changed. It can also read tasks, proposals and comment threads.
• Proposing. With Read and write access, an agent stages spec changes in the workstream's proposal and marks the proposal ready for review. It can also open and edit workstreams and tasks, and take part in comment threads.

Some decisions stay with people, and the server has no tool for them:

• accepting a staged revision
• resolving a thread
• scoping and publishing a task, and marking it done
• closing a workstream

An agent works with the role of the person who connected it. Every revision records who staged it and through which agent. That is how several agents and people share one model without stepping on each other.

The server also offers four prompts for common jobs: read then propose, review my proposal, pick up a task, and resolve a conflict. Each token or sign-in can make 600 requests and 60 writes a minute. Long results come back in pages that the agent follows. The MCP tool reference lists every tool and prompt.

Troubleshooting#

Once your agent is connected, the spec is the first thing it reads and the only place it proposes changes. To see where that leads, read how a living specification keeps people and agents working from the same agreement. If something in this guide does not match what you see, tell us on Discord↗ (opens in a new tab) or through support.