mcp section; the runtime probes it at startup and binds its tools alongside your local ones.
Declare a server in the manifest
Eachmcp entry names one server. Set exactly one transport per entry — the runtime infers the transport from whichever field you set:
urlfor a remote HTTP or SSE server (with optionalheaders),udsfor a Unix domain socket,command(plusargs/env) for a stdio server the runtime launches.
manifest.yml
include / exclude on an entry to expose only a subset of the mounted server’s tools.
Inspect and reload
1
Check binding status
Snapshot the live MCP binding state — which servers attached, which were skipped by a failed viability probe, and each attached server’s recent dispatch health.The payload carries three blocks: Each
bound maps each attached server’s title to the tool names it serves, failed lists the titles a viability probe skipped with a coarse status, and health reports each server’s most recent tool-dispatch outcome, keyed by title.health entry has four fields, detailed in the health block reference below.2
Replace the set at runtime
Write the full replacement
mcp list to a JSON file, then apply it. This hot-reloads the section without restarting the server. set remains the bootstrap and restore path — use it to lay down the whole section at once.3
Add or remove one entry
Change a single server without rewriting the whole list.
tai mcp add appends the entries in a JSON file — one entry object, a bare array, or an object carrying an "entries" list — and refuses a title that already exists unless you pass --replace, which swaps the existing entry in place. tai mcp remove deletes one entry by its title. Both hot-reload the section.remove is a persisted change — it edits the manifest, so the server stays gone across a restart. deregister is a runtime-only detach — it drops the server’s tools from the live registry but leaves the manifest untouched, so the next reload brings it back.4
Reload one server
Re-probe a single server by its manifest title and re-attach it if it is viable. A successful reload also drops that server’s pooled dispatch session, so the next tool call opens a fresh connection instead of reusing a stale one. A reload that finds the server unreachable reports it unavailable and leaves the session as is — once the server is back, the next tool call reconnects on its own; while it stays down, calls return the structured error described below.
A server that fails its viability probe is skipped, not fatal — the rest of the manifest still loads. Inspect skipped servers under
tai mcp status.The health block
Each health entry has four fields:
health covers every bound and failed title. A server that has never been called carries the block at its empty values — last_success, last_error, and failing_since null, consecutive_failures 0. A server that has only ever succeeded carries last_success with last_error and failing_since null. An auth-blocked dispatch records nothing: it signals credential state, not connection health, so it leaves the health block untouched. The health is this worker’s own passive view — per process, so a fleet report reads each worker’s dispatches separately.
When a mounted server’s tools fail
A tool call against a mounted server whose connection has dropped gets one automatic reconnect attempt. If the reconnect succeeds the call runs on the fresh session. If the server is still unavailable, the call returns a structured error whosecode is upstream_mcp_unavailable, with a message that names the entry by its configured title. The raw disconnect detail never reaches that message — it is logged at the dispatch seam, not surfaced to the caller.
See also
- Transports — the HTTP, SSE, stdio, and UDS paths a mounted server can use.
- The manifest — the
mcpsection and its selection fields. - Live operations — hot-reload and deregister at runtime.
- CLI reference — the full
tai mcpsurface.