pi-mcp-adapter
pi-mcp-adapter is a TypeScript bridge that lets the Pi coding agent use Model Context Protocol servers without inflating the context window. Instead of loading all tool definitions upfront (10k+ tokens per server), it exposes a single proxy tool that discovers and calls MCP tools on-demand, keeping the agent lean.
Key facts
Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.
| Field | Value |
|---|---|
| Repository | nicobailon/pi-mcp-adapter |
| Owner | nicobailon |
| Primary language | TypeScript |
| License | MIT — OSI-approved |
| Stars | 970 |
| Forks | 187 |
| Open issues | 62 |
| Latest release | v2.11.0 (2026-07-03) |
| Last updated | 2026-07-03 |
| Source | https://github.com/nicobailon/pi-mcp-adapter |
What pi-mcp-adapter is
A TypeScript MCP adapter implementing lazy-loading tool discovery via a proxy interface, supporting stdio and HTTP transports, OAuth/bearer auth, lifecycle management (lazy/eager/keep-alive), and config precedence across shared and Pi-specific files. Tool metadata is cached to enable search/describe without live connections.
Get the pi-mcp-adapter source
Clone the repository and explore it locally.
git clone https://github.com/nicobailon/pi-mcp-adapter.gitcd pi-mcp-adapter# follow the project's README for install & configurationNeed it deployed, integrated, or customized instead? DEV.co ships production installs.
Best use cases
Implementation considerations
- Config precedence is explicit (~/.config/mcp/mcp.json → <Pi agent dir>/mcp.json → .mcp.json → .pi/mcp.json) but non-obvious; teams must document which config file they own to avoid conflicts and silent overrides.
- OAuth flow supports remote/headless setups via manual code exchange (auth-start/auth-complete), but tokens are treated as sensitive; ensure logging/logging practices do not leak codes or redirects in session transcripts.
- Idle timeout interacts with requestTimeoutMs; setting both too low risks tool calls failing mid-flight or servers cycling too aggressively. Test against real workloads to find stable values.
- The proxy tool uses JSON string args, not objects (e.g., args: '{"format": "png"}'), which is error-prone in LLM-generated calls; type hints in prompts or schema are critical.
- Lifecycle modes (lazy/eager/keep-alive) default to lazy with 10-minute idle; misconfiguration can leak resource connections. Document per-server expectations and monitor idle disconnects in production.
When to avoid it — and what to weigh
- You need always-on tool availability with zero latency — Lazy lifecycle introduces mild startup cost on first tool call. Critical-path tools may benefit from eager or keep-alive modes, but those defeat the context-saving purpose.
- Your MCP servers cannot tolerate dynamic startup/shutdown — Idle timeout and lifecycle switching assume servers can cleanly disconnect and reconnect. Stateful servers (in-process caches, long-lived connections) may experience errors or data loss.
- You rely on tool listing to enumerate capabilities at init time — The adapter caches metadata asynchronously; on first run, full tool discovery may lag. Workflows that expect a synchronous tool list at startup may fail or require polling.
- You need real-time tool updates without restarting Pi — Tool metadata cache is static until reconnect. Adding a new tool to an MCP server requires manual restart or cache invalidation; no hot-reload mechanism is documented.
License & commercial use
MIT License. Permits commercial use, modification, and distribution with attribution. No warranty. Consult legal for internal/external product bundling.
MIT is a permissive OSI license permitting unrestricted commercial use without royalty, provided attribution and license text are included in distributions. Embedding in commercial products or services requires no negotiation; include LICENSE file and copyright notice. Verify downstream dependencies (MCP SDK, Pi agent) for any restrictive licenses.
DEV.co evaluation signals
Editorial assessment — not user reviews. Directional, with an explicit confidence level.
| Signal | Assessment |
|---|---|
| Maintenance | Active |
| Documentation | Strong |
| License clarity | Clear |
| Deployment complexity | Low |
| DEV.co fit | Good |
| Assessment confidence | High |
OAuth and bearer tokens are persisted in config files; ensure filesystem permissions restrict access to .mcp.json files containing secrets. OAuth redirect URI and code handling require careful validation; dynamic client registration may be target for phishing if not validated. MCP server processes inherit Pi agent's environment; ensure servers are from trusted sources. No documented sandboxing or process isolation.
Alternatives to consider
Direct MCP integration (no adapter)
Load all MCP tool definitions upfront as raw context. Simpler integration, no proxy indirection, but burns 10k+ tokens per server and does not scale past 2-3 servers.
CLI-only tooling (per Mario Zechner's take)
Replace MCP servers with custom shell scripts or executables. Smallest context footprint, full control, but requires building and maintaining custom adapters for each capability (database, browser, API).
Full MCP with server pooling/caching (e.g., Claude Code, Cursor native)
Host-native MCP support may cache tool metadata at IDE level, reducing per-session overhead. Tighter integration but lock-in to host tooling and no cross-platform portability.
Build on pi-mcp-adapter with DEV.co software developers
Use pi-mcp-adapter to run 3+ MCP servers in Pi without burning half your context window on tool definitions. Lazy loading, OAuth, and cross-host config sharing included.
Talk to DEV.coRelated open-source tools
Surfaced by semantic similarity across the DEV.co open-source index.
Related on DEV.co
Explore the category and the services that help you build with it.
pi-mcp-adapter FAQ
Will connecting 5+ MCP servers overload Pi's context?
Can I use both shared (~/.config/mcp/mcp.json) and Pi-specific (.pi/mcp.json) configs?
What happens if an MCP server crashes or hangs?
Is OAuth token storage secure?
Software development & web development with DEV.co
Need help beyond evaluating pi-mcp-adapter? DEV.co is a software development agency offering software development services and web development for teams of every size. Our software developers and web developers build custom software, web applications, APIs, and mcp servers integrations — and maintain them long-term.
Trim Context, Unlock More Tasks
Use pi-mcp-adapter to run 3+ MCP servers in Pi without burning half your context window on tool definitions. Lazy loading, OAuth, and cross-host config sharing included.