0028. MCP tools and CLI commands are derived from API operations
Status: accepted, 2026-10-21
Context
The vision says everything has an API, a CLI and MCP tools. In practice seven services have
hand-written tools and ten have none; tool names and inputs drift from the API they wrap; no tool says
whether it only reads or destroys something; home's /mcp asks every installed service for its tools on
every request; and six services have no CLI commands. With operations declared in Go
(0027), each one already knows its inputs, output, scope, risk and
access, which is everything a tool or a command needs, and approvals (0025) give a
way to let agents near risky operations safely.
Decision
- Every operation is an MCP tool unless a rule or its own flag says otherwise. Out by rule:
internal and service-only operations, operations only a person's own sign-in may call, streams,
uploads and downloads, operations that reveal secrets, and high and critical operations of a service
whose router doesn't gate approvals yet. A tool is named
<service>_<operation id>, takes the
operation's path, query and body fields as one object, declares its output schema and answers
structured content. Its annotations come from the risk (read-only for none, destructive for high and
critical) and the operation (idempotent); secret fields are redacted from results.
- There are no MCP-only tools. If an agent needs something the API can't do, the API gets an
operation for it.
- A service's
/mcp is derived from its document and runs tools in-process through the same
router as the API, as the caller, so a tool can do exactly what the token can and meets the same
approvals; it lists only what the caller may call.
- home aggregates from a catalog, not by fan-out. home builds its catalog from the services'
documents (refreshed on new versions and every few minutes;
tools/list for services without one) and
by default offers two meta-tools, xvii_find_operation and xvii_call_operation, plus a small pinned
set; every tool, or one service's, on request; a read-only mode that refuses anything else.
xvii mcp is a proxy of it.
- The CLI covers every operation.
xvii api <service> <operation> calls any operation from the
instance's own documents, with no CLI release. First-class commands come from operations with CLI hints
through kit/cli (flags, positional arguments, tables, --json, confirmation by risk, names resolved to
ids). Hand-written commands remain for local work and long flows.
Consequences
- Every service gets MCP tools and CLI coverage as it migrates; existing tool names are kept by choosing
operation ids to match, and renamed ones keep an alias for one release.
- Tools mirror the API's names and units, so field descriptions must state units; the API improves for
people and agents at once.
- Risk is the shared signal for confirmation across panels, the CLI, Telegram and the native apps, as it
is for approvals.
- conventions/api.md (the MCP endpoint), cli.md (command groups,
xvii api) and the MCP guide change
when kit/api ships.
- Design:
superpowers/specs/2026-10-21-api-contracts-design.md in this repository.