Connect an MCP client to TOVIO

tovio mcp serve --token <token-id>tovio mcp serve --transport http --port 7744 --token <token-id>

Runs the MCP server (protocol tovio-mcp-v1.3) so an AI client can work in the repository under a capability token.

A token is mandatory

There is no unauthenticated mode. Supply --token <id> or set TOVIO_TOKEN; with neither, the launcher refuses with TVO-MCP-001. TOVIO_TOKEN also accepts the hex-encoded token a delegate was handed by issue_sub_token, which is how a sub-agent opens its own session without ever reading your token store.

Which transport

You rarely need --transport: supplying --port or --bind implies HTTP on its own.

The bearer secret rule

A loopback bind needs no bearer secret. A non-loopback bind requires one, supplied as TOVIO_MCP_BEARER, and the server refuses to start without it. If you are binding to anything other than localhost you are exposing a capability-bearing endpoint to the network — the refusal is there to make you decide that on purpose.

Issue the token first

tovio agent new assistant --model <id> --task "…" --expires-in 4

Hours, as a plain number. The client operates entirely inside whatever that token holds.

Checking what the client sees

Clients can call effective_scope to report what they hold — useful when an agent claims it cannot do something. Remember it is an echo, not the gate: the engine re-checks every call regardless.

Failures

• TVO-MCP-001 — no capability token was supplied.
• TVO-MCP-002 — the tovio-mcp-server process could not be started or exited badly. The launcher runs it as a separate program; check it is installed and on the path.
• Scope and permission denials keep their native TVO-TOKEN-* / TVO-PERM-* codes rather than being reskinned as MCP errors.