Claude (claude.ai and Claude Desktop)

Add SpecsGraph to Claude as a custom connector, sign in and allow it, then read your spec and stage changes from claude.ai and Claude Desktop.

The SpecsGraph connector lets Claude read the spec of your projects, follow workstreams, tasks and review threads, and stage spec changes for your team to accept. It connects to the SpecsGraph MCP server and signs in with your SpecsGraph account; there is no token to create.

Before you start

A Claude plan that supports custom connectors. On Team and Enterprise plans, an owner may need to add the connector for the organization first.
A SpecsGraph account in a workspace, with the Editor role or above if the agent should stage changes. A Viewer's agent reads and comments.
The SpecsGraph MCP URL, https://mcp.specsgraph.io/mcp; see The MCP URL.

Add the connector

Open the connector settings
In claude.ai or Claude Desktop, open Settings, then Connectors, and choose Add custom connector.
02
Enter the name and URL
Name it SpecsGraph and paste the server URL. Leave the advanced OAuth fields empty: Claude registers itself with SpecsGraph.
Text
```
Name: SpecsGraph
Remote MCP server URL: https://mcp.specsgraph.io/mcp
```
Connect and sign in
Choose Connect. Claude opens app.specsgraph.io in your browser. Sign in to SpecsGraph if you are not already.
Allow the connector
The consent page asks "Allow Claude to use SpecsGraph?". Check that it returns to claude.ai, then pick the workspace under Organisation, the expiry, the access (Read only, or Read and write to stage changes) and the projects. Choose Allow. The browser returns to Claude and the connector shows as connected.

Connectors you add in claude.ai are available in Claude Desktop with the same account, and the other way round. Turn the connector on for a conversation from the tools menu in the chat input.

Note

Claude's own help center is the authority on its settings screens and plans. The steps here reflect Claude at the time of writing.

What the connector can do

Read. 12 tools read projects, spec documents, artefacts, workstreams and their changes, tasks, proposals and threads. They never change anything.
Stage spec changes. spec_apply stages edited documents as revisions in the proposal of a workstream. Nothing reaches Main until a person accepts the revisions in the web app and publishes the work.
Plan and discuss. Tools that open workstreams and tasks, move a task to Ready or In progress, and open or reply to comment threads.
Never accept a revision, publish, mark a task done, resolve a thread or change settings. The server refuses those for every agent.

Claude asks before it calls a tool unless you allow it, and you can change that per tool in the connector's settings. Read-only tools are safe to allow. Look at the arguments of the two destructive tools, proposal_discard and task_abandon, before you approve them.

Tools

Tool	Behavior	What it does
`project_list`	Read only	List the projects the connection can reach, with their key, name and whether they are archived. Call it first.
`spec_schema`	Read only	Return the JSON Schema of spec format 1, with one definition per artefact kind.
`spec_get`	Read only	Read spec documents as YAML, one per artefact, each with the id and revision a later edit must send back.
`workstream_list`	Read only	List workstreams (WS-n) with their state and the number of changes no task covers yet.
`workstream_get`	Read only	Read one workstream: title, description, goals, out of scope, state, task counts and its open proposal.
`workstream_listChanges`	Read only	List what a workstream changed against Main: each artefact added, modified or archived, its task and any conflict.
`task_list`	Read only	List tasks (T-n) with their state and workstream, newest first.
`task_get`	Read only	Read one task: description, state, workstream, the artefacts in its scope, its publication state and the actions allowed.
`proposal_get`	Read only	Read a proposal: its state, the revisions staged in it and what blocks each one, optionally with each document and its diff.
`thread_list`	Read only	List the comment threads of a workstream with their comments, open threads by default.
`artefact_list`	Read only	List the artefacts of a scope, filtered by kind, bounded context, text, state against Main or archived.
`artefact_get`	Read only	Read one artefact: its document as JSON and YAML, revision, state against Main and thread counts.
`spec_apply`	Stages or edits	Stage spec documents as revisions in the open proposal of a workstream, opening one if needed. Never writes the workstream or Main.
`proposal_open`	Stages or edits	Open the proposal of a workstream, where staged revisions wait for review.
`proposal_ready`	Stages or edits	Mark the open proposal Ready, telling the people of the workstream it is worth reviewing.
`proposal_finish`	Stages or edits	Close a proposal once every revision in it has been accepted or withdrawn.
`proposal_discard`	Destructive	Discard the open proposal, withdrawing every pending revision in it, including revisions other agents staged.
`proposal_withdraw`	Stages or edits	Withdraw one pending revision you staged.
`workstream_open`	Stages or edits	Open a new workstream (WS-n) in the project.
`workstream_rename`	Stages or edits	Stage a new title for a workstream. It changes when a person accepts the revision.
`workstream_editDescription`	Stages or edits	Stage a new description for a workstream. It changes when a person accepts the revision.
`workstream_editGoals`	Stages or edits	Stage the goals of a workstream. They change when a person accepts the revision.
`workstream_editOutOfScope`	Stages or edits	Stage the out-of-scope notes of a workstream. They change when a person accepts the revision.
`task_open`	Stages or edits	Open a Draft task (T-n) in a workstream. A person chooses what it covers.
`task_rename`	Stages or edits	Rename an open task.
`task_editDescription`	Stages or edits	Replace the description of an open task.
`task_submitReady`	Stages or edits	Move a Draft task to Ready, so a person can publish it.
`task_start`	Stages or edits	Move a Ready task to In progress.
`task_abandon`	Destructive	Abandon an open task. Its changes go back to the workstream and a publication in flight ends. It cannot be undone.
`task_resolveConflict`	Stages or edits	Resolve a conflict between an artefact in a workstream and Main by writing the complete merged document.
`thread_open`	Stages or edits	Open a comment thread on an artefact in a workstream, to ask a question or explain a change.
`thread_reply`	Stages or edits	Add a comment to an existing thread.
`thread_reopen`	Stages or edits	Reopen a thread a person resolved.

The server also offers 4 prompts, such as read-then-propose, which Claude shows in the attachment menu when the connector is on. The MCP tool reference describes every tool and prompt with its inputs.

Example prompts

Goal	Prompt
Get oriented	"Use SpecsGraph to list my projects, then summarize the active workstreams in Shop and what each one changes."
Read the spec	"Read the Orders bounded context and its use cases from SpecsGraph and explain how checkout reserves stock."
Stage a change	"In WS-3, stage a scenario in the Reserve stock use case for a cart that has been idle for 15 minutes. Tell me what to review."
Follow up on review	"Read the open threads in WS-3, stage revisions for the points you agree with and reply in each thread."
Pick up work	"Pick up task T-4 in SpecsGraph: read it and its workstream, then propose the spec work it needs."

Disconnect and revoke

In Claude. Open Settings, then Connectors, select SpecsGraph and disconnect or remove it. Claude stops calling the server.
In SpecsGraph. Open Settings, then Access tokens, then Signed-in agents, choose Revoke next to Claude, then Revoke agent. The connector stops working at its next request. Do this too if you removed the connector in Claude, so no stored grant is left behind.

Data handling

SpecsGraph receives the tool calls Claude makes and their arguments, not your conversation.
Tools return content only from the workspace and projects you allowed on the consent page.
What the connector writes (staged revisions, threads, tasks) is stored in your workspace and attributed to you through Claude, so reviewers can see where it came from.
Claude handles your conversation under Anthropic's own terms and privacy policy.

The Privacy Policy covers what SpecsGraph stores and for how long, and Security and your data covers hosting and export.

Troubleshooting

Symptom	Likely cause	What to do
Connecting fails before the browser opens	The URL is wrong or incomplete.	Use `https://mcp.specsgraph.io/mcp` exactly, path included.
The client asks you to sign in again, or reports `401 Unauthorized`	The agent's sign-in was revoked in Signed-in agents, it reached the expiry you chose on the consent page, or your membership of the workspace ended.	Connect again from the client and allow the agent on the consent page. Nothing the agent staged before is lost.
The consent page says "This sign-in request expired" or "was already answered"	The sign-in link is single use and short lived. It was opened late, twice, or in another browser.	Go back to the client and connect again, then finish the consent page in one go.
The consent page says "You are not in an organisation yet"	An agent always acts in one workspace, and your account has none.	Create a workspace or accept an invitation in the web app, then connect again.
You chose Deny, or closed the consent page	The client did not get access.	Connect again and choose Allow.
Connected, but some tools are refused	The agent was allowed Read only, the project is not among the projects you chose, or your role is below Editor.	Revoke the agent in Signed-in agents and connect again with Read and write and the right projects, or ask an Admin for the Editor role.

Support

Email support@specsgraph.io for help with the connector, or see Support for every way to reach us. Include the time of the problem and the tool name if you have it.