MCP servers
Which MCP servers the voice brain can use: moraine (the agent-session index) and fox9docs (the docs site on the mini), declared per loadout profile in catalog/agents/<agent>/.vulpine/mcp/<profile>.json as a secondary path; the brain sees only the tools the loadout's allowed_pi lists.
Living doc, checked against the code 2026-11-14
The voice brain’s default profiles use three MCP servers, listed below with a fourth that no loadout allows. MCP is a secondary path: every primary need is a first-party tool. Servers are declared per loadout profile, the way Claude Code declares them, in
catalog/agents/<agent>/.vulpine/mcp/<profile>.json (profile = the loadout name, VULPINE_LOADOUT)
catalog/agents/<agent>/.vulpine/mcp/default.json (fallback)
example.json beside them shows the shape (one HTTP server, one stdio server).
The file goes to pi-mcp-adapter (MIT, 5.4.0) as an isolated
snapshot: nothing ambient (~/.config/mcp, ~/.claude.json, a project .mcp.json) is merged in. These settings
are pinned whatever the file says:
directTools: true,scriptMode: false,disableProxyTool: true,hostConfigDiscovery: "off",sampling: false,autoAuth: false;namespaceProxyTools: false: no per-servermcp__<server>proxy;allowInstall: false: no agent-installed endpoint;jev: false: no semantic tool search. 5.x turns it on by itself when a System One key is in the environment, and it sends tool metadata to that endpoint.
The brain sees only direct tools named <server>_<tool>, and only those the loadout’s allowed_pi lists.
Servers
moraine(socket): the agent-session index —moraine_list_sessions,moraine_search_sessions,moraine_file_attention.fox9docs(http://127.0.0.1:7806/docs/mcp, the docs site on the gateway host):fox9docs_search_docs,fox9docs_get_page,fox9docs_list_pages, filtered by type (living, decision, generated, record, skill) and facets. Rebuilt byjust docs-site-roll.homeha(ha-mcp 8.5.0 inside Home Assistant): its/readonlywebhook, with an HA bearer token. Eight read tools only (HOMEHA_READ_TOOLS: history, logbook, automation and script traces, states, search, areas). homectl is the only actuator.FOX9_HA_MCP_URL(the secret webhook path) andFOX9_HA_MCP_TOKENcome from~/.config/foxline/mcp.env(0600,FOX9_keys only) on the brain host. A server whose variables are unset is skipped, and the others still load.omni(no loadout allows it): Omni, local semantic file search (Apache-2.0), on loopbackhttp://127.0.0.1:51234/mcpwith no token.omni.jsonis read only whenVULPINE_LOADOUT=omni. Onlysearchandfile_statusare allowed (READ_ONLY_SERVERS), the server must giveincludeTools, and a profile naming any other omni tool is refused at load. Its results are fenced as untrusted text and count as private reads in the guard’s flow tier.just docs::omni-mcp-addgives Claude Code the same two tools throughtools/gateway/mcp_stdio_bridge.py --allow-tools.
loadProfile refuses any server listing a write-shaped tool name (call_service, ws_command, manage, write,
delete, restart, bulk, config_set, eval, …), whatever the server says about the tool.
Tool overrides (what the brain reads about a tool)
A server’s tool descriptions ride in every voice turn’s prompt, and they can be long. A server entry may carry
toolOverrides, keyed by the tool’s MCP name:
"toolOverrides": {
"ha_get_state": {
"description": "Current state and attributes of one entity_id or a list. Use for what something is doing now …",
"inputSchema": { "type": "object", "properties": { "entity_id": { "type": "string" } }, "required": ["entity_id"] }
}
}
The extension swaps the override in when the adapter registers that <server>_<tool> name. The rules:
- Only
descriptionandinputSchemamay be overridden. Any other key refuses the override. A description is one or two lines, at mostTOOL_OVERRIDE_DESCRIPTION_MAX= 300 chars, and says when the brain should call the tool. - An override for a tool not in
directToolsis refused with a warning, and the profile still loads. An override naming a write-shaped tool refuses the whole profile. An override never admits a tool. - A trimmed
inputSchemamay only narrow the server’s: every parameter it names must exist on the server, and every required parameter must stay required. Otherwise the server’s schema is kept (logged). Narrow types only to ones the server accepts (a string where it takes string-or-list).
The checked-in profiles slim the eight homeha tools from 32.4 KB to 2.9 KB and the three fox9docs tools from 3.6 KB
to 0.8 KB. To undo, delete a server’s toolOverrides.
The tool catalog (catalog/pi/tool-catalog.json) reads the servers from these profile files, so a new server’s
tools are cataloged without a code change.
The MCP catalog (what the brain has)
The gateway’s MCP catalog lists each server with:
- its tools, and the loadouts each tool is on, deferred or switched off in;
- whether the server answered on the brain’s host (pi-mcp-adapter’s
mcp-cache.json: names and a time only); - the usage ledger’s calls and failures.
The Admin shows it as the Tools section’s MCP servers card (get_mcp_catalog). The brain reads it with
brain_vulpine_report {topic: tools}. A server dropped for an unset ${VAR} shows as not_seen, because the
gateway never reads mcp.env.
Adding a server
- Add it to the profile file with an explicit
directToolslist (the tools the brain may see; a server without one is refused at load). - Add each
<server>_<tool>name toallowed_piin that loadout (catalog/agents/operator/.vulpine/loadout.tomlorloadouts/<profile>.toml) and to the expected list incrates/voice_gateway/src/loadout.rs’s test. - Pull the gateway host’s checkout and kickstart the gateway; read
brain_identity_boundfor the tool list.
Never declare a server that runs a shell or writes files for the brain. Nothing the voice brain reaches may expose freeform shell or keystroke synthesis, and approvals stay with the operator.
Deploying the dependency
The adapter is an npm dependency of this directory (node_modules is ignored). On each brain host, in the checkout:
cd catalog/pi/extensions/mcp && npm ci
The directory’s .npmrc sets ignore-scripts=true (no package’s install script runs) and legacy-peer-deps=true.
The adapter’s peers (typebox, @earendil-works/pi-tui, @earendil-works/pi-ai) come from Pi’s extension loader,
so npm does not install copies here. Without the dependency the extension logs “pi-mcp-adapter is not installed” and
registers nothing, and the brain stays up. The adapter needs Node 20+.