An adapter that lets Pi use MCP servers, with a scripting skill that covers tool discovery, how call results are shaped, and script limits. It is meant for developers who want MCP tools without filling the context window.
$ git clone https://github.com/nicobailon/pi-mcp-adapter
Add a server to .mcp.json in your project:
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": ["-y", "chrome-devtools-mcp@1.6.0"]
}
}
}Servers are lazy by default — they won't connect until you actually call one of their tools. The adapter caches tool metadata so search and describe work without live connections.
mcp({ search: "screenshot" })chrome_devtools_take_screenshot
Take a screenshot of the page or element.
Parameters:
format (enum: "png", "jpeg", "webp") [default: "png"]
fullPage (boolean) - Full page instead of viewportmcp({ tool: "chrome_devtools_take_screenshot", args: { format: "png" } })Two calls instead of 26 tools cluttering the context.
Use MCP servers with Pi without burning your context window.
On servers that support MCP Tasks, add "protocolVersion": "auto" and slow tools run in the background while the agent keeps working. Tool search can rank tools by meaning and send full schemas only for the ones that fit. And extract hands the agent just the values it asked for from a long result. Everything else is in the changelog.
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.
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:
~/.pi/agent./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 turns codemode on by itself; with the adapter, add "+codemode" to defaultTools in Pi's settings. 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, opt-in (add "+codemode" to defaultTools) (MCP scripting) |
| Token cost | By default, every call is a codemode script | Single lookups cost about the same as the built-in's default. Bulk tasks cost up to 5.5× more without scripts, and up to 2.9× more with Pi's codemode turned on (measured) |
| Tool search | tool_search, ranked by words | mcp({ search }) ranked by words or regex. With a classifier model in Pi, such as Jev through /login to OpenRouter, semantic search ranks tools by meaning (setup) |
| Long tool results | A codemode script can filter a result before the model sees it | Opt-in per server: mcp({ tool, args, extract: { total: "number" } }) returns only the values you name, as numbers and dates read by Cloudflare's Clairic model with your Cloudflare credentials in Pi; the full result is saved to a file (Typed values) |
| Saved workflows as tools | No | A workflow you repeat becomes one tool with fixed inputs: a saved script that calls MCP and Pi tools, found by search and called like any other tool (scriptTools, Script tools) |
| Executor app tools | Only Executor's own six tools; the model reaches app tools through Executor's search and call | Each tool of your Executor apps is a Pi tool, found by search and called by name with Pi's approvals (Executor app tools) |
| OAuth tokens | JSON file in ~/.pi/agent | OS keychain |
| MCP prompts, elicitation, sampling, Tasks | No | Yes; Tasks run in the background and 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 also see each MCP call under the tool's own name |
| Roots (session directory sent to servers) | Yes | Yes |
| 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 on Pi 0.99.2 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 1.3.0.
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).
pi install npm:pi-mcp-adapter
Restart Pi after installation.
DeepSeek Harness (third-party bridge): Run the unmodified adapter in DSH via pi2dsh; see the verified dsh-TUI and Web MCP guide.
The adapter reads standard MCP files automatically. No extra setup needed if you already have them.
| You already have... | What happens |
|---|---|
.mcp.json or ~/.config/mcp/mcp.json | Pi uses it immediately. Use .mcp.json for project/team sharing and ~/.config/mcp/mcp.json for all projects. |
Servers added with pi mcp add (~/.pi/agent/mcp.json, .pi/mcp.json) | On Pi 0.99 and later, the adapter uses them and replaces Pi's built-in MCP extension, which Pi reports at startup; see Pi's built-in MCP. |
| Host-specific configs (Cursor, Claude Code, Codex, etc.) but no standard MCP files | Run /mcp-adapter setup to adopt those host configs into Pi. The setup flow shows exactly what it found, lets you pick which ones to import, and previews the exact file changes before writing. |
| Nothing configured yet | Run /mcp-adapter setup, choose project .mcp.json or global ~/.config/mcp/mcp.json, then scaffold a minimal config, add a curated known server, quick-add RepoPrompt, or inspect what the adapter discovered on your machine. |
If you prefer the terminal, you can also run pi-mcp-adapter init after install to scan for host-specific configs and add missing compatibility imports to the adapter config (~/.pi/agent/mcp-adapter.json by default, or $PI_CODING_AGENT_DIR/mcp-adapter.json when set).
Add a server to .mcp.json in your project:
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": ["-y", "chrome-devtools-mcp@1.6.0"]
}
}
}
Servers are lazy by default — they won't connect until you actually call one of their tools. The adapter caches tool metadata so search and describe work without live connections.
mcp({ search: "screenshot" })
chrome_devtools_take_screenshot
Take a screenshot of the page or element.
Parameters:
format (enum: "png", "jpeg", "webp") [default: "png"]
fullPage (boolean) - Full page instead of viewport
mcp({ tool: "chrome_devtools_take_screenshot", args: { format: "png" } })
Two calls instead of 26 tools cluttering the context.
| Want | Do | Details |
|---|---|---|
| Add a server without editing JSON | /mcp-adapter setup, or mcp({ action: "install", url: "..." }) | Configuration, Install from one URL |
| Use servers from Cursor, Claude Code, or Codex | /mcp-adapter setup or pi-mcp-adapter init | Import existing configs |
| Sign in to an OAuth server | /mcp-auth <server> | Authentication |
| Put a few tools directly in the model's tool list | "directTools": ["tool_a"] on the server | Direct tools |
| Ask before a risky tool runs | "approveTools": "destructive" | Tool approval |
Stars on GitHub
View @nicobailon’s profileAn agent skill that turns complex terminal output into styled HTML pages you actually want to read. Ask your agent to explain a system architecture, review a diff, or compare requirements against a plan.
@nicobailonA development methodology for coding agents that makes the agent brainstorm before building, follow plans, run parallel work and finish branches in a disciplined way. You get fewer skipped steps and more consistent results from your coding assistant.
@obraHelps you take a change from a rough idea or bug report through to a tested, reviewed result, with each step handled by a focused skill. Its skills cover pinning down domain terms, designing module interfaces, diagnosing hard bugs, and reviewing changes against your repo's coding standards.
@mattpocockGives your coding agent a planning, testing and review routine to follow on every task. It plans before building, checks changes with tests, has a fresh reviewer look for regressions, and saves repeated wins as reusable skills.
@affaan-mDeveloper tools for working on the React codebase itself. Provides skills for extracting error messages, managing and debugging feature flags across release channels, running Flow type checks, and fixing lint and formatting issues before committing.
@facebookAn adapter that lets Pi use MCP servers, with a scripting skill that covers tool discovery, how call results are shaped, and script limits. It is meant for developers who want MCP tools without filling the context window. Free and open source.
Is this tool yours?
Claim it with GitHubSubmit a pluginPromote it