DOCS · GUIDES

Agent integrations

Serve the knowledge base to Claude Code, Cursor or Windsurf over MCP, and install the plugin that makes the working agreements bind.

Engineering
8 min read

On this page

MCP — ask the knowledge base instead of grepping
The Claude Code plugin
Using specd from CI

The knowledge base is most useful inside the editor where the work happens. Two integrations put it there — one read-only for any MCP client, one Claude Code-specific that enforces two of the working agreements.

MCP — ask the knowledge base instead of grepping

specd mcp serve puts the retrieval engine behind the Model Context Protocol, so an agent in Claude Code, Cursor, Windsurf or anything else that speaks it can query the knowledge base directly.

.mcp.json — or your editor's MCP settings

{
  "mcpServers": {
    "specd": { "command": "specd", "args": ["mcp", "serve"] }
  }
}

Needs the specd CLI on your PATH and specd login once per machine. Seven tools and three ambient resources; the full signatures are in MCP tools.

The Claude Code plugin

AGENTS.md is a numbered list of rules, and three of them are already enforced by software: the server refuses to serve an unapproved spec, the webhook matches merged spec/<id>-<slug> branches back to their spec, and the build station files the as-built record itself. The rest were enforced by asking nicely. The plugin makes two more bind at the moment they are broken.

Install it from this repository, which is its own marketplace:

in Claude Code

/plugin marketplace add unitypark/specd
/plugin install specd@specd

Command	What it does
`/specd:pull <id>`	Gate first, then the knowledge the design cites, then the branch.
`/specd:implement`	Tasks in order, one commit each, verify between them.
`/specd:as-built`	Files the record — copied from the approved spec, never composed.

The two hooks

gate.sh: Blocks an edit on a spec/ branch whose spec is not approved. It fails open on every infrastructure problem — no CLI, not logged in, server unreachable — because a hook that blocks all editing when the API is down is a hook people uninstall.
docs-ride-the-change.sh: Asks once, when a spec branch has changed code and nothing under knowledge/, whether rule 3 was met. It asks; it does not decide.

Neither can approve anything. That is a signed-in human in the app, and the reasoning is recorded at knowledge/decisions/0018-working-agreements-ship-as-a-plugin.md.

Using specd from CI

The CLI is a single static Go binary, which makes it a reasonable thing to put in a pipeline. The gate is available as an exit code:

terminal

specd spec status "$SPEC_ID"
# 0 approved · 1 error · 2 usage · 3 exists but not approved

Set SPECD_TOKEN for a non-interactive session and SPECD_PROJECT to skip specd use. Full list in Configuration.