Pi MCP Adapter

// Overview

Pi MCP Adapter is an extension for the Pi coding agent that lets it use Model Context Protocol servers without filling its context window. The adapter installs as a Pi package from npm and adds a single `mcp` tool plus a set of `/mcp-adapter` slash commands.

The project exists because of a cost the README spells out: MCP tool definitions are verbose, a single server can burn 10k+ tokens, and you pay that cost whether the tools are used or not — connect a few servers and half the context window is gone before the conversation starts. The README cites a post by Mario Zechner arguing you might not need MCP at all and should write simple CLI tools instead. The adapter takes the other route: keep access to the MCP ecosystem (databases, browsers, APIs) but expose it through one proxy tool of roughly 200 tokens, and let the agent search for and describe the tools it needs on demand.

Servers are lazy by default: they connect on the first tool call, not at startup, and tool metadata is cached to disk so search, list and describe work without a live connection. Idle servers disconnect after 10 minutes (configurable) and reconnect on next use. The adapter reads the standard `.mcp.json` and `~/.config/mcp/mcp.json` files and can import server configs from Cursor, Claude Code and Codex. It is written in TypeScript and released under the MIT license.

// What it does

• One `mcp` proxy tool (~200 tokens) in context instead of every server's tool definitions; the agent searches and describes tools on demand
• Lazy servers that start on first call, cached tool metadata, and idle disconnect after 10 minutes with automatic reconnect
• Reads `.mcp.json` / `~/.config/mcp/mcp.json` and imports existing configs from Cursor, Claude Code and Codex via `/mcp-adapter setup` or `pi-mcp-adapter init`
• Per-server controls: `directTools` to promote chosen tools to first-class Pi tools, `approveTools` to confirm risky calls, `includeTools` / `excludeTools`, and a keep-alive lifecycle
• OAuth sign-in with `/mcp-auth`, MCP prompts registered as slash commands, and an opt-in `mcpScript` tool for chaining many MCP calls in one step
• npx-based servers resolve to direct binary paths, skipping the ~143 MB npm parent process

// Getting started

The adapter installs through Pi's own package command from npm. If you already keep MCP servers in a standard `.mcp.json`, Pi picks them up with no extra setup.

pi install npm:pi-mcp-adapter

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

mcp({ search: "screenshot" })

mcp({ tool: "chrome_devtools_take_screenshot", args: { format: "png" } })

pi-mcp-adapter init

Commands and code are distilled from the project's own documentation — always check the official repo for the latest.

// When to use it

• Give a Pi agent browser, database or API access through existing MCP servers without spending thousands of tokens on tool definitions up front
• Reuse the MCP servers already configured for Cursor, Claude Code or Codex in Pi
• Connect OAuth-protected remote MCP servers and require approval before destructive tools run
• Promote a handful of frequently used MCP tools to first-class Pi tools while keeping the rest behind search

// How Pi MCP Adapter compares

Pi MCP Adapter alongside other open-source coding-agent harnesses & runtimes tools AI/TLDR tracks, ranked by GitHub stars.