Skip to content

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, ask your team questions and stage spec changes for people 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 an organisation, with the Editor role or above if the agent should stage changes. A Viewer's agent reads, comments and asks questions.
  • The SpecsGraph MCP URL, https://mcp.specsgraph.io/mcp; see The MCP URL.

Add the connector

  1. Open the connector settings

    In claude.ai or Claude Desktop, open Customize, then Connectors, and choose Add custom connector.

  2. 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
  3. Connect and sign in

    Choose Connect. Claude opens app.specsgraph.io in your browser. Sign in to SpecsGraph if you are not already.

  4. Allow the connector

    The consent page asks "Allow Claude to use SpecsGraph?". Check that it returns to claude.ai, then pick the organisation 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. 16 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, grouped into plans with proposal_plan, one per task. A person accepts them into the workstream in the web app; Main changes only when a task publishes.
  • Plan and discuss. Tools that open and assign workstreams and tasks, start a Ready task, open or reply to comment threads and ask people questions with thread_ask.
  • Pick up work. work_item_next, work_item_claim and work_item_update take a work item, keep the claim and record the pull request; build_status and roadmap_get read what is built and what comes next.
  • With Agent autonomy on, Claude also writes the workstream directly, accepts, routes tasks, submits them as Ready and resolves threads.
  • Never 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 stay in the web app; the server lists no tool for them.

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 destructive tools, proposal_discard, workstream_abandon, workstream_discardChange and task_abandon, before you approve them.

Tools

ToolBehaviorWhat it does
project_listRead onlyList the projects the connection can reach, with their key, name and whether they are archived. Call it first.
spec_schemaRead onlyReturn the JSON Schema of spec format 1, with one definition per artefact kind.
spec_getRead onlyRead spec documents as YAML, one per artefact, each with the id and revision a later edit must send back. Read workstream:WS-3 while the spec is in flight; Main holds what shipped.
workstream_listRead onlyList workstreams (WS-n) with their state and the number of changes no task covers yet.
workstream_getRead onlyRead one workstream: title, description, goals, out of scope, state, task counts and its open proposal.
workstream_listChangesRead onlyList what a workstream changed against Main: each artefact added, modified or archived, its task and any conflict.
task_listRead onlyList tasks (T-n) with their state and workstream, newest first.
task_getRead onlyRead one task: description, state, tracker key, workstream, the artefacts in its scope, its publication state, the actions allowed, and its work items, flow (standard or hotfix) and delivery.
proposal_getRead onlyRead a proposal: its state, the revisions staged in it and what blocks each one, optionally with each document and its diff.
thread_listRead onlyList the threads of a workstream, of Main or of a work item with their comments and kind (comment, question, change request or conflict), open threads by default.
artefact_listRead onlyList the artefacts of a scope, filtered by kind, bounded context, text, state against Main or archived.
artefact_getRead onlyRead one artefact: its document as JSON and YAML, revision, state against Main and thread counts.
member_listRead onlyList the people of the organisation (user id, name, email, role), to pick the assignee of a task.
work_item_nextRead onlyList the ready implement, docs, regression and other items you may take, yours first, each with the scope to read the spec at. With nothing ready, it answers the roadmap's Up next.
build_statusRead onlyRead the derived build status of artefacts on Main (not started, planned, in dev, merged, on an environment, verified, outdated, rolled back), with the work item that delivered each one.
roadmap_getRead onlyRead the open milestones in order, each with its progress, phase, target date and warnings, and how many buildable artefacts no milestone plans. Read only: people create and order milestones.
spec_applyStages or editsStage spec documents as revisions in the open proposal of a workstream, opening one if needed, optionally into a plan for one task. A person accepts them into the workstream; Main after a task publishes. With Agent autonomy on, the documents are written to the workstream directly unless you ask to stage them.
proposal_openStages or editsOpen the proposal of a workstream, where staged revisions wait for review.
proposal_readyStages or editsMark the open proposal Ready, telling the people of the workstream it is worth reviewing.
proposal_finishStages or editsClose a proposal once every revision in it has been accepted or withdrawn.
proposal_discardDestructiveDiscard the open proposal and its pending revisions. Refused while another agent or a person has pending revisions in it.
proposal_withdrawStages or editsWithdraw one pending revision you staged.
proposal_planStages or editsCreate a plan in the open proposal, or change its task. A plan groups staged revisions that a person accepts together into one task: a new Draft task, or an open task of the workstream. It can name the work items the task gets at Ready.
proposal_assignStages or editsMove pending revisions you staged into a plan of the proposal, or out of every plan.
proposal_acceptStages or editsAccept staged revisions into the workstream: some, all, or a plan as a group. In the same call, route them into a new or existing task, assign it and submit it as Ready. Needs Agent autonomy.
workstream_openStages or editsOpen a new workstream (WS-n) in the project, optionally linked to a tracker issue and with its first Draft task.
workstream_renameStages or editsStage a new title for a workstream. It changes when a person accepts the revision, or at once with Agent autonomy on.
workstream_editDescriptionStages or editsStage a new description for a workstream. It changes when a person accepts the revision, or at once with Agent autonomy on.
workstream_editGoalsStages or editsStage the goals of a workstream. They change when a person accepts the revision, or at once with Agent autonomy on.
workstream_editOutOfScopeStages or editsStage the out-of-scope notes of a workstream. They change when a person accepts the revision, or at once with Agent autonomy on.
workstream_completeStages or editsComplete a workstream whose tasks are done or abandoned, optionally discarding the changes no task covers. Needs Agent autonomy.
workstream_abandonDestructiveAbandon a workstream and its open tasks; what it changed never reaches Main. It cannot be undone. Needs Agent autonomy.
workstream_discardChangeDestructivePut one changed artefact of a workstream back to its Main version. Needs Agent autonomy.
workstream_resolveConflictStages or editsResolve a conflict directly: keep Main, keep the workstream, or write the merged document. Needs Agent autonomy.
task_openStages or editsOpen a Draft task (T-n) in a workstream, optionally with an assignee. A person chooses what it covers and submits it as Ready, or the agent with Agent autonomy on.
task_renameStages or editsRename an open task.
task_editDescriptionStages or editsReplace the description of an open task.
task_startStages or editsMove a Ready task to In progress. A Draft task waits to be submitted as Ready.
task_abandonDestructiveAbandon an open task. Its changes go back to the workstream, a publication in flight ends and its open pull request closes. It cannot be undone.
task_routeStages or editsAdd changes of the workstream to a task's scope, or take them out, in one call. Needs Agent autonomy.
task_assignStages or editsSet the person responsible for a task, or clear it.
task_submitReadyStages or editsMove a Draft task with a scope to Ready, recording its agreement. Needs Agent autonomy.
task_markDoneStages or editsMark an In progress task done once its publication is published. Needs Agent autonomy.
task_resolveConflictStages or editsStage the complete merged document of an artefact that conflicts with Main. The conflict is resolved when the revision is accepted. With Agent autonomy, workstream_resolveConflict resolves it directly.
thread_openStages or editsOpen a comment thread on an artefact in a workstream or on Main, or on a work item, to explain a change or raise a point.
thread_askStages or editsAsk a question about an artefact in a workstream or on Main, or about a work item you are stuck on, with answers to choose from, a person or team to ask and whether it blocks. A person answers it.
thread_replyStages or editsAdd a comment to an existing thread.
thread_reopenStages or editsReopen a comment thread a person resolved. Only a person, or an agent with Agent autonomy on, reopens a question or a change request; a conflict thread is never reopened.
thread_resolveStages or editsResolve an open thread; a question or change request closed this way ends as withdrawn. Needs Agent autonomy.
thread_answerStages or editsAnswer an open question with one of its options, a text, or both. Needs Agent autonomy.
work_item_claimStages or editsClaim a ready implement, docs, regression or other item: it moves to doing and the claim lasts 2 hours unless you heartbeat. Deploy, verify and uat items are for CI and people.
work_item_updateStages or editsKeep your claim for 2 more hours, record the pull request, or give the item back. Never marks it done: the merge of a pull request naming it, or a person, does.

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

GoalPrompt
Get oriented"Use SpecsGraph to list my projects, then summarize the active workstreams and what each one changes."
Read the spec"Read the Ordering bounded context and the Reserve stock use case 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. Ask me with a question where you are unsure."
Check the build"Which use cases of the Ordering context are not built yet, and what is up next on the roadmap?"

Disconnect and revoke

  • In Claude. Open Customize, 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 organisation and projects you allowed on the consent page.
  • What the connector writes (staged revisions, plans, threads, questions, tasks) is stored in your organisation 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

SymptomLikely causeWhat to do
Connecting fails before the browser opensThe 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 UnauthorizedThe 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 organisation 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 organisation, and your account has none.Create an organisation or accept an invitation in the web app, then connect again.
You chose Deny, or closed the consent pageThe client did not get access.Connect again and choose Allow.
Connected, but some tools are refusedThe 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.