Skip to content

0031. MCP surface: stateless JSON-RPC over the action registry, with output schemas

  • Status: Proposed
  • Date: 2026-11-09

ADR 0005 requires every action to exist in REST, MCP, OpenAPI, and the docs with the same inputs, validation, and errors. ADR 0019 makes the action registry in core/actions the single declaration that generates them. The walking skeleton (ADR 0030) built REST only and listed MCP, OpenAPI, the docs index, llms.txt, the parity test, and an output schema per action as the next step.

Facts checked on 2026-11-09:

  • The official TypeScript SDK, @modelcontextprotocol/sdk 1.32.2, depends on about 17 packages, including express, and validates tool input with its own zod handling.
  • The Streamable HTTP transport of the MCP specification (2025-11-25) allows a stateless server that answers each POST with one JSON reply, with no session and no server-sent events.
  • Model APIs that MCP clients pass tools to, such as the Anthropic and OpenAI APIs, accept only ^[a-zA-Z0-9_-]{1,64}$ as a tool name, so dotted names such as customers.upsert are not portable even where MCP allows them.
  • MCP OAuth (ADR 0025) is not built yet; project API keys authenticate the API today (ADR 0026).
  • Transport. surfaces/mcp implements stateless Streamable HTTP itself, without the SDK: POST /mcp carries one JSON-RPC 2.0 message and gets one JSON reply. It answers initialize (protocol versions 2025-11-25, 2025-06-18, and 2025-03-26; the client’s version if listed, else the newest), ping, tools/list, and tools/call. A message is a request if it has a string method and an id, a notification if it has a string method and no id, and a response only if it has an id and a result or error. Notifications and responses get 202; a non-string method, or a message with neither a method nor a result or error, gets 400 with -32600; initialize without a string protocolVersion gets -32602. GET and DELETE get 405, and an unsupported MCP-Protocol-Version header gets 400. A JSON-RPC batch is refused with -32600 under every version. This knowingly deviates from the 2025-03-26 specification, which requires servers to accept batches; 2025-06-18 removed them, and supporting them for one old version is not worth a second dispatch path. A request with an Origin header gets 403: the specification requires validating Origin, and no browser-based client is supported yet. The SDK would add a dependency tree to the Worker and a second input validation that differs from invokeApiAction’s, for four methods.
  • One dispatch path. Every tool call goes through invokeApiAction, the same function REST uses, so scope checks, input validation, and errors are identical by construction.
  • Tool names. A tool is named after its action with the dot replaced by an underscore: customers.upsert becomes customers_upsert (mcpToolName). A registry test requires action names of the form resource.verb in camelCase, so the mapping is one-to-one and derived only from the action name. Each tool’s _meta carries the action name and its declared error codes.
  • Tool definitions. Each tool carries the action’s input and output JSON Schemas (JSON Schema 2020-12 from z.toJSONSchema, produced once in core/actions/json-schema.ts and used by both OpenAPI and MCP) and the annotations readOnlyHint, idempotentHint, and destructiveHint.
  • Output schemas. Every api action declares an output zod schema. invokeApiAction parses each result with it, which drops undeclared fields, so internal fields cannot leak through either surface. A result that does not match is an internal error whose message names only the failing paths, never the values.
    • Published output schemas are open: outputJsonSchema removes additionalProperties: false at every level. MCP clients cache the tool list and validate structuredContent against it, so a closed schema would make every new response field a breaking change for connected clients. A registry test checks every action.
    • Output schemas describe structure, not input rules: a saved workflow definition is read back with a structural schema derived from workflowDefinitionSchema (structuralSchema), without its limits and refinements, so a step type or field is defined in one place and tightening input validation never turns reading an older definition into an internal error. Removing a step type or an enum value, or making an optional field required, narrows the view too and needs a migration. metrics.get returns a typed view too, whose mapping fails to compile when the command adds a metric the view does not declare.
  • Error mapping.
    • The error body {"error":{"code","message","issues"}} is defined once in core (errorBodySchema, toErrorBody). REST returns it, MCP tool errors carry it, the OpenAPI Error component is generated from it (its codes include internal_error, and every operation has a default response), and the docs list its fields from it. The parity test compares the bodies both surfaces return.
    • An ActionError (validation, forbidden, not found, and the other declared codes) is a tool result with isError: true whose text is the error body. It has no structuredContent, so clients do not validate it against the output schema.
    • An unknown tool or arguments that are not an object return JSON-RPC -32602; an unknown method returns -32601.
    • Any other error, including a failure to authenticate, returns -32603 internal error, with no detail (REST: 500 internal_error). Both surfaces log only the error’s name and its message, with credentials, email addresses, and IP addresses masked (ADR 0032).
    • Missing or invalid credentials return HTTP 401 with WWW-Authenticate: Bearer.
  • Authentication seam. createMcpHandler takes an authenticator, (request) => Promise<Authentication<ProjectKeyCaller>>: the caller, or the refusal (missing or invalid_token) from which the surface builds its 401 challenge, as REST does from the same core/auth result (ADR 0051, built as its P1). apps/workers passes the project API key authenticator. MCP OAuth adds the grant to the authenticator, and the scope ∩ role check to dispatch (ADR 0051); the tools do not change.
  • No real mail yet. Sending actions need the server-side confirmation of ADR 0005, because a client may ignore tool annotations. Until it is built, apps/workers refuses at composition time to wire any email provider but the fake one (assertEmailProviderAllowed). The provider is hard-wired today, so the check guards the change that wires a real one rather than any runtime choice; when the provider becomes configurable, the check belongs where it is chosen.
  • OpenAPI and docs. The HTTP surface serves OpenAPI 3.1 at GET /api/openapi.json, generated from the registry with the same schemas, each operation’s error responses, and its tool name (x-mcp-tool). The API reference (docs/api/reference.md) and docs/llms.txt are generated from the registry by pnpm docs:generate, and a test fails when the committed files are stale. /llms.txt is not served by the API, because ADR 0028 routes the root path to the dashboard.
  • Parity and isolation tests run against the Worker: every REST operation is an MCP tool and no other tool exists, both surfaces publish the same input schema, output schema, and errors per action, endpoint actions are on neither surface, and every tenant isolation case runs on REST and on MCP.
  • An AI assistant can create, activate, and operate a workflow through /mcp with a project API key, and invalid input comes back with the path and reason of each issue, as in REST.
  • Adding an api action adds its route, tool, OpenAPI operation, and docs entry; the parity, isolation coverage, and stale-docs tests fail until it has an output schema, an isolation case, and regenerated docs.
  • Following protocol changes is our work rather than an SDK upgrade. An interop test with the official SDK client would catch drift.
  • Open:
    • MCP OAuth through Better Auth, with resource_metadata in WWW-Authenticate and the /.well-known metadata (ADR 0025).
    • The server-side confirmation for sending actions (ADR 0005); it lifts the fake-provider-only check.
    • An authentication seam that carries the 401 challenge ({ caller } | { challenge }) for REST and MCP alike, with resource_metadata for OAuth.
    • An Origin allowlist, needed before browser-based MCP clients are supported.
    • Whether an insufficient OAuth scope stays a forbidden tool result, as for API keys, or becomes HTTP 403 insufficient_scope to start step-up authorization.
    • Tool titles and the openWorldHint annotation.

Amendment (2026-11-18, pending ADR 0041, Proposed): actions that need a signed-in user are listed as tools like every api action (ADR 0005) and answer forbidden over MCP, to project keys now and to OAuth grants later; their descriptions say so. /mcp never accepts the dashboard’s session cookie (ADR 0040).

Amendment (2026-11-18, ADR 0044, decided by the maintainer): the server-side confirmation of sending actions is ADR 0033’s send approval, required only in workspaces that turn it on (off by default). Where it is off, workflows.activate makes a sending version live at once, and pause and rollback are the safeguards. Proposed in ADR 0044, not decided: workflows.activate becomes annotated destructive.

Amendment (2026-11-18, ADR 0042): the open point on the public URL of the generated docs is resolved. docs/llms.txt links to api/reference.md relatively, which would resolve under /api/* (the API Worker, ADR 0028) if llms.txt were served at the app domain’s root. The public site serves it at its own root with absolute links.

Amendment (2026-11-19, pending ADR 0050, Proposed): the server-side confirmation that “No real mail yet” waits for is ADR 0050’s preview-then-confirm. Once it is built, assertEmailProviderAllowed is removed with the rest of B4’s deploy gate (plan-limit budgets, sender protection, pause and rollback, the SES go-live runbook).

Amendment (2026-11-20, pending ADR 0051, Proposed): its open items on MCP OAuth and the authentication seam that carries the 401 challenge are decided there: core returns a refusal reason and /mcp answers 401 with resource_metadata. A grant’s scope ∩ role check runs in dispatch (invokeApiAction), not in the authenticator. A grant missing an action’s scope gets a forbidden tool result naming the scope; the HTTP 403 insufficient_scope step-up waits until a spike shows the target clients follow it.