ADR-0008 — The MCP server is a thin client of the REST API, with bearer authentication
Status: accepted for V1, 2026-11-09. Describes the build contract for apps/registry-mcp.
Decision
- The registry MCP server implements the Model Context Protocol with the official TypeScript SDK and exposes two transports: Streamable HTTP at
/mcp(stateless, JSON responses) and stdio (apps/registry-mcp/src/stdio.ts). - Every tool is implemented by calling the REST API through
@skills/sdk. The server holds no database connection and no privileged credential of its own. - For authenticated tools, the caller's
Authorization: Bearer skr_…header is forwarded to the REST API unchanged. For stdio, the token comes from the environment. - Archive bytes never travel through MCP.
begin_release_uploadreturns an upload URL; the client sends the archive with an HTTPPUT, then callsfinalize_release. - There is no tool for shell execution, filesystem access on the server, token readback or fetching arbitrary URLs.
Why
RBAC, scopes, namespace checks, rate limits, idempotency and audit already exist in the REST layer and are tested there. Reusing them through HTTP makes the two surfaces identical by construction, and a bug in an MCP tool cannot bypass authorization because the tool has no authority of its own.
Authentication caveat
The MCP specification (revision 2026-07-28) makes authorization optional and, when used over HTTP, describes an OAuth 2.1 flow. It does not define static bearer tokens. Sending an API token in the Authorization header is common practice supported by Claude Code, Codex and Cursor, and is what V1 does. OAuth 2.1 with protected-resource metadata is Planned.
Consequences
- Tool output is registry content written by third parties. Clients must treat it as untrusted data, not as instructions.
- One extra loopback HTTP hop per tool call.
- Clients that only speak the OAuth flow cannot use the authenticated tools until OAuth is implemented; public tools need no authentication.