Connecting coding agents (MCP).

SpecGraph projects don't stop at the spec — they ship code. Once a project is in good shape, you connect a coding agent (Claude Code, Cursor, Cline, any MCP-speaking client) and let it implement story by story. This page is the end-to-end practical guide.

What you'll get #

A coding agent connected to SpecGraph reads your spec live and writes its progress back live. Concretely:

• The BMAD pack as MCP tools. Eight planning artifacts (product-brief, prd, architecture, ux-design, epics, qa-test-plan, project-context, CLAUDE), one file per story, plus a sprint-status.yaml lifecycle. The agent pulls each on demand — no copy-paste, no stale context.
• Three implementation skills — /sg-dev, /sg-review, /sg-status — that turn the pack into a workflow. The agent claims a story, implements it, posts a Dev Agent Record, picks the next one. Loops until the sprint's empty.
• Two writeback channels. Story lifecycle (ready-for-dev → in-progress → done) flows back into the SpecGraph pack browser. Live events (commits, test results, questions) flow into the §8 Progress board.

The connection is per-project — one token, one project, instant revocation. Edits to the spec while the agent works are picked up on the next tool call; there's no caching window.

Step 1 — Mint a token #

Open the project, click Settings in the top right, scroll to MCP Access:

1. Type a label that helps you remember which device/agent this is for ("Claude Code · MacBook", "Cursor · work laptop").
2. Click Generate. The token reveals once — it looks like sg_live_<48-hex>.
3. Copy it now. You can re-reveal a token later in the list, but treat each one as a secret on par with an SSH key.

Tokens are bound to one project at mint time. If you work on three projects, you mint three tokens. If you swap laptops, mint a new one — don't reuse.

Step 2 — Register with Claude Code #

The fastest path is the CLI:

claude mcp add --scope user --transport http specgraph \
  https://mcp.specgraph.dev/v1/mcp \
  --header "Authorization: Bearer sg_live_<paste-token-here>"

Three flags worth understanding:

• --scope user — the connection works in any Claude Code session you start, regardless of which directory. Use this unless you have a reason not to.
• --transport http — required. Default is stdio; SpecGraph is an HTTP server.
• specgraph — the name you'll reference in prompts. Pick something else if you have multiple SpecGraph projects connected at once (see "Multiple projects" below).

Don't use --scope project. That writes a .mcp.json file into your repo, which means the next git commit ships your token to whoever has read access. Always --scope user or --scope local for token-bearing config.

Verify it took:

claude mcp list
# specgraph: https://mcp.specgraph.dev/v1/mcp (HTTP) - ✓ Connected

If it says ✗ Failed to connect, the token is wrong, revoked, or you typoed the URL. Re-run claude mcp add (or claude mcp remove specgraph first).

Manual JSON config #

If you'd rather edit the file directly, add to ~/.claude.json:

{
  "mcpServers": {
    "specgraph": {
      "url": "https://mcp.specgraph.dev/v1/mcp",
      "headers": { "Authorization": "Bearer sg_live_<token>" }
    }
  }
}

Same shape works for Cursor, Cline, and any other MCP-aware client (the field name varies by client — check their docs).

Step 3 — Open a session in the target repo #

The MCP server holds your spec. The code the agent writes lands in a separate target repo — usually empty when you start.

mkdir -p ~/projects/<project-slug> && cd ~/projects/<project-slug>
git init
claude

Inside the session, run /mcp. You should see specgraph listed with its tool count. If not, you opened the session before the MCP registration finished — start a new one.

Step 4 — Bootstrap #

The bootstrap prompt installs the SpecGraph implementation skills locally and primes the agent with the rules. Paste this verbatim:

This is a fresh repo. The complete spec for this project lives on the
`specgraph` MCP server you have connected.

Bootstrap procedure:

1. Call `specgraph.project_info` and print the name + slug. If it
   shows the wrong project, stop and tell me before doing anything else.

2. Call `specgraph.install_skills`. The response contains a
   `skills` array; for each entry, write its `content` to its `path`,
   creating parent directories as needed. This installs `/sg-dev`,
   `/sg-review`, and `/sg-status` as Claude Code skills in this repo.

3. Call `specgraph.read_bmad_claude_md` and adopt every rule as your
   working agreement.

4. Call `specgraph.read_project_context` and treat each numbered
   rule as a hard constraint when generating code.

5. Call `specgraph.list_epics` and `specgraph.list_stories` (no
   filter). Summarize the epic list and the next 3 ready-for-dev
   stories in 10 lines.

6. Stop and wait. Don't write any code yet — restart your Claude
   Code session first so the new skills register.

Then exit Claude Code and restart it (/exit then claude again, in the same directory). On the next session start the three slash-commands are available.

Why each step matters:

• (1) Confidence check. Wrong project = wrong code. Catch it before any file writes.
• (2) Skill install. install_skills returns the SKILL.md files the agent then writes to .claude/skills/sg-dev/SKILL.md, etc. Without this, the slash-commands don't exist.
• (3) Working agreement. The BMAD CLAUDE.md points at project-context.md, the per-story workflow, and the tech stack — all in one place.
• (4) Hard rules. project-context.md is the highest-leverage file: 12+ numbered rules with Why + ✅ + ❌. Skipping this is the single biggest source of "correct features built with the wrong patterns."
• (5) Sanity summary. Confirms the pack is well-formed and the agent understood it.
• (6) Session restart. Slash-commands only register at session start. No way around it.

Step 5 — Implement story by story #

In the new (post-restart) session, your first command is:

/sg-status

This calls get_sprint_status and renders a sprint dashboard — total stories, per-epic breakdown, what's done vs in-progress vs ready-for-dev, and the next 3 stories queued up. Read it before you start coding so you know where you are.

Then implement the next story:

/sg-dev

This is the workhorse loop. /sg-dev will:

1. Pull get_sprint_status and pick the first ready-for-dev story.
2. Pull get_story for that key, plus read_project_context and read_architecture for the rules and patterns the story expects.
3. Claim the story by calling update_story_status: in-progress. The pack browser flips that story's badge from grey to amber. Anyone watching /sg-status sees the change immediately.
4. Implement every task in the story file in order. After each major file, type-check; after each commit, call report_commit.
5. Run the test suite. Post results via report_test_result.
6. Verify each AC against the actual code. If any fails, fix it; the story doesn't close until every AC verifies.
7. Close the story by calling update_story_status: done with a Dev Agent Record (summary, files modified, test counts). Pack badge turns green.

When /sg-dev finishes, ask it to review:

/sg-review

This audits the most recently done story against its ACs and the project-context rules. It fixes issues it finds and posts a PASS/FAIL verdict back to the story via append_story_review. You can read the verdict either in the agent's terminal or in SpecGraph's pack browser (story file → Review Record).

Pick a specific story instead of the auto-select:

/sg-dev 2-3              # implement story 2-3
/sg-review 2-3           # review story 2-3

Run continuously until the sprint's done:

/sg-dev --loop

The agent will pick the next ready-for-dev story after each one closes, until the sprint hits zero ready stories. Watch the §8 Progress board to see what's happening — interrupt at any time if a story is going off the rails.

What to expect during a typical story #

• First 30 seconds: tool calls fly — get_story, read_project_context, read_architecture. The agent isn't writing code yet; it's loading the contract.
• Middle: file writes + commits + test runs. The §8 Progress board shows commits as they land. Story badge stays amber.
• Last few seconds: AC verification + update_story_status: done. Story badge goes green; sprint progress bar advances.
• On failure: the agent calls ask_question and stops. The question shows up on the Progress board with a clear blocker. Answer in SpecGraph (clarify the spec or amend the story) and rerun /sg-dev.

When to intervene #

• Wrong-stack assumptions in the bootstrap summary → cancel, fix architecture.md in SpecGraph, restart.
• The agent is mid-story and asking a question → answer, re-run /sg-dev (it picks up where it left off).
• A story finished done but the result looks wrong → run /sg-review <key>. The skill audits + fixes; if it can't, it returns FAIL and you decide.
• Mid-sprint feature change → file a wish in SpecGraph, accept it; it becomes a new story; /sg-dev picks it up next.

Why story-by-story instead of "build the whole thing" #

• One story = one PR-sized chunk. Reviewable, revertable.
• The agent's context window stays focused on one story file + the rules + the patterns — not an 8-week plan.
• Wrong turns get caught before they compound — /sg-review fires on every story, not at the end.
• The lifecycle (update_story_status) keeps the dashboard honest; you always know what's in flight.

Step 6 — Watch from SpecGraph #

Two surfaces show what the agent is doing, in different time scales:

The pack browser (§7 Handoff → BMAD pack, or click the Pack icon on the right rail of any phase). This is the canonical view:

• File tree on the left: planning-artifacts, then implementation-artifacts (every story file).
• Per-story status badges (ready-for-dev / in-progress / done) update as the agent calls update_story_status.
• A validation findings banner at the top — error entries block a "fully valid" pack; warning entries point at upstream gaps to enrich (missing personas, missing ADRs, etc.).
• Click any file to read the full markdown the agent saw.

The §8 Progress board. This is the live event stream:

• A Live badge with a pulsing dot when an event arrived in the last 5 minutes.
• A KPI strip with started / in-progress / blocked / completed counts.
• A task board grouping events by their taskId (typically the story key).
• A reverse-chronological event stream below — every commit, test run, question.

The feed is server-rate-limited to 120 events/minute per token, so a runaway agent just gets Rate limit: errors back; the platform stays healthy.

Adding a feature mid-build #

The amendment flow (wishes → stories) keeps additions clean:

1. File a wish in SpecGraph (any phase's wish panel, or the public stakeholder portal).
2. Accept it; merge it into the features section — or skip the wish and propose an add-feature amendment directly.
3. A new story file appears in the BMAD pack with status ready-for-dev. Next /sg-dev (or /sg-dev --loop) picks it up.
4. project-context.md stays unchanged — stable rules = stable agent. Architecture changes append a new ADR rather than rewriting existing ones.

Full walkthrough — including the stable-story-key story and a 60-second test — is in Mid-build amendments.

Tool catalogue #

BMAD pack tools — the new shape #

The BMAD pack is what /sg-dev and /sg-review consume. It's the recommended path for any new project.

Classic 4-doc tools — backward compat #

These still work for agents that haven't been upgraded to the BMAD shape. New projects should prefer the BMAD tools above.

Live-feed write tools (the agent posts to your Progress board) #

Two writeback channels. The story lifecycle (update_story_status, append_story_review) is the canonical state — it's what /sg-status reads, what the pack browser shows, what sprint-status.yaml renders. The live-feed tools (report_*) are in addition, for the §8 Progress board's real-time view. /sg-dev and /sg-review use both — don't substitute one for the other.

Implementation skills — reference #

Specgraph ships three Claude Code skills that turn the MCP pack into a workflow. They're installed by install_skills (Step 4); the source-of-truth markdown lives in bmad/skills-mcp/<name>/SKILL.md if you want to read or customize them.

Validation findings #

The pack composer runs a dozen validation passes when it's read. Findings come in three levels:

• error — blocks a "fully valid" pack. Examples: an FR is mapped to multiple epics, a feature has no acceptance criteria, no features captured at all. The agent should still implement what's there but the pack is incomplete.
• warning — pack is valid but a section is auto-stubbed. Examples: no personas (using primaryUsers/secondaryUsers strings), no structured NFRs (synthesized from performance config), no ADRs (stubbed from architecture.stack). Promote in the corresponding phase to remove.
• info — recommended but optional. Examples: no user journeys captured, an epic has no permission-boundary AC.

Findings show up in three places: a banner in the right-rail live preview, a banner at the top of the pack browser, and a summary in the export panel. Clicking any finding takes you to the phase to enrich.

Operations #

Rotating and revoking tokens #

A leaked token is a one-row delete:

1. Settings → MCP Access on the project page → trash icon on the row.
2. The token returns 401 on the very next request — there's no caching window.
3. On your machine: claude mcp remove specgraph, mint a new token, re-add.

Rotate proactively whenever:

• A laptop is lost or reassigned.
• You change agents (different name = different token, easier to audit).
• The project becomes much more sensitive (e.g. a public beta launches).

Multiple projects #

The token is project-scoped, so two SpecGraph projects = two tokens. Two patterns:

• One server name, swap on demand. Run claude mcp remove specgraph + claude mcp add with the new token when switching projects. Simple, manual.
• Distinct names per project. Register them as specgraph-billing and specgraph-admin; both stay connected; you reference them explicitly in prompts (Use specgraph-billing.read_epics).

Pick the second pattern only when you actively flip between projects in the same Claude Code session.

Clearing the Progress feed #

Owners and admins can wipe a project's Progress events at any time — useful when:

• A runaway agent flooded the feed during a debug loop.
• You're starting a fresh implementation pass and want a clean board.
• You ran a smoke test and want to drop the noise before real work begins.

Open §8 Progress → click the trash icon in the connection header → confirm. Existing tokens keep working; agents just start a fresh stream on their next post.

Note: clearing the Progress feed does not reset story lifecycle. To re-implement a story, run /sg-dev <key> and the skill will pick up wherever the canonical status left off.

Troubleshooting #

Why this exists #

The traditional handoff from spec to implementation is a copy-paste of spec.md and CLAUDE.md into the agent's context window. That works once. It breaks the moment the spec changes — now your agent is implementing yesterday's spec in today's repo, and nobody notices until the PR review.

MCP closes that loop. The agent reads the spec at the moment it implements, not at the moment you typed the prompt. The BMAD shape goes one step further: instead of one giant spec.md, the agent reads exactly the slice it needs — one story, plus the rules, plus the architecture sections that story references. And the lifecycle writebacks (update_story_status, append_story_review) keep your dashboard honest without anyone manually updating a tracker.

That's the loop: spec on SpecGraph → agent reads it over MCP → code in your repo → progress flows back to the same SpecGraph project. One source of truth, both directions.