nicobailon/pi-mcp-adapter

Token-efficient MCP adapter for Pi coding agent

What it solves

Pi MCP Adapter prevents the LLM context window from being overwhelmed by verbose tool definitions. In standard Model Context Protocol (MCP) setups, a single server can consume thousands of tokens just to describe its available tools, which costs tokens regardless of whether those tools are actually used. This adapter replaces hundreds of individual tool definitions with a single proxy tool, allowing the agent to discover and call tools on-demand.

How it works

Instead of registering every tool from every connected MCP server directly with the LLM, the adapter provides a single mcp proxy tool. The agent uses this proxy to search for specific tools and then execute them.

Key technical features include:

  • Lazy Loading: Servers are not connected to until a tool is call is actually made, reducing startup overhead.
  • Configuration Merging: It automatically detects and merges configurations from multiple sources, including standard .mcp.json files and host-specific configs (like those from Cursor or Claude Code).
  • Output Guarding: To prevent massive tool outputs from blowing up the context window, the adapter caps text output at 50 KiB or 2,000 lines, saving oversized results to temporary files for the agent to read selectively.
  • Lifecycle Management: Supports various connection modes including lazy, eager, keep-alive, and lazy-keep-alive to optimize resource usage.

Who it’s for

Developers using Pi who want to integrate MCP servers (databases, browsers, APIs) without sacrificing their context window to tool metadata.

Highlights

  • Context Efficiency: Reduces tool definition overhead from thousands of tokens to approximately 200 tokens.
  • Flexible Config: Supports project-local and user-global shared MCP configurations.
  • Secure OAuth: Integrates with OS credential stores for secure token management and supports remote/headless OAuth flows.
  • Resource Management: Includes an "Output Guard" to prevent oversized tool responses from crashing the session.
  • On-Demand Discovery: Allows agents to find tools via search rather than having all tools pre-loaded into the prompt.