Run and scope the MCP server

The MCP server (tovio-mcp-server) exposes TOVIO to any Model Context Protocol client as a set of capability-gated tools. It speaks protocol tovio-mcp-v1.3.

Start it

tovio agent new reviewer --model anthropic:claude --task "review the auth module" --expires-in 8

tovio mcp serve --token cap_…

The CLI never interprets the token itself. It resolves the repository, hands the server the token id, and runs the independently packaged server binary. A missing token is TVO-MCP-001; a server binary that cannot start is TVO-MCP-002.

Transports

Over HTTP the endpoint is /mcp and each protocol session gets its own engine-backed session and its own in-memory working change.

The bind rule

HTTP defaults to loopback and needs no shared secret there. A non-loopback bind requires TOVIO_MCP_BEARER to be set; without it the server refuses to start rather than listening on the network unauthenticated. Requests then need Authorization: Bearer <secret>, compared in constant time; a mismatch is 401.

The bearer is transport hygiene, not authorization. It gates who may talk to the process. What that process may do is entirely the capability token's scope, re-checked in the engine on every call.

Environment

Failing closed

The connect handshake runs before any transport is accepted. An unknown, expired, or revoked token means the process exits with the refusal — there is never a running server holding a bad token. The server writes its readiness line to stderr so stdio framing on stdout stays clean. The stdio line names the agent, the number of scope globs, and the clearance flag; the HTTP line names the bound URL and the agent only, so check effective_scope from the client if you need the rest.

Which tools a token unlocks

A session is offered exactly the tools its token's operation set unlocks. A token without commit is not shown a commit tool that then fails — the tool is not in its catalog at all.

Reads

effective_scope is also a resource at tovio://session/effective-scope, for clients that prefer to attach scope as context rather than call a tool for it.

Writes

Absent by construction

There is no MCP tool for policy:modify, obliterate, tag:force, or key management. Those are not hidden behind a flag or a scope — no tool implements them, so no token and no prompt can reach them through this edge. An agent that needs a policy change has to ask a person.

Every call is re-enforced

The edge holds only the serialized token and re-presents it on every call. The engine re-validates signature, expiry, revocation, path scope, lane scope, operation set, and secret_clearance each time — so a token revoked mid-session fails the next operation, not the next reconnect. A clearance-gated path read without secret_clearance is TVO-PERM-001.

Protected content is audited before it is released

A protected read_file, diff side, conflict side, or sealed symbol shard is released only after the engine appends a signed read-audit entry binding this agent principal and this token. Where it cannot be released you get a redaction marker, never a silent empty result.

The tool catalog is recorded on every commit

The exact catalog a session negotiated — protocol version, per-tool JSON Schemas, canonical operation names — is serialized deterministically and hashed into the tool_manifest_hash on every commit that session makes. Two sessions with the same protocol version and the same token operation set record the same hash, so the tools an agent held when it wrote a change are diffable after the fact.

Sub-agents

A delegate does not need an entry in your token store. tovio agent token <token_id> prints the hex-encoded signed token bytes, and TOVIO_TOKEN accepts them directly — so a sub-agent holding only a leaf can start its own server, and the engine reconstructs and revalidates the whole chain to its human root before the session exists.