Pi MCP Context Adapter
Use MCP servers in Pi on demand without filling the context window with tool schemas.
What does this agent do, and when should you use it?
Pi MCP Adapter is a Pi coding agent extension that exposes many MCP servers through one `mcp` proxy tool. It connects servers lazily by default and caches tools, resources, prompts, and instructions in the Pi agent directory, so discovery can work without a live connection. Server transports include stdio, HTTP, and explicit rmcp-mux Unix sockets, with lazy, eager, keep-alive, and lazy-keep-alive lifecycle modes. Selected server capabilities can become Pi direct tools, while `mcpScript` provides a worker-thread JavaScript interface for multi-call MCP tasks. Configuration is merged from shared MCP files and Pi-specific override files, and persistent OAuth credentials are kept in the operating system credential store.
The extension reads .mcp.json, ~/.config/mcp/mcp.json, ~/.agents/mcp.json, ~/.agents/mcp/mcp.json, and Pi override files, merging server definitions according to the documented precedence. An agent can search cached Pi and MCP tools with mcp({ search }), inspect a target with mcp({ describe }), and invoke it with mcp({ tool, args }); mcp({ connect }) connects or refreshes one server. Lazy servers start on their first actual call, cache their metadata, and disconnect after the configured idle timeout, while HTTP endpoints can use bearer or OAuth authentication. The /mcp panel, /mcp setup, /mcp reconnect, /mcp disable, and /mcp-auth commands handle interactive setup and operations, and mcpScript exposes tools.search, tools.describe, and tools.call for JavaScript orchestration. Its default Output Guard truncates oversized text output and writes the full text to a mode-0600 temporary file.
- A Pi developer with a project `.mcp.json` who wants to use an MCP service such as Chrome DevTools only when it is needed.
- An engineer with several database, browser, and API MCP servers who wants to discover a relevant tool before connecting to its server.
- A team that wants a few frequent MCP operations in Pi's direct tool list without exposing every tool from a large server.
- A user running Pi remotely or headlessly who needs to complete OAuth through the `auth-start` and `auth-complete` proxy actions.
- A Pi user migrating existing Cursor, Claude Code, or Codex host configuration through explicit compatibility import.
What are this agent's strengths and limitations?
- Replaces many directly registered MCP schemas with an approximately 200-token proxy surface and on-demand discovery.
- Combines lazy connections with disk-cached metadata, allowing search, listing, and descriptions without routinely starting servers.
- Supports stdio, HTTP with SSE fallback, and explicit rmcp-mux sockets across four documented lifecycle modes.
- Provides per-server and per-tool control through `directTools`, `includeTools`, `excludeTools`, and `approveTools`.
- Guards large text results by default and stores persistent OAuth credentials in the OS credential store rather than plaintext files.
- Its core runtime is the Pi coding agent; the documented support for other hosts is configuration import, not standalone proxy deployment.
- A lazy server still has connection and startup latency on its first use, and new direct tools initially fall back to proxy-only until metadata is cached.
- Cross-session server sharing is not implemented, so ordinary Pi sessions run their own server processes.
- Headless OAuth still requires an available, unlocked OS credential store; the adapter fails closed instead of using plaintext fallback storage.
- MCP sampling is text-only; context inclusion, tools, stop sequences, audio, and image content are explicitly rejected.
How do you install or deploy this agent?
Install the Pi coding agent and npm first. Run pi install npm:pi-mcp-adapter, then restart Pi. For a project server, create or retain .mcp.json, for example: {"mcpServers":{"chrome-devtools":{"command":"npx","args":["-y","[email protected]"]}}}. If standard MCP files do not exist, run /mcp setup after installation, or run pi-mcp-adapter init to scan host-specific configuration and add compatibility imports. An HTTP OAuth server additionally needs its applicable OAuth configuration and an available operating-system credential store.
How do you use this agent?
In Pi, begin with mcp({ search: "screenshot" }); inspect the result using mcp({ describe: "chrome_devtools_take_screenshot" }); then call mcp({ tool: "chrome_devtools_take_screenshot", args: { format: "png" } }). Use /mcp to inspect server status and switch direct/proxy exposure, or /mcp reconnect <server> to refresh one server. For a multi-step task, use the default-enabled mcpScript tool with await tools.search(...), await tools.describe(...), and await tools.call(...). For remote OAuth, run mcp({ action: "auth-start", server: "linear-server" }), approve in a browser, and submit the callback URL back to the same Pi session through mcp({ action: "auth-complete", server: "linear-server", args: { redirectUrl: "..." } }).