Want to skip ahead? The Quickstart ships a single copy/paste bash script that runs the full pipeline — verify key → start interview → generate → download package.
Building an integration? Grab the logo, colors, naming guidance, and a ready-to-paste "Powered by SpecStep" badge at /brand. Free to use — no permission needed.
SpecStep exposes two programmable surfaces over the same generation engine that powers the web app: a REST API and an MCP server. Both share the same authentication, rate limits, and package outputs. MCP also supports OAuth 2.1 browser-based sign-in — MCP-capable clients (Claude Desktop, Cursor, Codex, etc.) can authenticate without handling an API key at all. Any MCP client that speaks RFC 7591 Dynamic Client Registration auto-registers on first use and signs in via the browser without any pre-shared credentials.
What the API is for
The API lets you drive SpecStep from outside the browser. Common uses are CI pipelines that kick off a documentation generation after a planning phase, scripts that pull package status and post it elsewhere, and AI coding agents that request a regeneration when the codebase drifts from its spec.
REST API
The REST API is a conventional JSON API at https://specstep.com/v1/. It follows standard HTTP semantics: GET to read, POST to create, DELETE to remove. Responses are JSON. Errors follow RFC 7807 problem-details format.
Use the REST API when you are writing a script, a CI step, or any integration where you control the HTTP client directly.
- Quickstart — one copy/paste script, key to package
- Authentication — API key format, how to send it, revocation
- Rate limits — windows, headers, retry semantics
- Errors — status codes, problem-details shape, retryable vs non-retryable
- REST walkthrough — end-to-end flow from interview to delivered package
- OpenAPI document:
GET /v1/openapi.json(declares thebearerAuthsecurity scheme — codegen-ready)
MCP server
The MCP (Model Context Protocol) server exposes the same operations as discrete tools over JSON-RPC, transported via POST /mcp. Any MCP-capable client — Claude Code, Claude Desktop, or a compatible IDE extension — can connect to it and invoke SpecStep tools directly.
Use the MCP server when the caller is an AI agent. It removes the need to hand-craft HTTP requests and lets the agent treat SpecStep as a first-class tool.
- MCP walkthrough — transport, tool names, end-to-end flow
OAuth + discovery endpoints
These endpoints support the MCP browser-based sign-in flow. The discovery documents are anonymous; the authorize and token endpoints are part of the standard OAuth 2.1 + PKCE handshake. Full walkthrough lives in MCP server → Authentication.
| Endpoint | Purpose |
|---|---|
GET /.well-known/oauth-authorization-server |
RFC 8414 metadata: authorization_endpoint, token_endpoint, registration_endpoint, supported response/grant types, PKCE method (S256). |
GET /.well-known/oauth-protected-resource |
RFC 9728 metadata for the /mcp resource. The 401 WWW-Authenticate MCP clients see on first call points at this document. |
GET /oauth/authorize |
OAuth 2.1 authorization-code endpoint. PKCE-required (code_challenge, code_challenge_method=S256). Loopback redirect URIs only. |
POST /oauth/token |
Authorization-code → access-token exchange. Form-encoded body per RFC 6749 §4.1.3. Returns access_token (oat_…), token_type=Bearer, expires_in. |
POST /oauth/register |
RFC 7591 Dynamic Client Registration. Anonymous; rate-limited to 30 registrations / IP / hour. Returns a fresh client_id of the shape mcp_<32-hex>. |
Choosing between them
| REST API | MCP server | |
|---|---|---|
| Caller | Script, CI pipeline, human-written integration | AI coding agent, MCP client |
| Protocol | HTTP + JSON | JSON-RPC over HTTP POST |
| Discovery | OpenAPI document | Tool manifest via MCP handshake |
Both surfaces require an Authorization: Bearer … header. REST callers use an sf_… API key. MCP callers use either an sf_… API key or an oat_… OAuth token issued via browser sign-in.
Parity is close but not 1:1. The MCP tool catalog mirrors the REST surface for every operation an agent typically needs, but package delivery to GitHub is REST-only (
POST /v1/packages/{id}/deliver) — there is no MCP equivalent. Agent builders that need delivery have to fall back to REST for that step. Separately, the catalog any caller sees is scoped to its key's permissions: operator/admin tools are filtered out oftools/listfor standard customer keys (the MCP permission boundary explains what that means for what you'll see). See the MCP tool reference for the customer catalog and Step 7 of the REST walkthrough for the delivery flow.
Reporting a vulnerability
Found a security issue in the API, MCP server, OAuth flow, or any other SpecStep surface? See our Security policy for scope, safe harbor, and what to include in a report — or email security@specstep.com directly. We acknowledge every report within 72 hours. The standards-compatible discovery file lives at /.well-known/security.txt per RFC 9116.