Pi MCP Context Adapter
Use MCP servers in Pi on demand without filling the context window with tool schemas.
- Source repo
- nicobailon/pi-mcp-adapter
- Stars
- ★ 1.6k
- Last updated
- today
- License
- MIT
- Primary language
- TypeScript
- FA score
- 60/100 · Some gaps
At a glance
- How it runs
- Works with
- Platform-specificCodex · Claude Code (Partial support)
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A Pi developer with a project
.mcp.jsonwho wants to use an MCP service such as Chrome DevTools only when it is needed. - Not a fit if
- Teams not using the Pi coding agent or wanting a standalone proxy service
- Users who need MCP server processes shared across sessions
- Workflows needing image or audio MCP sampling
- Source review
- 60/100 · Some gaps
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.
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: "..." } }).
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 does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Pi MCP Context Adapter This agent | 60 · Some gaps | Agent plugin / skillFree | ★ 1.6k | today | TypeScript | — |
| mcp-agent | 53 · Major gaps | FrameworkFree + model costs | ★ 8.6k | 9mo ago | Python | Claude.ai · OpenAI API · Claude API |
| Claude Code Architecture Study | 43 · Major gaps | CLI | ★ 12k | 7mo ago | — | — |
| MATLAB MCP Server | 69 · Some gaps | MCP serverFree | ★ 1.8k | 10d ago | Go | Claude Code · Claude.ai |
How does FollowAgents rate this agent?
Why each dimension lost points
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.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
This is a fix release, and the biggest fix is for servers with long tool or resource names. A single long name, like a Home Assistant resource with a file path in it, used to make OpenAI, Anthropic, Bedrock and other strict providers reject every request. Those names are now shortened to fit, and the full name still works anywhere you write it for the adapter. Pi also starts faster, a mistyped mcp action now gives a clear error instead of quietly doing something else, and a few terminal annoyances are gone. Highlights …View on GitHub ↗ -
Release notes excerpt
This release makes the agent's MCP work faster and cheaper. On servers that support MCP Tasks, slow tools like a CI run or a report export no longer hold up your session: Pi gets control back right away, and the result arrives as a new message when the job finishes. Semantic search now finds tools by meaning using the model logins you already have in Pi, and shows full parameters only for the tools it's confident about. The agent can also ask a tool for just the values it needs instead of reading a whole page of output. Highlights …View on GitHub ↗ -
Release notes excerpt
pi-mcp-adapter 6.0.0 makes Pi a better home for your MCP tools, especially if you use Executor. Pi now asks you before an Executor app does anything that needs approval, instead of letting the model approve it. When an app needs an account you haven't connected, Pi opens the sign-in link and finishes the call for you. You can also save a workflow you repeat as your own named tool. The adapter's old mcpScript tool is gone, because Pi's own codemode now does that job and works with the rest of Pi. Highlights …View on GitHub ↗
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.