@grapha/mcp-server

Model Context Protocol server for Grapha — lets users summon their coding agent from inside a Grapha project without switching to their IDE.

This is the transport layer that connects your coding agent (Claude Code, Codex, Cursor, any MCP-compatible client) to a Grapha project. Once connected, the agent can:

• Read the full project context in one call (grapha_get_pickle)
• Claim pending tasks (/rigor runs, visualize requests, comment replies)
• Write markdown docs with rich blocks (charts, metrics, mermaid, tables)
• Query the connected database
• Post annotations, suggestions, and replies to comment threads

Previously, an external agent had to be invoked manually via a terminal command (/rigor). With MCP, the agent is connected once and watches for work inside the session — users click a "Summon" button in Grapha and the agent picks up the task immediately.

Install

Via Claude Code / Claude Desktop

Add to your ~/.claude/claude_desktop_config.json (Claude Desktop) or .mcp.json in your project root (Claude Code):

{
  "mcpServers": {
    "rigor": {
      "command": "npx",
      "args": ["-y", "@grapha/mcp-server"],
      "env": {
        "GRAPHA_BASE_URL": "https://grapha.agency",
        "GRAPHA_API_TOKEN": "gr_...",
        "GRAPHA_AGENT_ID": "claude-code"
      }
    }
  }
}

Get your GRAPHA_API_TOKEN from the /agent-setup page in your Grapha project.

Local development

cd mcp
pnpm install
pnpm build

Then point your MCP client at node /absolute/path/to/mcp/dist/server.js.

Environment variables

| Variable | Required | Default | Description | |---|---|---|---| | GRAPHA_BASE_URL | no | https://grapha.agency | Base URL of the Grapha instance. Use http://localhost:3000 for local dev. | | GRAPHA_API_TOKEN | yes | — | Per-project bearer token. From /agent-setup. | | GRAPHA_AGENT_ID | no | mcp:coding-agent | Identifier for this agent in audit logs and presence indicators. |

Tools exposed

| Tool | Purpose | |---|---| | grapha_get_pickle | One-shot project context: schema, formulas, themes, feature set | | grapha_get_state | Full project state including doc bodies | | grapha_get_pending | Lightweight list of pending work | | grapha_watch_tasks | Long-poll (up to 120s) for new tasks | | grapha_claim_task | Atomically claim a task before working on it | | grapha_submit_task_result | Return a structured result for a claimed task | | grapha_write_doc | Create or update a plan document (markdown) | | grapha_reply | Reply to an existing comment thread | | grapha_query_db | Read-only SELECT against the connected DB | | grapha_render_mermaid | Render mermaid to SVG |

Typical session loop

1. grapha_get_pickle({ project_id }) → baseline context
2. grapha_get_pending() → any work waiting?
3. For each pending task:
   a. grapha_claim_task({ notification_id })
   b. Execute (write doc / build chart / answer comment / …)
   c. grapha_submit_task_result({ notification_id, result_type, result_data })
4. grapha_watch_tasks({ project_id }) → block for new work
5. Loop.

Design notes

• stdio transport — matches Claude Desktop, Claude Code, Cursor conventions
• Per-project scope — one token = one project. Run multiple servers for multiple projects.
• Long-poll client-side — Grapha's HTTP API isn't long-poll native, so grapha_watch_tasks polls /api/coplanner/agent/pending every 2s up to the deadline. Simple and reliable.
• SQL guard — grapha_query_db rejects anything that doesn't start with WITH or SELECT. Write/DDL queries are never allowed through the MCP.