Cursor
Connect Cursor to SpecsGraph by adding the MCP server to .cursor/mcp.json and signing in from Cursor Settings, then use the spec from Cursor's agent.
Before you start
- Cursor installed, with the agent available in chat.
- 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 server to mcp.json
Cursor reads MCP servers from a JSON file. Pick where it lives based on who should get the server:
{
"mcpServers": {
"specsgraph": {
"url": "https://mcp.specsgraph.io/mcp"
}
}
}A server with a url field is treated as a remote server, so there is nothing to install or run locally. If the file already lists other servers, add the specsgraph entry next to them inside mcpServers. Open Cursor Settings, go to Tools & MCP, click Needs login next to specsgraph and choose Allow on the SpecsGraph consent page in your browser.
Keep the token out of the file
If you cannot use sign-in, send a personal access token in a header. Cursor replaces ${env:SPECSGRAPH_TOKEN} with the value of the environment variable when it loads the file. The committed file holds no secret, and each teammate connects with their own token. If the server fails to authenticate while echo $SPECSGRAPH_TOKEN works in your terminal, start Cursor from that terminal with cursor ..
{
"mcpServers": {
"specsgraph": {
"url": "https://mcp.specsgraph.io/mcp",
"headers": {
"Authorization": "Bearer ${env:SPECSGRAPH_TOKEN}"
}
}
}
}Note
Cursor's own documentation is the authority on its configuration format and settings screens. The examples here reflect Cursor at the time of writing.
Check the connection
Open Cursor Settings and go to Tools & MCP (older versions call it MCP, or Tools & Integrations). The specsgraph entry should show as enabled with a healthy status and list its 52 tools, such as project_list, spec_get and spec_apply. After you edit mcp.json, toggle the server off and on, or reload the window, so Cursor reads the change.
Use SpecsGraph from the agent
Cursor's agent picks MCP tools on its own when a prompt calls for them. By default it asks before running a tool; approve read tools freely and read write-tool calls before you accept them, since spec_apply stages revisions under your name (as an agent) into a proposal.
Add a project rule
A project rule tells the agent to check SpecsGraph before it writes code. Save it under .cursor/rules/ and commit it with the repository. Cursor also reads an AGENTS.md at the repository root; Working well with agents has a version for that file.
---
description: Use SpecsGraph for the spec, glossary terms and review threads
alwaysApply: true
---
## Specs live in SpecsGraph
This repository's spec (bounded contexts, aggregates, use cases, features, glossary terms) is in
SpecsGraph, available through the `specsgraph` MCP server. Main is the spec that shipped; a workstream
(WS-3) holds the spec in flight until one of its tasks publishes.
Before you change behaviour, read first:
1. `project_list` to find the project, then `spec_get` for the documents you touch (selector `kind/Name`):
`scope: workstream:WS-n` while the spec is in flight in that workstream, `scope: main` for what shipped.
2. `workstream_list` and `workstream_listChanges` to see what a workstream already changes.
3. `task_list` and `thread_list` for the task and the review threads (open questions) you are working on.
When behaviour changes:
- Stage the spec change with `spec_apply` into the workstream. It lands in a proposal that a person
reviews: accepted into the workstream; Main after a task publishes. In a project with Agent autonomy on, it is
written to the workstream directly, and you may accept, route and submit tasks as Ready yourself.
- One small proposal per change. Do not treat an open proposal as final; read the workstream, not Main,
for what was accepted.
- People publish a task; publishing moves it on and the landing marks it done.
- Cite display ids such as WS-3 and T-4 (or the task's tracker key, such as KAN-43) in commit
messages and pull request descriptions.
When you implement agreed work (work items):
1. `work_item_next` for the ready items you may take, then `work_item_claim` the one you start.
2. `spec_get` at the item's `read.scope` for exactly what was agreed, then implement it.
3. Open a pull request whose title names the item, such as T-12.1, and link it with `work_item_update` (`codeRef`).
4. Send `work_item_update` with `heartbeat` within 2 hours while you work, or your claim lapses; `release` it if you stop.
- Stuck on the spec? Ask with `thread_ask` on the item (`item`, `blocking: true`). The merge, not you, marks the item done.Example prompts
Next steps
- Working well with agents: keep proposals small and reviewable.
- MCP tool reference: every tool the agent can call.
- Agent skills: guided modeling workflows, installed with
npx skills add SpecsGraph/specsgraph-skills.