MCP client will not connect

TVO-MCP-* covers launcher configuration and process startup. Protocol-level denials keep their native TVO-TOKEN-* / TVO-PERM-* codes — which tells you where to look.

The two launcher codes

• TVO-MCP-001 — no token. The launcher never falls back to ambient human authority; every server process is bound to one explicit capability token. Pass --token or set TOVIO_TOKEN.
• TVO-MCP-002 — the tovio-mcp-server executable could not be started or did not run successfully. The cause keeps the executable name and the OS error without exposing token contents.

stdio

tovio mcp serve --transport stdio --token <token-id>

The client launches this as a subprocess, so the failure is usually that it cannot find tovio on the PATH it uses, that tovio-mcp-server is not installed, or that the working directory is not a repository. Check the client’s configured command and cwd. This is the default transport and the right one for a local client.

HTTP

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

Defaults are 127.0.0.1 and port 7744; the endpoint is /mcp. Supplying --port or --bind implies HTTP.

Binding to anything other than 127.0.0.1, localhost, or ::1 requires a bearer secret in the TOVIO_MCP_BEARER environment variable, and the server refuses to start without one.

Do not expose the HTTP transport directly

The server speaks plain HTTP only — it has no TLS option. The bearer secret is sent in an Authorization header, so on a non-loopback bind without TLS it crosses the network in cleartext and anyone on the path can read it and replay it against a capability-bearing endpoint. The bearer check is a useful second control; it is not transport security, and the refusal to start without one should not be read as the bind being safe.

For any access beyond the local machine:

• Keep the server bound to loopback.
• Put a TLS-terminating reverse proxy in front of it, and let only the proxy reach the loopback port. Clients connect to the proxy over HTTPS.
• Set TOVIO_MCP_BEARER as well, so the token is required in addition to TLS rather than instead of it.
• Treat the secret like any other credential: generate it randomly, keep it out of shell history and process listings, and rotate it.

An SSH tunnel to the loopback port is a fine alternative, and needs no proxy.

Connects, then cannot do anything

That is scope, not connection. Have the client call effective_scope, and check tovio agent show <token-id>. Expired or revoked tokens give TVO-TOKEN-*.

A tool is missing

The manifest is capability-gated, so a narrow token sees fewer tools. Some are absent for everyone by construction — obliterate, policy modification, key management, tag force. No token unlocks those.

Reporting it

The code, the transport, and whether the bind was loopback. Never the bearer secret, the token id, or the URL you bound.