The agent interface

Torno is built to be operated by agents and governed by humans. Every capability is registered once and exposed through the web app, the public REST API, the torno CLI, and MCP — one contract, four doors.

One capability map, four surfaces

Parity is a product rule, not an aspiration. A UI action without an API and CLI path is treated as an incomplete feature, and MCP tools are generated from the same registered capability map that binds the UI, REST routes, and CLI commands. Each capability row declares its required scopes, REST method and path, CLI binding, MCP tool, and whether it is destructive or approval-gated. Continuous checks reject a capability that is missing a surface, so the four doors cannot quietly drift apart.

Being listed is not permission. The runtime can still refuse a capability by scope, state, or policy — see Policy and approvals.

Authentication and Principals

The public API lives under /api/v1. Every request runs as a Principal — a human session or an API key. Keys are shown once and stored as digests, carry scope and ceiling metadata, record last use, and support rotation grace and immediate revocation. Machine Principals are created by humans and inherit policy constraints. Per-Principal rate limits and request logs keep API behavior auditable, and unauthorized reads of sensitive objects are indistinguishable from missing data.

Agent mutations require a reasoning field. It is stored as a claim — quoted, fenced, attached to the audit record — and never treated as an instruction to the system.

Idempotency and approvals

Mutations use idempotency keys; the CLI and MCP generate them automatically, and direct API clients supply their own. A receipt binds the Principal, the capability, and the request body, and reusing a key with a different body is rejected. When policy requires approval, the call returns a structured requires_approval outcome with a reference — the action has not run. After a human approves, a single-use execution grant replays the same idempotent request. No blind retries, no double execution.

Webhooks and SSE

Webhook endpoints subscribe to a pinned event catalog covering Signals, Insights, evidence, Metrics, approvals, Decisions, and Loop transitions. Deliveries are signed, filtered by type, retried on a published schedule, dead-lettered when exhausted, and redeliverable; endpoint secrets rotate. A server-sent events stream carries the same sequence and resumes from a cursor, returning an honest expired-cursor error rather than silently skipping. Together they let an agent sleep until something happens — a new Signal, an evidence change, an Approval Request — instead of polling.

Reading everything out

There is no lock-in by omission. The API includes paginated reads across the full ontology — Loops, Signals, Insights, Hypotheses, Changes, Experiments, Decisions — plus raw-event export from event collection. What Torno records about your growth work is yours to take elsewhere.

MCP

torno mcp serve runs an MCP server over stdio. Tools are generated from every capability row and annotated as read-only, destructive, idempotent, or approval-gated. Resources expose the current Loop context, Decisions, Change briefs, Signals, Workspace capabilities, and documentation; prompt templates cover Hypothesis proposal, Experiment planning, Signal triage, and Decision recording. Signal-bearing results stay fenced as untrusted data.

Honest note: MCP is local stdio today. The server runs next to your agent and talks to Torno over the same authenticated API. A remote MCP endpoint over HTTP is not available yet.

Agent documentation

GET /api/v1/docs/agent renders a reference straight from the capability map: the product model, auth, response envelopes, the error and exit taxonomy, every surface with its approval flags, the event catalog, and a golden path. The CLI bundles a snapshot, so torno docs --agent works offline and without credentials. See The CLI and Loops as code for the rest of the agent toolchain.