AI agents

How agents discover Spec0 capabilities, react to exit codes, and use the docs MCP server.

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:

Code	Meaning
0	success
2	usage error
3	not authenticated
4	permission denied
5	not found
6	conflict
7	validation failed
8	rate limited
9	upstream server error
10	network error

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

A Model Context Protocol server hosting the Spec0 documentation as agent-callable tools. Same idea as Context7 but for our platform — your agent searches and retrieves Spec0 docs while it codes against Spec0, with citation URLs back to this site.

Public, no auth. v1 covers the documentation corpus only (CLI, mock-server, platform docs). Org-scoped tools — querying your own indexed APIs through MCP — will land in v2.

The docs MCP runs on Spec0's infrastructure. The other AI surface — Ask Spec0 chat inside the dashboard, plus future features like the spec critic and changelog generator — runs on your LLM provider key. See AI provider.

Wire it up

~/.cursor/mcp.json

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

Same shape works for Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS). Restart the agent and the three tools below appear in its tool palette.

You can also get the URL from the CLI:

spec0 mcp url
# Spec0 MCP server (public docs):
#   https://api.spec0.io/mcp/sse

Tools

Tool	Inputs	Returns
`search_docs(query, section?, topK?)`	natural-language query; optional section filter (`cli`, `mock-server`, `platform`, …); optional `topK` (default 6)	top chunks with `title`, `path`, absolute `url`, `excerpt`, similarity `score`
`get_page(path)`	relative slug, e.g. `cli/commands/publish`	full reassembled page content + URL
`list_sections()`	—	section tree of the corpus, derived from indexed paths

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

How agents use it in practice

A typical flow when a developer asks Cursor "how do I gate CI on breaking changes in Spec0?":

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

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

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.