Skip to content

Connect an agent

Connect Claude Code, Cursor, GitHub Copilot or any MCP client to SpecsGraph so your agent reads the system graph and proposes spec changes for review.

What an agent does with SpecsGraph

A coding agent connected to SpecsGraph works from the same model of the system as the rest of your team. It uses that connection in three ways:

  • Reads for context. Before it changes checkout code, the agent pulls the Orders context, requirements such as ORD-12 and ORD-13, and the glossary term Reservation. It builds against what the team agreed instead of guessing intent from the code.
  • Proposes changes. When the work changes behavior, the agent drafts the requirement or scenario change as a proposal, for example on the branch spec/checkout-reserve. A person reviews it before it becomes part of the spec.
  • Answers review threads. Reviewers comment on the nodes of a proposal. The agent reads the threads, revises the proposal and replies.

You do not need a plugin or an extension. SpecsGraph runs an MCP server, and any client that supports the Model Context Protocol can connect to it.

How the connection works

Your agent client talks to the SpecsGraph MCP server over streamable HTTP, the remote transport defined by the MCP specification. Every request carries your personal access token. The server checks the token, your workspace role and the token scope, then runs the tool.

Request pathText
Agent client (Claude Code, Cursor, GitHub Copilot, ...)
   |
   |  MCP over streamable HTTP
   |  POST https://specsgraph.example.com/mcp
   |  Authorization: Bearer sgp_...
   v
SpecsGraph MCP server: checks token, role and scope
   |
   +-> read tools  -> system graph, glossary, decisions, workstreams
   +-> write tools -> proposals and review threads
                         |
                         v
          A person approves in the web app
                         |
                         v
          The GitHub App commits the spec and opens a pull request
                         |
                         v
          Merging the pull request publishes the change
SettingValue
Server URLYour SpecsGraph server's MCP URL, such as https://specsgraph.example.com/mcp
TransportStreamable HTTP
AuthenticationAuthorization: Bearer <token> header on every request
Token prefixsgp_
Server name used in these docsspecsgraph

Authentication and permissions

Each agent authenticates with a personal access token that you create in the web app. The token stands in for you, so the agent acts with your current workspace role and never more:

  • If you are a Viewer, your agent can read the graph and reply in review threads.
  • If you are an Editor or above, your agent can also open proposals, draft decisions and update workstream tasks.
  • The token scope can narrow this further: a Read only token cannot call write tools, and a token limited to one project cannot see the others.
  • No role and no token lets an agent approve, publish or merge. Approval is a web app action for people.

Note

Write tools never approve or publish

The proposal tools (propose_requirement, propose_term, propose_structure_change and record_decision) open or extend a proposal. comment_on_proposal replies in existing threads, and update_task changes workstream tasks right away. No tool approves, publishes or merges, and nothing reaches your repository until a person approves. The MCP tool reference lists every tool.

Connect as many clients as you like, each with its own token. The self-hosted edition does not count seats, and on SpecsGraph Cloud, which is coming soon, agents will not count as seats either.

Supported clients

ClientWhere the server is configuredGuide
Claude Codeclaude mcp add or a shared .mcp.jsonClaude Code
Cursor.cursor/mcp.json or ~/.cursor/mcp.jsonCursor
GitHub Copilot in VS Code.vscode/mcp.jsonGitHub Copilot
Any other MCP clientServer URL plus an Authorization header, or the mcp-remote bridgeOther MCP clients

Client configuration formats change between releases. The steps in these docs reflect each client at the time of writing, and the client's own documentation is the authority when the two disagree.

Connect in four steps

  1. Create a token

    In your SpecsGraph web app, open Account settings, then Access tokens and create a token for this client. Copy it into the SPECSGRAPH_TOKEN environment variable.

    Shell
    export SPECSGRAPH_TOKEN="sgp_paste-your-token-here"

  2. Add the server to your client

    Register your SpecsGraph server's MCP URL, such as https://specsgraph.example.com/mcp, under the name specsgraph with the Authorization header. The client guides above have the exact file or command.

  3. Check the connection

    Your client should show specsgraph as connected and list its tools, starting with get_project_overview.

  4. Tell the agent to use it

    Add a few lines to your repository's agent instructions so the agent reads SpecsGraph before it writes code. Working well with agents has a snippet you can copy.

Find your server's MCP URL

Your SpecsGraph server answers MCP requests at /mcp under SPECSGRAPH_PUBLIC_URL. These docs use an example install at https://specsgraph.example.com, so their examples show https://specsgraph.example.com/mcp. If your install sets SPECSGRAPH_MCP_PUBLIC_URL, use that value instead.

Replace the example URL with your own in every example on these pages, and create tokens on your own install. Configuration covers both variables.

Next steps