Starts the MCP servers from mcp_config.json and exposes their tools to the agent.

The file is the one that super-pi mcp add|remove|enable|disable edits (in the global config dir). Each enabled server is started once under SuperPi.MCPClientSupervisor. Its tools join the tool catalog as mcp__<server>__<tool>, so the model sees which server a tool belongs to and two servers cannot collide. SuperPi.Tools.execute/3 routes those names to call_tool/3.

Tool calls pass the same before_tool pipeline as built-in tools, so the permission policy applies. Every MCP tool is registered with an "effects" list, which is what the policy decides by (SuperPi.Plugins.Permissions): ["net_read"] when the server annotates the tool readOnlyHint: true, else ["net_write"]. A read-only tool runs without a prompt under accept-edits and in plan mode. Any other tool needs auto mode, a prompt answer, permissions.allowTools, or dangerouslySkipPermissions. The network policy (deny, allowlist) applies to every MCP tool, a local stdio one included, because the server may do anything.

Configuration

config :super_pi,
  mcp_clients: true,           # start servers when a conversation starts
  mcp_tool_exposure: :direct,  # or :deferred (found through `tool_search`)
  mcp_startup_timeout_ms: 10_000,
  mcp_call_timeout_ms: 60_000

Server entries

Each entry under "mcpServers" is one of two shapes. Both accept "disabled": true.

A local process, over stdio:

{"command": "npx", "args": ["-y", "some-server"], "env": {"TOKEN": "..."}}

A hosted server, over Streamable HTTP (url, or serverUrl as other hosts write it):

{"url": "https://mcp.example.com/mcp",
 "headers": {"Authorization": "Bearer ${EXAMPLE_TOKEN}"}}

${NAME} in a header value is replaced from the environment at start-up. A name that is not set fails that server with {:missing_env, names}. OAuth is not supported. See SuperPi.MCP.Transport.StreamableHTTP for the session and fallback behaviour. An entry with both command and url runs the command.

Scopes

A server belongs to a scope. The servers from mcp_config.json are :global: every conversation sees their tools. The servers that a client hands over at run time (add_servers/2) belong to one conversation. Their tools stay out of the shared catalog, only that conversation declares them, and only a call from that conversation reaches them. Two conversations that hand over a server with the same name get two processes, each with its own env and headers.