---
title: "MCP servers"
description: "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."
type: "living"
source: "catalog/pi/extensions/mcp/README.md"
verified: "2026-11-14"
group: "The brain"
---

> **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](https://github.com/nicobailon/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+.

