MCP servers

Model Context Protocol (MCP) servers are operator-owned. Apothem carries the MCP inventory in the shared profile (mcp_servers). An adapter whose tool keeps its MCP servers in a config file Apothem already writes projects that inventory into the file; every other adapter authors no server entries, and the servers stay yours to register through the tool.

Which adapters project the inventoryCopy Anchor Link

The table below is generated from the harness registry's mcp_servers capability cell for each adapter.

Where MCP servers registerCopy Anchor Link

Each tool registers MCP servers through its own native mechanism, and Apothem honors that surface rather than overwriting it. On Claude Code, servers register with claude mcp add into ~/.claude.json (user or local scope) and a project-level .mcp.json; the Claude Code adapter writes neither file, and Apothem's managed Claude Code settings never carry an mcpServers block.

Give a helper access to MCP serversCopy Anchor Link

The read-only research agents (research-scout, citation-auditor) ship with an explicit tools list of Read, Glob, Grep, WebSearch, WebFetch. Claude Code admits an MCP tool to a subagent's explicit list only when an entry names the server, in the form mcp__<server>__*. The profile's agent_mcp_servers key names those servers per agent:

agent_mcp_servers:
  research-scout:
    - "your-scholarly-server"
  citation-auditor:
    - "your-scholarly-server"

The Claude Code install adds one mcp__<server>__* entry per named server to each listed agent's tools line, and changes no other agent or line. With no key every agent keeps the plain list, so no agent reaches an MCP tool. Write each server name as /mcp shows it. Claude Code writes : and . as _ in tool names, so the install renders the server plugin:bio-research:biorxiv as mcp__plugin_bio-research_biorxiv__*. A name holds letters, digits, -, _, : and ., starts and ends with a letter or digit, and never has two of _, : and . in a row (the rendered entry would hold a __); *, whitespace and every other character are rejected. A grant names every tool of that server, including any that writes, so grant only a server you trust for lookups; the agents' instructions limit them to lookups, but the harness enforces only the names you list. A grant for an agent that does not exist, or one without an explicit tools list, is reported and skipped. A per-harness override under harnesses.claude-code adds to the shared lists.

The grant applies to the engine install (apothem install) on Claude Code and on Gemini CLI. On Gemini CLI the install adds one mcp_<server>_* entry per named server to the listed agent's tools allowlist, for example mcp_your-scholarly-server_*, and changes no other agent or line. Gemini CLI names every MCP tool mcp_{serverName}_{toolName} and reads the server from the text up to the first underscore after mcp_, so a server name with an underscore cannot be addressed there. Apothem writes a Gemini CLI grant only for a name of letters, digits and -: a name with an underscore, colon or period is valid for Claude Code but is skipped for Gemini CLI and reported, never rewritten into another name. An agent that already reaches every MCP server (no tools list, or one that holds mcp_*) is left unchanged and reported. Gemini CLI has no deny list, so a server the agent's own disallowedTools names gets no entry and is reported: the denial wins, as it does on Claude Code. The Gemini grant reads the shared agent_mcp_servers lists and the harnesses.gemini-cli override, not the harnesses.claude-code one. Other harnesses ignore the key: Qwen Code documents no per-server entry for tools; OpenCode controls tools through permissions; Codex and Antigravity emit no tool list.

The Claude Code plugin is assembled without a profile, so its two agents keep the plain list. To give them connector access without editing plugin files, define a user-level agent of your own in ~/.claude/agents/, under a name of your choosing, that carries the same read-only tools list plus the mcp__<server>__* entries you want.

Adding a serverCopy Anchor Link

Register a server through your tool's native mechanism; the canonical entry shape is one key under mcpServers:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/some/path"]
    }
  }
}

The tool's runtime loads the registered servers on session start; restart the tool to pick up new servers.

Naming conventionCopy Anchor Link

MCP tools surface to the assistant as mcp__<server>__<tool> per the tool's standard MCP-tool naming convention.