AI agents

Spec0 is built for AI-driven engineering workflows. Three integration points an agent uses today:

1. Self-describing CLI

Every command emits machine-readable output. The full surface is exposed as a manifest:

spec0 commands --output=json | jq '.commands[].name'

The manifest includes flags, arguments, and exit codes for every command. An agent can compose operations without hardcoding CLI knowledge.

2. Stable exit codes

Codes are part of the contract — never repurposed:

Every command's exit codes are documented in its manifest entry; agents should branch on these rather than parse stderr.

3. Agent mode

Set SPEC0_MODE=agent to flip every default for machine callers: JSON output, no colour, no spinners, no update banner.

export SPEC0_MODE=agent
spec0 api list   # JSON, no ANSI, no progress

Spec0 MCP server

One Model Context Protocol server, one endpoint, two tiers of tools. The transport is Streamable HTTP — a single endpoint you POST to, the same whether or not you authenticate:

https://api.spec0.io/mcp        # Streamable HTTP (single endpoint, HTTP POST)

Anonymous callers get the documentation tools — your agent searches and retrieves Spec0 docs while it codes against Spec0, with citation URLs back to this site. Same idea as Context7, but for our platform.

Authenticated callers (a Spec0 token in an Authorization: Bearer header) get those plus org-scoped tools over their own indexed OpenAPI specs — semantic search across the org's registry, full spec retrieval, and an API index, all token-scoped to the caller's org.

Anonymous vs authenticated

Calling an org-scoped tool without a valid token doesn't error the transport — it returns a structured "authentication required" message so the agent can prompt you to wire up a token and retry.

Documentation tools (anonymous)

To wire up the anonymous tools, point your client at the endpoint with no headers:

{
  "mcpServers": {
    "spec0": {
      "url": "https://api.spec0.io/mcp"
    }
  }
}

claude mcp add --transport http spec0 https://api.spec0.io/mcp

{
  "servers": {
    "spec0": {
      "type": "http",
      "url": "https://api.spec0.io/mcp"
    }
  }
}

Restart the client and the three docs tools appear in its tool palette. (Claude Desktop uses the same mcpServers shape as Cursor.)

You can also get the URL from the CLI:

spec0 mcp url
# Spec0 MCP server:
#   https://api.spec0.io/mcp

Org-scoped API tools (authenticated)

Add a Spec0 token to the config and the org-scoped toolset appears — these run against your own org's indexed specs, never anyone else's.

The token is the one minted by spec0 auth login; print it with spec0 auth token. Pass it in the Authorization header:

{
  "mcpServers": {
    "spec0": {
      "url": "https://api.spec0.io/mcp",
      "headers": {
        "Authorization": "Bearer ${SPEC0_TOKEN}"
      }
    }
  }
}

claude mcp add --transport http spec0 https://api.spec0.io/mcp \
  --header "Authorization: Bearer ${SPEC0_TOKEN}"

{
  "servers": {
    "spec0": {
      "type": "http",
      "url": "https://api.spec0.io/mcp",
      "headers": {
        "Authorization": "Bearer ${SPEC0_TOKEN}"
      }
    }
  }
}

Org tools are strictly token-scoped: list_apis and search_apis return only the caller's own org's APIs, and get_api_spec rejects ids the token's org doesn't own. The same isolation that protects the registry on the dashboard applies here — see APIs → Org boundaries.

Easiest setup — spec0 mcp install

Skip the hand-edited JSON. The CLI writes the right config for you:

spec0 mcp install                 # auto-detect installed clients
spec0 mcp install --client cursor # write ~/.cursor/mcp.json
spec0 mcp install --client claude # run `claude mcp add` for Claude Code
spec0 mcp install --client all    # every detected client

It drops the endpoint in, and — if you're logged in — wires the Authorization: Bearer header so the org-scoped tools light up immediately. Restart the client afterwards.

How agents use it in practice

A docs question — a developer asks Cursor "how do I gate CI on breaking changes in Spec0?":

1. The agent calls search_docs("gate CI on breaking changes") with section: "cli".
2. Server returns chunks from cli/recipes/block-on-breaking-changes and cli/commands/diff with their citation URLs.
3. Agent synthesises a step-by-step answer using its own reasoning (no LLM cost on our side).
4. Agent renders the answer with the citation URLs as clickable references.

If the agent needs more than an excerpt, it follows up with get_page("cli/recipes/block-on-breaking-changes") for the full markdown.

An org-API question — with a token wired up, the agent works over your registry: it finds the API that handles refunds, drills into the exact operation, and reads the request shape, all scoped to your org. That discovery loop — and the full catalogue of questions the org tools answer — has its own page: API discovery.

Each tool's MCP description tells the agent when to call it. The agent decides; you don't have to prompt-engineer tool selection.

Plain-text fallback for non-MCP crawlers

If your tool doesn't speak MCP, the docs portal also serves the corpus as plain text:

• https://docs.spec0.io/llms.txt — index of every page
• https://docs.spec0.io/llms.mdx/docs/<slug>/content.md — full markdown for one page
• https://docs.spec0.io/llms-full.txt — entire corpus in one file

These routes are stable and intended for crawling.