sscoble/pi-mono
1
0
Fork 0
mirror of https://github.com/badlogic/pi-mono.git synced 2026-11-06 23:44:36 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 5
pi-mono/packages/coding-agent/docs/mcp.md
Armin Ronacher 27d2914457 feat(coding-agent): connect MCP servers and expose them through codemode 
Adds a built-in mcp extension that reads mcp.json (agent dir, and .pi/mcp.json for trusted projects) in the common mcpServers format, connects stdio and streamable HTTP servers at session start, and registers their tools as mcp__<server>__<tool>. Calls go through the regular tool pipeline, so hooks and permission extensions apply. /mcp shows server status.

By default a server's tools are codemode-only: the new nestedOnly tool flag keeps them executable for other tools but out of the model's tool declarations, and pi activates the codemode tool for them. "exposure": "direct" declares them to the model as well. structuredContent from tools with an outputSchema reaches codemode scripts as data.
2026-09-25 15:02:51 +02:00

2.6 KiB
Raw Blame History

MCP Servers

Pi connects to Model Context Protocol servers over stdio or streamable HTTP and makes their tools available to the model.

Configure servers

Add servers to ~/.pi/agent/mcp.json, or to .pi/mcp.json in a project. The format matches other MCP clients, so existing mcpServers entries can be copied over:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "docs": {
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer ${DOCS_TOKEN}" },
      "exposure": "direct"
    }
  }
}
  • stdio servers take command, args, env, and cwd. Relative cwd resolves against the session directory.
  • HTTP servers take url and headers. The legacy SSE transport is not supported.
  • env and headers values can reference environment variables (${NAME}) or commands (!command), like provider API keys.
  • timeout sets the per-request timeout in seconds (default 60). Progress notifications from the server reset it.
  • enabled: false keeps an entry without connecting to it.

Project entries replace global entries with the same name. A project mcp.json is only read after the project is trusted, because stdio servers run commands.

Pi connects when a session starts. The first prompt waits until startup connections finish. A server that drops its connection is reconnected on the next call. Run /mcp to see server status, tool counts, and errors.

Exposure

Each server's tools are registered as mcp__<server>__<tool>. The exposure setting controls how the model reaches them:

  • codemode (default): the tools are callable from codemode scripts but are not declared to the model. Large MCP tool lists stay out of the model's tool declarations, and scripts can call several MCP tools, in parallel if needed, while returning only the part of the result the model needs. Pi activates the codemode tool when such a server connects.
  • direct: the tools are declared to the model like built-in tools, and are also callable from codemode.

MCP tools that declare an outputSchema return their structuredContent to codemode scripts. Other tools return their text output. Images are passed through as image content.

Every MCP call goes through pi's tool pipeline, so tool_call and tool_result extension handlers, including permission gates, apply to MCP tools. Calls made from codemode scripts carry the codemode call's id as parentToolCallId.

OAuth sign-in is not supported yet. Use header-based authentication for remote servers.