Skip to content

Cursor

Connect Cursor to SpecsGraph by adding the MCP server to .cursor/mcp.json with your access token, then use the system graph from Cursor's agent.

Before you start

  • Cursor installed, with the agent available in chat.
  • Your SpecsGraph server's MCP URL. The examples use https://specsgraph.example.com/mcp; see Find your server's MCP URL.
  • A personal access token in the SPECSGRAPH_TOKEN environment variable.

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:

FileApplies toCommit it
.cursor/mcp.jsonThis project, for everyone who opens it in CursorYes, with the variable reference below
~/.cursor/mcp.jsonEvery project you open on this machineNo, it lives in your home folder
.cursor/mcp.jsonJSON
{
  "mcpServers": {
    "specsgraph": {
      "url": "https://specsgraph.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SPECSGRAPH_TOKEN}"
      }
    }
  }
}

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.

Keep the token out of the file

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.

Cursor needs to see the variable in its own environment. If the server fails to authenticate while echo $SPECSGRAPH_TOKEN works in your terminal, quit Cursor and start it from that terminal with cursor . so it inherits the variable.

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 tools, such as get_project_overview and get_requirement. After you edit mcp.json, toggle the server off and on, or reload the window, so Cursor reads the change.

A red status or an empty tool list usually means the token did not reach the server. Check the variable, then see the troubleshooting table in Other MCP clients.

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 they open proposals under your name.

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.

.cursor/rules/specsgraph.mdcMarkdown
---
description: Use SpecsGraph for requirements, domain terms and decisions
alwaysApply: true
---

Requirements and domain terms for this repository live in SpecsGraph, available
through the `specsgraph` MCP server.

- Read the relevant context and requirements before changing behavior.
- Use SpecsGraph glossary terms in code and tests.
- Propose spec changes in SpecsGraph when behavior changes, and cite
  requirement IDs such as ORD-12 in commit messages.

Example prompts

GoalPrompt
Understand a context"Use SpecsGraph to list the requirements in Fulfilment and explain how they depend on Orders."
Write tests from scenarios"Read ORD-13 from SpecsGraph and write one test per scenario in the reservations module."
Propose a missing case"Propose a new scenario for BIL-04 that covers a payment failing after stock is reserved."
Name things consistently"Check the SpecsGraph glossary for Orders and rename anything in this file that uses a different word for Reservation."

Next steps