MCP Connection

MCP Connection

After a PRD is locked and agents are generated, the next step is connecting your development environment to SpecGraph. The MCP (Model Context Protocol) connection is the recommended way to do this — it gives Claude Code live access to your spec without any file exports or stale documents.

What MCP Does

MCP is the nerve system between SpecGraph and Claude Code. Once connected:

• Claude Code can read your PRD, agents, stories, wishes, and project context on demand — always the current version, never a stale file.
• Claude Code reports progress back to SpecGraph: stories complete, blockers appear, and project phases advance — all visible in the SpecGraph web UI in real time.
• Each agent loads only the context it needs. The Developer agent, for example, receives a self-contained story package — the story description, acceptance criteria, relevant PRD sections, and applicable constraints — not the entire spec.

Setting Up the MCP Connection

Step 1: Get Your Project ID

From the Export page of your locked project, copy the Project ID. This identifies your project to the MCP server.

Step 2: Run Init in Your Project Directory

Open a terminal in your project's root directory and run the init command shown on the Export page:

npx specgraph-mcp init --project-id <your-project-id>

This writes two files to your project root:

.mcp.json — tells Claude Code how to connect to the SpecGraph MCP server:

{
  "mcpServers": {
    "specgraph": {
      "command": "npx",
      "args": ["-y", "specgraph-mcp"],
      "env": {
        "SUPABASE_URL": "http://127.0.0.1:54321",
        "SUPABASE_SERVICE_ROLE_KEY": "<your-service-role-key>",
        "SPECGRAPH_PROJECT_ID": "<your-project-id>"
      }
    }
  }
}

CLAUDE.md — a minimal project context file that tells Claude Code to use SpecGraph MCP tools. This is regenerated on demand from the live PRD state, so it's always up to date.

Step 3: Start Claude Code

Open a Claude Code session in your project directory. It automatically detects .mcp.json and connects to the SpecGraph MCP server. You can verify the connection by asking Claude Code to call list_projects or get_project.

The Development Workflow via MCP

Once connected, the agent team works through four phases in sequence:

Phase 1 — Architect

Load the Architect agent by selecting the architect prompt from SpecGraph's MCP prompts. The Architect:

• Calls get_prd to read the full specification.
• Calls get_project_context to read the tech stack, design system, and security requirements.
• Calls get_control_manifest to read implementation guardrails (approved libraries, constraints).
• Designs the system architecture locally.
• When done, calls update_project_phase — the project advances to Story Sharding in SpecGraph.

Phase 2 — Scrum Master

Load the Scrum Master prompt. The Scrum Master:

• Calls get_wishes to read all accepted requirements.
• Calls get_acceptance_criteria to get the Given/When/Then criteria.
• Breaks the project into implementation stories with a clear sequence.
• Calls create_stories to save all stories to SpecGraph.
• Stories appear immediately in the Implementation Dashboard on the web UI.
• When done, calls update_project_phase — the project advances to Exported.

Phase 3 — Developer (repeating loop)

Load the Developer prompt. For each story:

1. Call get_stories to see the backlog and pick the next pending story.
2. Call get_story_context with the story ID to fetch the self-contained context package (relevant PRD sections, wishes, acceptance criteria, and agent instructions — no need to load the full spec).
3. Call update_story_status to set the story to in_progress.
4. Write failing tests from the acceptance criteria.
5. Implement code to make the tests pass.
6. Run tests locally — fix until green.
7. Call complete_story with a summary and list of files changed.
8. Repeat for the next story.

If stuck: If the story has an ambiguity, a conflict in requirements, or a decision that requires human input — call report_blocker instead of guessing. A blocker appears in SpecGraph's web UI, a human resolves it, and the Developer picks the story back up once it's cleared.

Phase 4 — QA (per story)

Load the QA prompt. For each completed story:

• Call get_story_context with the story ID to fetch acceptance criteria and implementation notes.
• Review the implementation against the criteria.
• Call update_story_status to reopen the story if criteria are not met, or add_implementation_note to log QA findings.

Monitoring Progress in SpecGraph

While Claude Code works, the SpecGraph Implementation Dashboard shows everything in real time:

• Which stories are Todo, In Progress, Done, or Blocked.
• A phase timeline showing where the project is in the architect → shard → develop → QA cycle.
• All blockers with their descriptions, so the right people can resolve them.
• Implementation notes logged by Claude Code during development.

You don't need to ask Claude Code for a status update — just open the Implementation Dashboard.

Resolving Blockers

When the Developer agent reports a blocker, it shows up in SpecGraph's Implementation Dashboard as a blocked story with a description. To resolve it:

1. Read the blocker description — it will reference the specific ambiguity or conflict.
2. Review the relevant wishes, PRD sections, or conflict resolutions for context.
3. Add a clarification note to the story and clear the blocker.
4. The story returns to Pending and the Developer agent can resume it on the next call to get_story.

Blocker resolution keeps humans in the loop for decisions that matter, while letting Claude Code handle everything it can resolve autonomously.

MCP vs Standard Export