pi-mcp-adapter weekly downloads statistics

Pi MCP Adapter

Use MCP servers with Pi without burning your context window.

https://github.com/user-attachments/assets/4b7c66ff-e27e-4639-b195-22c3db406a5a

Why This Exists

Mario wrote about why you might not need MCP. The problem: tool definitions are verbose. A single MCP server can burn 10k+ tokens, and you're paying that cost whether you use those tools or not. Connect a few servers and you've burned half your context window before the conversation starts.

His take: skip MCP entirely, write simple CLI tools instead.

But the MCP ecosystem has useful stuff - databases, browsers, APIs. This adapter gives you access without the bloat. One proxy tool (~200 tokens) instead of hundreds. The agent discovers what it needs on-demand. Servers only start when you actually use them.

pi-mcp-adapter vs Pi's built-in MCP

Since then, Pi 0.99 added MCP support of its own, which also keeps tool definitions out of context. Installing the adapter replaces it in Pi sessions. What you get by switching:

• Install many servers without paying for idle ones. The built-in starts every enabled server in every Pi session and keeps it running until the session ends. By default, the adapter starts a server when the model first calls it and stops it after 10 idle minutes. • Fewer tokens on everyday calls. By default, the built-in runs every MCP call as a codemode script, even a single lookup. The adapter's scripts are off by default, so a lookup is one small JSON call to the mcp tool, which cost 10–33% less in our tests. For bulk work across many records, turn scripts on with settings.scriptMode; then it costs about the same as codemode. • More servers work fully. Servers can ask you questions through forms, show interactive UIs, and offer prompt templates as slash commands. The built-in doesn't handle these. • Find tools by what you mean. The built-in's tool search only matches words. With a System One key, the adapter can also rank tools by meaning: in a test of 12 everyday requests across 95 tools, it put the right tool first in 10 of 11, where word search did in 5. • Sign-in tokens go in your OS keychain by default (an encrypted file is opt-in), not in a plain JSON file under ~/.pi/agent. • Adding servers is easier. Give the agent a server's URL and it installs it and checks its tools in the same session, opening sign-in first if the server needs it, with no shell command or /reload. Servers already configured in Cursor, Claude Code, Codex, or VS Code can be imported with /mcp-adapter setup, which also adds presets such as Figma and GitHub.

The built-in has two things the adapter doesn't: Pi's permission extensions see each MCP call as its own tool call without changes, and it sends roots (the session directory) to servers. Pi's codemode works with both.

| | Pi's built-in MCP | pi-mcp-adapter |

| Servers running | Every enabled server, for the whole session | Only servers in use; each stops after 10 idle minutes | | Server memory (100 installed, 3 in use) | 7.0 GB at start, 5.9 GB after 15 minutes | Only the 3 in use, then none once they're idle | | How the model reaches tools | Default: codemode scripts. Per server: direct, or loaded by tool_search | Default: one mcp proxy tool. Per server: direct, or loaded by tool_search. Scripts: Pi's codemode (add "+codemode" to defaultTools) or the adapter's mcpScript, both opt-in | | Token cost | By default, every call is a codemode script | Compared with the built-in's default, single lookups cost 10–33% less. For bulk work, turn on scriptMode; without it, bulk tasks cost up to 7× more (measured) | | Tool search | tool_search, ranked by words | mcp({ search }) ranked by words or regex. With a System One key, semantic search ranks tools by meaning (setup) | | OAuth tokens | JSON file in ~/.pi/agent | OS keychain | | MCP prompts, elicitation, sampling, Tasks | No | Yes; Tasks need "protocolVersion": "auto" | | MCP UI apps | Left out | Native window or browser | | Add a server | pi mcp add in a shell, then /reload | Give the agent the URL: mcp({ action: "install", url }) connects it and checks its tools in the current session; for an OAuth server it opens sign-in first and checks the tools once you approve | | Configs from Cursor, Claude Code, Codex, VS Code | Convert by hand | Imported | | Guided setup in a session | No; /mcp manages servers that are already configured | /mcp-adapter setup overlay: imports configs found on your machine, adds presets (Figma desktop and RepoPrompt when installed, GitHub, Notion, Context7, DeepWiki, Parallel Search, Tavily Search, Chrome DevTools), and previews each file change before writing | | Ask before risky tools | Through a permission extension, which sees every MCP call | Built in (approveTools); permission extensions see proxy calls as the proxy tool | | Roots (session directory sent to servers) | Yes | No | | Shell commands | pi mcp add, remove, list | pi-mcp-adapter init, doctor | | Transports | stdio, streamable HTTP | stdio, streamable HTTP, legacy SSE, rmcp-mux socket |

Over a session, measured with 100 small local servers:

| 100 servers installed, 3 used | Pi's built-in MCP | pi-mcp-adapter |

| Servers running at session start | 100 | 0 | | While you use 3 | 100 | 3 | | After the idle timeout (10 min) | 100 | 0 |

Stopping a server doesn't take its tools away: the model can still search them, and a stopped server starts again on its next call (0.1–0.3 s for a small local server). For a server that must keep state between calls, set "lifecycle": "lazy-keep-alive". The first session briefly starts new servers, 10 at a time, to read their tool lists. Measurements and details.

The full comparison has every row with sources, as of Pi 0.99.2.

When you install or update the adapter, it turns Pi's built-in MCP off in Pi's settings for you (the same switch as pi config → Built-in), so the two don't both run. If you remove the adapter, turn the built-in back on there (details).

Install

Restart Pi after installation.…

Description from the npm listing.