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. See the MCP tool reference for the full 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.