Agents & MCP

Specbench exposes its spec-authoring surface to agents through an MCP server. Agents author the spec the way they author code: export a YAML document, edit it, apply it back — one round trip instead of dozens of granular tool calls.

Connect

Two ways in, whichever agent you use:

Sign in (OAuth). Add the server URL and let the client open a browser. You sign in with whatever the instance accepts, click Allow, and the client holds a token that renews itself. Revoke it any time from Personal settings → Access tokens, where it appears under the client's name.
Paste a token. For scripts and clients that can't open a browser, issue a Personal Access Token from Personal settings → Access tokens; it starts sbp_ and is shown once. The server takes it as a bearer (Authorization: Bearer sbp_…).

The server URL is https://mcp.specbench.io/mcp for the hosted app, https://mcp.<your-domain>/mcp for a self-hosted Instance, or http://localhost:8081/mcp for the local stack (Try it locally or pnpm run dev). Everything an agent does is attributed to the person who signed in or owns the token, and marked as agent work.

Under the hood, sign-in is standard MCP authorization: the server points the client at the instance's own OAuth authorization server, the client registers itself (dynamic client registration), sends you to the consent page, and exchanges your approval for an access token and a refresh token using PKCE. Nothing is configured on your identity provider; consent uses the same sign-in the web app does. Self-hosting? See Agents signing in.

Add the server, then authenticate from the /mcp panel. The browser opens on the consent page and the terminal reports Connected once you allow it.

claude mcp add --transport http specbench https://mcp.specbench.io/mcp

Use --scope user to make it available in every project, or --scope project to write a shareable .mcp.json:

{
  "mcpServers": {
    "specbench": {
      "type": "http",
      "url": "https://mcp.specbench.io/mcp"
    }
  }
}

Prefer a pasted token? Add --header "Authorization: Bearer sbp_…" to the command, or a "headers" block to the JSON with "Authorization": "Bearer ${SPECBENCH_TOKEN}" so the file can be committed and each person exports their own token.

Add a custom connector with the server URL: Customize → Connectors → Add custom connector on claude.ai and in Claude Desktop, or Organization settings → Connectors for Team and Enterprise owners. Leave the OAuth client fields empty; the client registers itself. Signing in happens the first time you enable the connector in a chat. Cloud clients can't reach a localhost Instance; use a real hostname or a tunnel.

Codex CLI, the Codex IDE extension, and the ChatGPT desktop app's Codex mode all read ~/.codex/config.toml. Register the server, then sign in:

codex mcp add specbench --url https://mcp.specbench.io/mcp
codex mcp login specbench

codex mcp list shows the server; /mcp inside a Codex session confirms the tools loaded. To use a pasted token instead, add bearer_token_env_var = "SPECBENCH_TOKEN" under [mcp_servers.specbench] and export the token.

In the ChatGPT desktop app, open Settings → MCP servers → Add server, choose HTTP, and enter the server URL including the /mcp path. ChatGPT registers itself and prompts you to sign in. Cloud clients can't reach a localhost Instance; use a real hostname or a tunnel.

Any client that supports streamable-HTTP MCP works. Clients that speak OAuth discover everything from the server URL:

Setting	Value
Transport	Streamable HTTP
URL	`https://mcp.specbench.io/mcp`

Clients without OAuth take a pasted token as the header Authorization: Bearer sbp_…. Cursor, Windsurf, Gemini CLI, and Copilot each take a JSON block equivalent to the Claude Code one (type/url, plus headers for a token).

Install the skills

The MCP server is deliberately small: it exposes the tools, not a way of working. The guided workflows live in specbench-io/specbench-skills, a set of open-source Agent Skills (plain SKILL.md files) that turn a connected agent into a modelling partner:

Skill	Job
`specbench-director`	Reads the project state and routes to the right workflow.
`specbench-engineer`	Domain modelling by interview: contexts, language, roles.
`specbench-product`	Features, scenarios, roles, and terms in plain language.
`specbench-brownfield`	Seam-by-seam ingest of an existing codebase.

All four assume the server above is connected. Every workflow asks one question at a time and agrees each element with you before writing it.

The repo is a plugin marketplace. Inside Claude Code:

/plugin marketplace add specbench-io/specbench-skills
/plugin install specbench

Then start with /specbench-director in a project that has the server connected. Update later with /plugin marketplace update specbench; third-party marketplaces do not auto-update unless you turn that on under /plugin → Marketplaces.

Skills upload one at a time. Clone or download the repo, zip a folder under skills/ (for example skills/specbench-director), and add it under Customize → Skills. Team and Enterprise owners can provision them organisation-wide instead. Uploads are point-in-time copies; re-zip and re-upload to update.

The skills follow the portable .agents/skills/ convention, so the skills installer places them for Codex, Cursor, Copilot, and the rest:

npx skills add specbench-io/specbench-skills
npx skills update

Or copy the folders under skills/ into your agent's skills directory by hand and re-copy to update.

Everything the skills will make your agent do is in that repo, readable before you install it. They call no endpoint beyond your connected Specbench server.

The loop

project_list — discover the project to work in.
workstream_list / workstream_open — every spec edit is tagged with a working workstream; pick an Active one (or open one) and pass its number.
spec_get — export artefacts as YAML Spec Documents. Select with a qualified reference (bounded-context/Identity), a kind alone (bounded-context), or nothing for the whole surface.
Edit the YAML.
spec_apply — submit the whole document back. The server diffs it against current state and lands the difference on the trunk as ordinary granular changes.

spec_schema serves the JSON Schema documents answer to — exported files name it, so editors and agents can validate before submitting.

Document semantics

Partial by default. Keys a document asserts are claims; keys it omits say nothing. Omission never deletes.
Ids anchor, names address. Every identifiable node carries the server's id on export. Nodes match by id, adopt by name without one, and are created when nothing matches. An id matching nothing is refused — fix the document, never guess.
Renames. Keep the id and change name; a document with no id needs renamed-from.
Archiving. Set archived: true on the node — or pass prune: true to declare a document the complete truth for its artefact, clearing the content it omits.
Revisions. Exports carry revision. Hand it back and the apply refuses with a conflict only when another writer changed the same paths since — re-get, re-derive the edit, re-apply. The server never merges.
No-ops are free. Re-applying an untouched export lands nothing: no events, no history.

Direct mode and proposals

spec_apply currently lands changes directly on the trunk. A proposal mode is coming: the same documents staged behind an explicit proposal for a human to review, approve, or return with feedback before anything lands.