Skip to content

0005. REST, MCP, OpenAPI, and docs parity

  • Status: Accepted
  • Date: 2026-11-07

Users operate Customer.lite through their own AI assistant. The MCP surface must be as complete and predictable as the REST API.

  • One MCP tool per REST endpoint, with identical inputs, validation, and errors.
  • Tool annotations mark each tool read-only, idempotent, or destructive. Sending actions require user confirmation.
  • API keys are scoped, for example ingest-only. MCP accepts OAuth and API keys.
  • Publish llms.txt.
  • A parity test fails when an action is missing from REST, MCP, OpenAPI, or the docs.
  • Adding an action is one change that touches all four surfaces; use the add-api-action skill.
  • Tool annotations are hints that an MCP client may ignore, so the confirmation requirement needs a server-side guard. Proposed: a preview call returning a short-lived confirmation token, or a separate send scope. The mechanism is open.
  • Proposed: define each action once and generate the surfaces from it (see docs/architecture.md).
  • Open: OAuth provider and scope names.

Amendment (2026-11-18, ADR 0044, decided by the maintainer): the server-side confirmation of making a sending workflow live is ADR 0033’s send approval, and it is required only in workspaces that turn it on; it is off by default. Elsewhere there is no server-side confirmation, and the server’s safeguards are pause and rollback. Proposed in ADR 0044, not decided: workflows.activate becomes annotated destructive, so a client that honours annotations asks the user.

Amendment (2026-11-19, the maintainer’s decision, recorded in ADR 0050, Proposed): every action that can start real sends needs a server-side confirmation in every workspace, including where approval is off: called without a token it returns a preview and a short-lived token bound to the credential, the action, and the canonical input, and only the call with that token commits. This replaces “Elsewhere there is no server-side confirmation” of the amendment above. It proves the commit matches a fresh preview, not that a person saw it; the send approval of ADR 0033 stays the optional proof of a human decision.