Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nicobailon/pi-mcp-adapter/llms.txt

Use this file to discover all available pages before exploring further.

​
Pi MCP Adapter

Token-efficient MCP adapter for the Pi coding agent Pi MCP Adapter enables you to use MCP servers with Pi without sacrificing your context window. Instead of loading hundreds of tool definitions upfront, you get a single proxy tool (~200 tokens) that discovers and calls tools on-demand.

​
The Problem

MCP tool definitions are verbose. A single MCP server can burn 10,000+ 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. Mario Zechner wrote about why you might not need MCP, suggesting simple CLI tools instead. But the MCP ecosystem has valuable integrations—databases, browsers, APIs. This adapter gives you access without the bloat.

​
The Solution

One proxy tool (~200 tokens) instead of hundreds. The agent discovers what it needs on-demand. Servers only start when you actually use them. 
mcp({ search: "screenshot" })
Two calls instead of 26 tools cluttering the context.

​
Key Features

Token-Efficient Proxy

Single ~200 token proxy tool instead of 10k+ tokens for direct tool registration. Your context window stays clean.

Lazy Server Lifecycle

Servers don’t connect until you actually call their tools. Automatic idle timeout disconnects unused servers.

Metadata Caching

Tool discovery works offline. Search and describe tools without live server connections.

Direct Tool Registration

Optionally register frequently-used tools directly for instant LLM access—no search required.

Flexible Authentication

Support for OAuth and bearer token authentication for secure server connections.

Multiple Transports

HTTP and stdio transport with automatic fallback. Works with any MCP-compliant server.

Interactive Management

Built-in management panel for server status, tool toggles, and OAuth setup.

Config Import

Import existing configs from Cursor, Claude Desktop, VS Code, Windsurf, and Codex.

Installation

Get started with Pi MCP Adapter in under a minute

Quick Start

Configure your first server and start using MCP tools

Configuration

Deep dive into server options, lifecycle modes, and settings

GitHub Repository

View the source code and contribute to the project

​
How It Works

Under the hood, Pi MCP Adapter:
  • Registers a single mcp tool in your context (~200 tokens)
  • Keeps servers lazy by default—they connect on first tool call, not at startup
  • Caches tool metadata to disk so search/list/describe work without live connections
  • Disconnects idle servers after 10 minutes (configurable)
  • Resolves npx-based servers to direct binary paths, skipping the ~143 MB npm parent process
  • Validates arguments at the MCP server level, not in the adapter
  • Provides health checks and auto-reconnect for keep-alive servers
  • Promotes specific tools from proxy to first-class Pi tools via directTools config
Context Window Savings: With traditional MCP integration, 3-4 servers could consume 30k+ tokens just for tool definitions. With Pi MCP Adapter, you use ~200 tokens regardless of how many servers you connect.

​
Next Steps

1

Install the adapter

Follow the installation guide to add Pi MCP Adapter to your Pi setup.
2

Configure your servers

Create your mcp.json config file and add MCP servers using the quick start guide.
3

Start using tools

Search for tools, call them through the proxy, or register direct tools for instant access.