# pi-mcp-adapter: using MCP servers with Pi without burning the context window

> pi-mcp-adapter replaces hundreds of MCP tool definitions with a single proxy tool of roughly 200 tokens, and connects servers only when a tool is actually called. It is aimed at Pi coding agent users who already have MCP configs and want them to stop eating context.

**nicobailon/pi-mcp-adapter** — Token-efficient MCP adapter for Pi coding agent

- Repository: https://github.com/nicobailon/pi-mcp-adapter
- Stars: 1,569 · Forks: 382
- Language: TypeScript
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/nicobailon-pi-mcp-adapter

## The context tax pi-mcp-adapter is built to remove

MCP tool definitions are verbose. The README states that a single MCP server can burn 10k+ tokens, and that cost is paid whether or not the tools are used. Connect a few servers and, in the project's own framing, half the context window is gone before the conversation starts. The README links to Mario Zechner's post arguing that you might not need MCP at all, and that writing simple CLI tools is a reasonable alternative.

The adapter takes the middle position. The MCP ecosystem has useful servers (databases, browsers, APIs), so instead of dropping MCP the project exposes it through one proxy tool of roughly 200 tokens rather than hundreds of individual tool definitions. The agent discovers what it needs on demand, and servers start only when a tool from them is actually called. The audience is narrow and specific: people running Pi who want MCP servers available without carrying their full schema in every request.

## One proxy tool, lazy servers, and a cached tool index

The mechanism has three parts. First, tool definitions are collapsed into a single mcp tool that takes a search query, a describe request, or a tool call. Second, servers are lazy by default: they do not connect until one of their tools is invoked. Third, the adapter caches tool metadata, so search and describe work without live connections. That cache is what makes the two-call pattern possible: search first, then call.

The README gives this example of a search:

```
mcp({ search: "screenshot" })
```

The result is a tool name and its parameter list rather than a live call. Only the second call, `mcp({ tool: "chrome_devtools_take_screenshot", args: { format: "png" } })`, actually reaches the server. The README notes that args can be a JSON object or a JSON string, and recommends the object form when the model handles it reliably, keeping the string form for providers that need simpler schemas. Config resolution is layered, with later entries winning: `~/.config/mcp/mcp.json`, then `~/.agents/mcp.json`, then `~/.agents/mcp/mcp.json`, then the Pi agent dir's `mcp.json`, then project `.mcp.json`, then `.pi/mcp.json`.

## Installing pi-mcp-adapter and making a first MCP call

Installation is a single Pi command, and the README says to restart Pi afterwards:

```bash
pi install npm:pi-mcp-adapter
```

If you already have a standard MCP file, there is nothing else to configure. The README's compatibility table says `.mcp.json` or `~/.config/mcp/mcp.json` is used immediately, with `.mcp.json` for project and team sharing and the global path for all projects. A minimal project config looks like this:

```json
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@1.6.0"]
    }
  }
}
```

With nothing configured, the README directs you to `/mcp setup`, where you 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. If your MCP servers live in host-specific files (Cursor, Claude Code, Codex), `/mcp setup` adopts them: it shows what it found, lets you pick which to import, and previews the file changes before writing. There is also a terminal path, `pi-mcp-adapter init`, which scans for host-specific configs and adds missing compatibility imports to `~/.pi/agent/mcp.json` by default, or `$PI_CODING_AGENT_DIR/mcp.json` when that variable is set. After install and restart, open `/mcp` and confirm which config file Pi reports as detected.

## Disabling a server writes to .pi/mcp.json, not to your source file

The enable and disable commands are the part most likely to surprise people, in a good way. `/mcp disable <server>` and `/mcp enable <server>` persist only the `disabled` field in the project-local `.pi/mcp.json`, which the README describes as the highest-precedence Pi layer. Enabling removes the project flag when lower layers are enabled, or writes `false` when it needs to override a disabled lower source. The source file is never rewritten and credentials are never copied, even when the effective server came from a shared global file, an imported host config, or a `configPath`.

Two operational details follow from that. You must run `/reload` after changing the flag so registered tool surfaces are refreshed. And the manual equivalent is adding `{ "disabled": true }` to a server in any normal MCP config. One mode is excluded: configurations supplied in memory through `createMcpAdapter({ config })` are isolated and do not read or write the project override, so the commands are unavailable there.

## Host config discovery is off by default, and that is deliberate

The README is explicit that host-specific configs are compatibility inputs, not normal setup paths, and that they are not loaded automatically. The normal `/mcp` panel does not scan them when `settings.hostConfigDiscovery` is `"off"`, which is the default. To opt in to fallback discovery you set that key to `"on"` or run `pi-mcp-adapter init --discover-host-configs`. A third value, `"prompt"`, exists for integrations that want detection without activation.

When discovery does run, host configs sit below every shared and Pi-owned source in precedence, and the README states that discovery reports source paths, provenance and same-name conflicts while never writing to external host files or silently launching commands from them. That is a sensible default for anyone with a Cursor or Claude Code setup they do not want a second tool touching. The cost is that a fresh install appears to find nothing until you either run `/mcp setup` or turn discovery on, which is the most likely source of "it did not pick up my servers" confusion. Agent Plugins are a separate opt-in: the adapter loads servers from those packages when directories are listed in `settings.agentPluginPaths`, and each directory must contain a valid Agent Plugins 1.0 `plugin.json`.

## Where pi-mcp-adapter is the wrong tool

The lazy model trades a connection for a round trip. If your workflow calls the same MCP tool many times in a session, you pay for a search or a describe before calls that a directly registered tool would not need. The README's own framing is two calls instead of 26 tools cluttering the context, and that arithmetic only favors the adapter when the tool count is the problem.

There is also a hard dependency on Pi. This is an extension for the Pi coding agent, installed through `pi install` and driven by `/mcp` commands; it is not a standalone MCP client and not a general MCP proxy for other editors. If you do not run Pi, none of it applies. The project's own README points at the alternative position, Mario Zechner's argument that you may not need MCP at all and simple CLI tools are enough. If your MCP usage is one database server with a handful of tools, that argument is worth taking seriously before adding a proxy layer. And if you rely on in-memory `createMcpAdapter({ config })` configurations, the enable and disable commands are unavailable by design.

## Alternatives: direct tool registration and the no-MCP position

The most direct alternative is what Pi does without the adapter: register MCP server tools as ordinary tools. Every definition is present in context from the start, the model sees the real tool names and schemas, and there is no search step before a call. The difference is entirely about cost and discoverability. Direct registration is predictable and needs no cache, but the README's stated problem is that a single server can consume 10k+ tokens, and the adapter's answer is one proxy tool of roughly 200 tokens with metadata cached for search and describe.

The second alternative is the no-MCP route the README itself cites: skip MCP and write small CLI tools for the few things you need. That avoids both the token cost and the proxy indirection, and it is a better fit when your needs are stable and narrow. The adapter's counterargument is the breadth of the existing MCP ecosystem (databases, browsers, APIs) and the cost of reimplementing each of those as a CLI. The trade is between writing and maintaining your own tools versus accepting a proxy layer over servers someone else maintains.

## Maintenance, upgrades and the MIT licence

The repository is not archived, and the last push was on 2026-09-05, so the project is being touched. Recent releases listed are v2.31.0 on 2026-08-28, v2.32.0 and v2.32.1 on 2026-09-01. Upgrades go through the same channel as the install, `pi install npm:pi-mcp-adapter`, followed by a Pi restart, and the README's note about running `/reload` after changing a disable flag applies to config changes generally. The package declares Node `>=20` in its engines field, so that is the floor to check on the machine running Pi.

The licence is MIT, which permits commercial and private use and modification with the copyright notice retained. That is a permissive default, and nothing in the README adds terms on top. It says nothing about warranty or support obligations, and MIT carries none. One licensing detail worth noting separately: the adapter reads `.mcp.json` and `~/.config/mcp/mcp.json` and can import host configs from Cursor, Claude Code and Codex, but the README states it never writes to external host files. If your MCP configs are shared with a team through `.mcp.json`, the adapter's disable and enable flags land in `.pi/mcp.json`, which is project-local and separate.

## Conclusion

Adopt pi-mcp-adapter if you run Pi and already keep MCP servers in .mcp.json or ~/.config/mcp/mcp.json, because it reads those files without extra setup and only connects a server when one of its tools is called. Skip it if you are not a Pi user, or if you only need one or two MCP tools and the token cost of their definitions never bothered you. Before relying on it, verify two things on your own machine: which config file Pi reports as the detected source when you first open /mcp, and whether /mcp setup previews changes to your host configs the way the README describes, since host configs are compatibility inputs that are not loaded automatically.

## FAQ

### How do I use MCP with Pi?

Install the adapter with pi install npm:pi-mcp-adapter and restart Pi. If you already have a .mcp.json or ~/.config/mcp/mcp.json, the README says Pi uses it immediately; otherwise run /mcp setup to scaffold a config or import host-specific configs.

### Does Pi have MCP support?

Not built in, according to the README, which frames the adapter as the way to get MCP into Pi. The adapter exposes MCP servers through a single proxy tool of roughly 200 tokens and connects each server only when one of its tools is called.

### What is an MCP adapter?

In this project, it is a layer that sits between the Pi coding agent and MCP servers. It caches tool metadata so search and describe work without live connections, and it collapses many tool definitions into one proxy tool so the definitions do not sit in the context window.

## Sources

- [Issues](https://github.com/nicobailon/pi-mcp-adapter/issues)
- [License: MIT](https://github.com/nicobailon/pi-mcp-adapter/blob/main/LICENSE)
- [nicobailon/pi-mcp-adapter on GitHub](https://github.com/nicobailon/pi-mcp-adapter)
- [README](https://github.com/nicobailon/pi-mcp-adapter/blob/main/README.md)
- [Releases](https://github.com/nicobailon/pi-mcp-adapter/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nicobailon-pi-mcp-adapter