pi-mcp-adapter — Claude Code skill: what it does, how to install
pi-mcp-adapter is a skill for the Pi agent that connects MCP servers through one proxy tool instead of loading hundreds of definitions into context. Servers connect on demand.
no license 202 installs ★ 9 updated 2026-10-09
npx skills add reason-machines/mcp-skills --skill pi-mcp-adapter -a claude-codeWhat pi-mcp-adapter does
This skill drops an MCP adapter into the Pi coding agent. A big server would otherwise dump 10k+ tokens of tool definitions into the window; here Pi sees a single mcp proxy of roughly 200 tokens and uses it to search, describe or run a tool. Connections open on demand, so the window stays clear. Inside Pi the adapter itself goes in with pi install npm:pi-mcp-adapter, then Pi restarts.
Configs stack across four files: ~/.config/mcp/mcp.json, ~/.pi/agent/mcp.json, .mcp.json and .pi/mcp.json, later ones overriding earlier. An entry is either a launch command with args and env, or a URL for HTTP/SSE with headers. OAuth works too: with autoAuth: true the handshake runs on the first tool call, otherwise open /mcp and press Enter or ctrl+a.
Switch on directTools and the schemas land in the system prompt, each one costing 150-300 tokens. On a server with hundreds of tools that cancels the savings, so keep the list to what you call constantly. excludeTools hides the rest, and lifecycle picks between lazy, eager and keep-alive. The default idleTimeout is 10 minutes, and zero turns it off.
What it helps with
- wire an MCP server into Pi without flooding the context window
- keep idle servers from holding a connection open
- expose only the tools the agent actually calls
- run the OAuth handshake for a server on first use
- layer project and global MCP configs in the right order
Example prompts for the agent
- Hook the chrome-devtools MCP server into Pi with pi-mcp-adapter, keep it on the proxy.
- Add a github entry to
.mcp.jsonand pull the token fromGITHUB_TOKEN. - Turn on OAuth with autoAuth for google-drive so the login happens on the first call.
How to install pi-mcp-adapter
1Skills CLI (Vercel)
npx skills add reason-machines/mcp-skills --skill pi-mcp-adapter -a claude-code2Manually: put the files in place
~/.claude/skills/pi-mcp-adapter/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/pi-mcp-adapter/
1Skills CLI (Vercel)
npx skills add reason-machines/mcp-skills --skill pi-mcp-adapter -a codex2Manually: put the files in place
.agents/skills/pi-mcp-adapter/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add reason-machines/mcp-skills --skill pi-mcp-adapter -a cursor2Manually: put the files in place
.cursor/skills/pi-mcp-adapter/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install reason-machines/mcp-skills skills/pi-mcp-adapter2Manually: put the files in place
.github/skills/pi-mcp-adapter/SKILL.md1Skills CLI (Vercel)
npx skills add reason-machines/mcp-skills --skill pi-mcp-adapter -a gemini-cli2Platform CLI
gemini skills install https://github.com/reason-machines/mcp-skills --path skills/pi-mcp-adapterManually: put the files in place
.devin/skills/pi-mcp-adapter/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add reason-machines/mcp-skills --skill pi-mcp-adapter -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about pi-mcp-adapter
How do I install pi-mcp-adapter in Claude Code?
Run npx skills add reason-machines/mcp-skills --skill pi-mcp-adapter -a claude-code. The skill file lands at ~/.claude/skills/pi-mcp-adapter/SKILL.md.
What does pi-mcp-adapter do?
It puts one mcp proxy tool in front of your MCP servers and connects to a server only when a tool from it is called. Tool lookup, schemas and execution all go through that single tool.
Which MCP config file wins when several exist?
Order is ~/.config/mcp/mcp.json, then ~/.pi/agent/mcp.json, then .mcp.json, then .pi/mcp.json. A later file overrides the earlier ones.