Pi MCP Adapter
An extension for the Pi agent that connects MCP servers through one proxy tool without flooding the context with tool definitions
Medium risk
We rate an entry medium when the tool runs code, makes network calls or reads project files. Check what exactly it does before installing.
Why this level
- Launches the connected MCP servers and forwards tool calls to them
- Stores OAuth tokens and static tokens in the OS credential store
Install
Manual install
pi install npm:pi-mcp-adapterInstalls into the Pi agent; restart Pi after installation.
This is third-party code. Review the repository files before installing.
What it does
The adapter tackles context bloat with MCP: one server's tool definitions can take more than ten thousand tokens, and you pay for them even when you never call the tools. Instead the adapter gives the Pi agent a single mcp proxy tool of about two hundred tokens, through which the model searches for the tool it needs on demand and calls it, while servers are lazy by default and start only on first use. Tool metadata is cached, so search and describe work without live connections. The adapter reads standard MCP configuration files, can import settings from Cursor, Claude Code, Codex and other host configs, supports OAuth and static tokens stored in the OS credential store, tool-call approval, output guarding, and a direct-tools mode for frequently used servers.
Who it is for. For users of the Pi agent who connect several MCP servers and want to save context.
Good fit when
- Pi has many MCP servers connected and they flood the context with tool definitions
- You want servers to start only when actually used
- You want to bring MCP settings into Pi from Cursor, Claude Code or Codex configs
- You want a single search across the tools of all connected servers
Not a fit when
- You work in another client rather than the Pi agent
- You have a single small server and do not need to save context
Example request
Find a screenshot tool among the connected servers and capture the pageLimitations
The adapter runs inside the Pi agent and is installed by its package manager; it does not connect directly to other agents, though it can import their MCP configs as compatibility sources. Some features need recent Node versions: the token commands require Node 22.18 or newer. Persistent OAuth relies on the OS credential store, and on headless Linux on an unlocked keyring, otherwise the adapter fails closed rather than storing credentials in plaintext. Import is supported for a limited set of hosts: cursor, claude-code, claude-desktop, opencode, vscode, windsurf, codex.
How to disable. Remove the pi-mcp-adapter extension from Pi with the same package manager you used to install it. A single server can be turned off with /mcp disable <server>, which writes a flag to the project .pi/mcp.json file.
Security check
- Launches the connected MCP servers and forwards tool calls to them
- Stores OAuth tokens and static tokens in the OS credential store
README in short
The README explains that the adapter gives the Pi agent access to MCP servers through a single proxy tool instead of hundreds of definitions, saving context. Servers are lazy by default and start on first call, with metadata cached for search without connecting. The adapter reads standard MCP files, describes config precedence, importing settings from hosts such as Cursor and Claude Code, and loading servers from Agent Plugins packages and local Claude plugins. Separate sections cover OAuth and token storage, tool-call approval, output guarding, direct tools and MCP UI integration. Installation is pi install npm:pi-mcp-adapter. MIT licensed.
FAQ
Which agents does it work with?
The adapter targets the Pi agent. It can import MCP settings from Cursor, Claude Code, Codex and other host configs, but it runs inside Pi itself.
How does it save context?
Instead of hundreds of tool definitions the agent sees a single mcp proxy tool, and finds specific tools by search on demand, then calls them by name.
Related
A skills library that gives coding agents a development process: brainstorming, planning, TDD, subagents and code review
Skills for real engineers by Matt Pocock
Skills For Real Engineers
Small composable skills for engineering with agents: plan grilling, TDD, bug diagnosis, code review and architecture
GitHub toolkit for spec-driven development: the specify CLI adds agent commands and skills to a project, from principles to implementation
Reference MCP servers
Model Context Protocol servers
Official reference MCP servers: Filesystem, Fetch, Git, Memory, Sequential Thinking, Time and Everything