nicobailon/pi-mcp-adapter

Pi MCP Adapter – What It Is

Purpose – The adapter lets the Pi coding‑assistant (a LLM‑driven AI agent) talk to MCP servers without loading every server’s tool definitions into the model’s context. It starts a server only when the model actually calls one of its tools, stops it after a short idle period, and caches the tool metadata. The result is fewer tokens spent on “bloat”, lower memory use, and faster sessions.

How it works

• Pi sees a single proxy tool called mcp (~200 tokens). When the model runs mcp({search:…}) or mcp({tool:…}) the adapter forwards the request to the appropriate MCP server.
• Servers are lazy: they launch on first use and shut down after 10 minutes of inactivity (configurable).
• Tool lists are cached on disk, so the model can search or describe tools without the server running.
• OAuth tokens are stored in the OS keychain by default, not in plain JSON files.
• Optional script mode lets you batch many calls in one request, matching Pi’s built‑in codemode behaviour.

Key benefits over Pi’s built‑in MCP support

Feature	Pi built‑in MCP	pi‑mcp‑adapter
Servers started at session start	All enabled servers (high memory)	Only servers actually used (much lower memory)
Token cost for a single lookup	Higher (full codemode script)	10‑33 % less
Semantic tool search	Word‑only	Word or regex; with a System One key can rank by meaning
OAuth token storage	Plain JSON file	OS keychain
UI support	None	Native window or browser UI
Import configs from other IDEs	Manual conversion	Guided import (/mcp‑adapter setup)

Typical workflow

1. Install the adapter: pi install npm:pi-mcp-adapter and restart Pi.
2. Add a server (e.g. Chrome DevTools) to a .mcp.json file or run /mcp‑adapter setup to import existing configs.
3. In a Pi chat, call:

   mcp({ search: "screenshot" })
   

   The adapter returns the matching tool description.
4. Execute the tool:

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

   The server starts, runs the command, then idles and shuts down after 10 min.

Main commands (run inside a Pi session)

• /mcp‑adapter – opens the interactive setup/onboarding panel.
• /mcp‑adapter setup – guided import of Cursor/Claude/VS Code configs, adds preset servers (Figma, GitHub, etc.).
• /mcp‑auth <server> – OAuth sign‑in for a server.
• /mcp‑adapter edit [project|global] – edit the .mcp.json or global config.
• /mcp‑adapter tools – list all discovered tools.
• /mcp‑adapter reconnect … – manually reconnect servers.

Limitations

• Each Pi session spawns its own server processes (can be shared via rmcp‑mux).
• Inline images still depend on Pi’s display settings.
• MCP sampling only supports text; audio/image payloads are rejected.

Documentation – Full reference lives in the docs/ folder (configuration, server options, authentication, scripting, UI, extension API, etc.).