0005. REST, MCP, OpenAPI, and docs parity
- Status: Accepted
- Date: 2026-11-07
Context
Section titled “Context”Users operate Customer.lite through their own AI assistant. The MCP surface must be as complete and predictable as the REST API.
Decision
Section titled “Decision”- 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.
Consequences
Section titled “Consequences”- Adding an action is one change that touches all four surfaces; use the
add-api-actionskill. - 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.