Pi MCP Context Adapter
Use MCP servers in Pi on demand without filling the context window with tool schemas.
Per-dimension scores and reasoning
Evidence shows: adapter defaults to lazy connections, avoiding unnecessary server starts; provides approval tools and user confirmation mechanisms; data flow transparency via status snapshots and trace options; sensitive data handling includes OAuth credentials stored in OS credential store, failing closed rather than degrading; dependency security: dependency list includes known packages, but no vulnerability scanning or lock file evidence; external effects: adapter does not auto-start/stop external daemons, but does start MCP server processes; rollback: disable/enable commands exist, but no full rollback mechanism; source attribution: author identity clear, but publisher unverified. Deductions: dependency security lacks concrete evidence, rollback incomplete, source attribution limited by unverified publisher.
Evidence shows: documentation and config descriptions consistent, good self-consistency; dependencies clearly listed in package.json, but availability not verified; failure messages: documentation describes error handling, but no concrete examples. Deductions: dependency availability unverified, failure messages lack concrete examples.
Evidence shows: targets Pi coding agent users, scenarios include local and remote OAuth; capability boundaries clear, e.g., unsupported features; trigger precision via tool prefixes and approval modes; environment fit includes multiple config files and platform support. Deductions: environment fit not all platforms, trigger precision depends on user config.
Evidence shows: clear information architecture, detailed README; install instructions clear; naming stable, version clear; examples and FAQ present; known limitations listed; license MIT; changelog present; maintenance responsibility by author, but publisher unverified. Deductions: maintenance responsibility limited by unverified publisher.
Evidence shows: output usability enhanced via tool metadata caching and status snapshots; marginal value in reducing context window consumption; cost-benefit via lazy connections and on-demand startup. Deductions: no performance benchmarks or real usage data.
Evidence shows: README claims consistent with code structure, but no independent verification; cross-source corroboration limited, mainly single repository; fact-inference separation unclear. Deductions: lack of independent verification and cross-source corroboration.
- Publisher identity unverified; assess supply chain risk carefully.
- Dependency security lacks vulnerability scanning or lock file evidence; check dependency versions.
- Rollback mechanism incomplete; only disable/enable, no full rollback.
- Remote OAuth flow involves sensitive information; ensure secure environment.
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.jsonwho 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-startandauth-completeproxy 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, andapproveTools. - 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: "..." } }).
FAQ
Does it start every MCP server when Pi launches?
lazy, so a server connects on its first tool call. eager and keep-alive configurations start during extension load or session initialization.Must every MCP tool appear in the model's tool list?
mcp proxy for search, description, and calls. Only servers or tools configured with directTools are registered individually.How are tokens and OAuth credentials handled?
Can it reuse Claude Code or Codex MCP configuration?
/mcp setup or pi-mcp-adapter init. Host-specific configuration is not loaded automatically by default.