Skip to content
Vulpine
Esc
↑↓navigate↵open⌘Jpreview
On this page

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-server mcp__<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 by just docs-site-roll.
  • homeha (ha-mcp 8.5.0 inside Home Assistant): its /readonly webhook, 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) and FOX9_HA_MCP_TOKEN come 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 loopback http://127.0.0.1:51234/mcp with no token. omni.json is read only when VULPINE_LOADOUT=omni. Only search and file_status are allowed (READ_ONLY_SERVERS), the server must give includeTools, 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-add gives Claude Code the same two tools through tools/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 description and inputSchema may be overridden. Any other key refuses the override. A description is one or two lines, at most TOOL_OVERRIDE_DESCRIPTION_MAX = 300 chars, and says when the brain should call the tool.
  • An override for a tool not in directTools is 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 inputSchema may 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

  1. Add it to the profile file with an explicit directTools list (the tools the brain may see; a server without one is refused at load).
  2. Add each <server>_<tool> name to allowed_pi in that loadout (catalog/agents/operator/.vulpine/loadout.toml or loadouts/<profile>.toml) and to the expected list in crates/voice_gateway/src/loadout.rs’s test.
  3. Pull the gateway host’s checkout and kickstart the gateway; read brain_identity_bound for 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+.

Was this page helpful?