Connect an agent
Connect Claude Code, Cursor, Codex, GitHub Copilot or any MCP client to SpecsGraph so your agent reads the spec and stages changes for review.
What an agent does with SpecsGraph
A coding agent connected to SpecsGraph works from the same spec as the rest of your team. It uses that connection in four ways:
- Reads for context. Before it changes checkout code, the agent reads the Ordering bounded context, the Reserve stock use case and the Reservation glossary term (
project_list, thenspec_getwith akind/Nameselector): from the workstream it works in (scopeworkstream:WS-n) while the spec is in flight, from Main for what shipped. It builds against what the team agreed instead of guessing intent from the code. - Stages changes. When the work changes behaviour, the agent stages the changed documents into a workstream with
spec_apply. They land in a proposal that a person reviews: accepted into the workstream; Main after a task publishes. The agent groups them into plans, one per task it proposes. - Works the tasks and threads. The agent lists the tasks of a workstream (
task_list), opens, describes and assigns tasks (task_open,task_assign), reads review threads (thread_list), replies in them (thread_reply) and asks people questions (thread_ask). Marking a task Ready is a person's act, unless the project has Agent autonomy on. - Builds what was agreed. The agent takes a ready work item with
work_item_nextandwork_item_claim, codes against the agreed spec and names the item, such asT-12.1, in its pull request; the merge marks the item done. It reads what is built withbuild_statusand what comes next withroadmap_get.
You do not need a plugin or an extension. SpecsGraph runs a remote MCP server, and any client that supports the Model Context Protocol over streamable HTTP can connect to it. Once connected, the optional SpecsGraph skills add guided modeling workflows on top.
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 the grant of an agent sign-in or your personal access token. The server checks it, your role and the projects you chose, then runs the tool inside your organisation.
Agent client (Claude Code, Cursor, Codex, ...)
|
| MCP over streamable HTTP
| POST https://mcp.specsgraph.io/mcp
| Authorization: Bearer <token from sign-in, or a personal access token>
v
SpecsGraph MCP server: checks the token, your role and projects
|
+-> read tools -> Main, workstreams, changes, tasks, proposals, threads,
| work items, build status, roadmap
+-> write tools -> proposals (staged revisions and plans), tasks, threads,
claims on work items
|
v
A person accepts the revisions in the web app
(or the agent itself, with Agent autonomy on)
|
v
A task publishes the change to Main (and to git when connected)
|
v
Its work items track the code: a merge, a deployment, a resultAuthentication and permissions
There are two ways to authenticate. Both stand in for you, so the agent acts with your current role and never more. Sign-in and access tokens covers both in detail.
- Sign in with OAuth (recommended). Clients that support MCP sign-in find it on their own: the first request gets
401with a pointer to SpecsGraph, the client opens your browser, and you allow the agent on a consent page. There is no token to copy or store. You choose the organisation, the access level and the projects there, and you can revoke the agent at any time in Settings, then Access tokens, then Signed-in agents. - Personal access token. For clients without MCP sign-in, and for scripts. Create a token in Settings, then Access tokens and send it in the
Authorizationheader. Tokens start withsgp_.
What the agent may do follows your role, narrowed by the access and projects you chose:
- If you are a Viewer, your agent can read the spec, open or reply in review threads and ask questions.
- If you are an Editor or above, your agent can also stage spec changes and plans, open workstreams and tasks, start its tasks, and claim work items.
- The access narrows this further: Read only access cannot stage anything, and an agent allowed one project cannot see the others.
- No role and no token lets an agent publish a task, record a verify or uat result, mark a work item done or edit the work items of a task, mark code as implemented, change the roadmap, or change project, organisation or account settings. Those are web app actions for people, and the server lists no tool for them.
- With Agent autonomy off, an agent never can accept a revision or a plan, choose what a task covers, submit a task as Ready, mark a task done, answer a question, resolve a thread, discard a change, resolve a conflict directly, or complete or abandon a workstream. With it on (an Admin turns it on in Project settings), an agent with Read and write access can, and writes the workstream directly; see Agent autonomy.
Note
Write tools never publish
spec_apply stages documents into the open proposal of a workstream, opening one when needed. Nothing is written until a person accepts it: accepted into the workstream; Main after a task publishes. With Agent autonomy on, the agent writes the workstream directly instead, and Main still moves only when a person publishes a task. The tools proposal_discard, workstream_abandon, workstream_discardChange and task_abandon are marked destructive, because they withdraw or end work. The MCP tool reference lists all 52 tools.
Agent autonomy
Agent autonomy is a project setting for teams that let agents run the review and task flow on their own. An Admin turns it on or off in Project settings. New projects start with it on; projects created before it existed start with it off.
- On. An agent with Read and write access does what a person does in review:
spec_applyand the workstream edits write the workstream directly (passstage: trueto stage for review anyway), andproposal_accept,workstream_complete,workstream_abandon,workstream_discardChange,workstream_resolveConflict,task_route,task_submitReady,task_markDone,thread_resolveandthread_answertake a person's acts.proposal_acceptaccepts staged revisions and, in the same call, can route them into a new or existing task, assign it and submit it as Ready.task_opentakes the changes to scope. - Off. Everything works as described elsewhere on this page: the agent stages, and a person accepts, scopes, marks Ready and resolves. Those tools answer
person-requiredwith a message that names the setting. - Either way. Publishing a task stays a person's act, as do settings, verify and uat results, the work items of a task, marking code as implemented and the roadmap. Everything an agent writes is attributed to it (an Agent badge with the client's name), so the history shows who did what. Read only access never writes.
Connect as many clients as you like. Each sign-in and each token is listed separately, so you can revoke one without touching the others. Agents never count as seats.
Supported 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. The web app's Connect an agent panel (Settings, then Access tokens) shows the same snippets, ready to copy.
Connect in four steps
Add the server to your client
Register
https://mcp.specsgraph.io/mcpunder the namespecsgraph. The client guides above have the exact command, file or settings screen.Sign in and allow the agent
Your client opens
app.specsgraph.ioin the browser. Sign in if needed, pick the organisation, the access level and the projects, and choose Allow. For a client without sign-in, create a personal access token and put it in theAuthorizationheader instead.Check the connection
Your client should show
specsgraphas connected and list 52 tools, starting withproject_list. With a token, Test connection in the token created dialog runs the same check from your browser.Tell the agent to use it
Add a few lines to your repository's agent instructions (
CLAUDE.md,AGENTS.md, a Cursor rule) so the agent reads SpecsGraph before it writes code. Working well with agents has the snippet.
The MCP URL
SpecsGraph is hosted, so every organisation uses the same MCP URL: https://mcp.specsgraph.io/mcp. Your sign-in or token tells SpecsGraph who you are and which projects the agent may reach, so there is no per-organisation address to look up. Settings, then Access tokens shows it too.
Next steps
- Sign-in and access tokens: allow, scope, rotate and revoke agent access.
- Claude Code: connect Claude Code in one command.
- MCP tool reference: every tool an agent can call.
- Agent skills: install guided workflows for modeling, features and existing codebases.
- Context engineering: why one shared, reviewed context makes every agent more useful.