pi-mcp-adapter

# pi-mcp-adapter > Skill by [ara.so](https://ara.so) — MCP Skills collection. ## Overview pi-mcp-adapter is a token-efficient proxy for Model Context Protocol (MCP) servers in the Pi coding agent. Instead of exposing hundreds of tool definitions (10k+ tokens per server), it provides a single ~200 token proxy tool that discovers MCP capabilities on-demand. Servers lazy-load when needed, keeping your context window clean. **Key benefits:** - **One proxy tool** instead of hundreds cluttering context - **Lazy server loading** — only connect when tools are called - **Direct tool registration** for high-priority tools - **Standard MCP file support** — reads `.mcp.json` and `~/.config/mcp/mcp.json` - **Interactive configuration** via `/mcp` overlay ## Installation ```bash pi install npm:pi-mcp-adapter ``` Restart Pi after installation. The adapter auto-detects standard MCP config files on first run. ## Configuration Files ### File Precedence Pi reads MCP configs in this order (later overrides earlier): 1. `~/.config/mcp/mcp.json` — User-global shared config 2. `~/.pi/agent/mcp.json` — Pi global override (or `$PI_CODING_AGENT_DIR/mcp.json`) 3. `.mcp.json` — Project-local shared config 4. `.pi/mcp.json` — Pi project override ### Basic Server Configuration Create `.mcp.json` in your project root: ```json { "mcpServers": { "chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp@latest"] }, "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" } }, "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"] } } } ``` ### HTTP/SSE Servers For servers with HTTP endpoints: ```json { "mcpServers": { "figma": { "url": "http://localhost:3845/mcp", "headers": { "Authorization": "Bearer ${FIGMA_TOKEN}" } } } } ``` ### OAuth Configuration For servers requiring OAuth: ```json { "mcpServers": { "google-drive": { "command": "npx", "args": ["-y", "gdrive-mcp"], "auth": "oauth", "oauth": { "grantType": "authorization_code" } }, "api-service": { "url": "https://api.example.com/mcp", "auth": "oauth", "oauth": { "grantType": "client_credentials" }, "env": { "CLIENT_ID": "${API_CLIENT_ID}", "CLIENT_SECRET": "${API_CLIENT_SECRET}" } } }, "settings": { "autoAuth": true } } ``` **OAuth flow:** - With `autoAuth: true`, adapter runs OAuth automatically on first tool call - Without `autoAuth`, run `/mcp` and press Enter on the server or use `ctrl+a` - `client_credentials` grant skips interactive prompts for machine-to-machine auth ## Using MCP Tools ### Proxy Mode (Default) All MCP tools are accessed through the `mcp` proxy tool: ```typescript // Search for available tools mcp({ search: "screenshot" }) // Returns: chrome_devtools_take_screenshot - Take a screenshot of the page... // Describe a specific tool mcp({ describe: "chrome_devtools_take_screenshot" }) // Returns: Full parameter schema // Call a tool (args must be JSON string) mcp({ tool: "chrome_devtools_take_screenshot", args: '{"format": "png", "fullPage": true}' }) ``` **Available proxy actions:** - `{ search: "query" }` — Find tools by keyword - `{ list: true }` — List all available tools - `{ describe: "tool_name" }` — Get tool details - `{ tool: "name", args: "json" }` — Execute a tool - `{ action: "resources", server: "name" }` — List server resources - `{ action: "read-resource", server: "name", uri: "file://..." }` — Read resource content - `{ action: "ui-messages" }` — Get pending UI messages ### Direct Tools Register specific tools individually for immediate LLM visibility: ```json { "mcpServers": { "chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp@latest"], "directTools": true }, "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "directTools": ["search_repositories", "get_file_contents"] } } } ``` **Direct tool options:** - `true` — Register all tools from this server - `["tool_a", "tool_b"]` — Register only specified tools - `false` or omitted — Proxy only (default) **Token cost:** Each direct tool adds ~150-300 tokens to system prompt. Good for 5-20 high-priority tools. ### Global Direct Tool Default ```json { "settings": { "directTools": true }, "mcpServers": { "huge-server": { "command": "npx", "args": ["-y", "mega-mcp@latest"], "directTools": false } } } ``` ### Excluding Tools Hide specific tools from proxy and direct registration: ```json { "mcpServers": { "figma": { "url": "http://localhost:3845/mcp", "directTools": true, "excludeTools": ["get_figjam", "figma_get_code_connect_map"] } } } ``` ## Lifecycle Management ### Lifecycle Modes ```json { "mcpServers": { "lazy-server": { "command": "npx", "args": ["-y", "some-mcp"], "lifecycle": "lazy", "idleTimeout": 10 }, "eager-server": { "command": "npx", "args": ["-y", "another-mcp"], "lifecycle": "eager" }, "critical-server": { "command": "npx", "args": ["-y", "important-mcp"], "lifecycle": "keep-alive" } } } ``` **Lifecycle options:** - **`lazy`** (default) — Connect on first use, disconnect after idle timeout. Cached metadata keeps search working without connections. - **`eager`** — Connect at startup, no auto-reconnect. No idle timeout unless explicitly set. - **`keep-alive`** — Connect at startup, auto-reconnect, never timeout. For always-available servers. ### Idle Timeout ```json { "settings": { "idleTimeout": 10 }, "mcpServers": { "keep-warm": { "command": "npx", "args": ["-y", "warm-mcp"], "idleTimeout": 0 } } } ``` Global `idleTimeout` (default 10 minutes) applies to all servers. Set to `0` to disable. Per-server overrides global setting. ## Tool Prefixing Control how tool names are prefixed: ```json { "settings": { "toolPrefix": "server" } } ``` **Prefix modes:** - `"server"` (default) — `chrome_devtools_take_screenshot` - `"short"` — Strips `-mcp` suffix: `chrome_devtools_take_screenshot` - `"none"` — No prefix: `take_screenshot` ## Interactive Configuration ### `/mcp` Overlay Run `/mcp` in Pi to open interactive panel: - View all configured servers with connection status - See tool counts and lifecycle modes - Toggle tools between direct and proxy registration - Reconnect servers manually - Trigger OAuth authentication (Enter on server or `ctrl+a`) ### `/mcp setup` Guided Setup Run `/mcp setup` for first-time configuration: 1. **Detect existing configs** — Scans for `.mcp.json`, `~/.config/mcp/mcp.json`, and host-specific configs (Cursor, Claude Code, etc.) 2. **Import compatibility** — Adopt host configs into Pi with preview before writing 3. **Scaffold minimal config** — Create basic `.mcp.json` with prompts 4. **Quick-add RepoPrompt** — One-shot add popular MCP servers 5. **Preview file changes** — Shows exact before/after diffs before any writes ### CLI Tool After installation, `pi-mcp-adapter` CLI is available: ```bash # Scan for host configs and create compatibility imports pi-mcp-adapter init # Show detected config files pi-mcp-adapter info ``` ## Environment Variables ### Variable Interpolation Supports `${VAR}` and `$env:VAR` syntax: ```json { "mcpServers": { "db": { "command": "npx", "args": ["-y", "db-mcp"], "env": { "DATABASE_URL": "${DB_URL}", "API_KEY": "$env:SECRET_KEY" }, "cwd": "${PROJECT_ROOT}/data" } } } ``` **Home directory expansion:** ```json { "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/Documents"] } } } ``` ## Advanced Settings ### Complete Settings Reference ```json { "settings": { "toolPrefix": "server", "idleTimeout": 10, "directTools": false, "disableProxyTool": false, "autoAuth": false, "sampling": true, "samplingAutoApprove": false } } ``` **Settings:** - `toolPrefix` — `"server"`, `"short"`, or `"none"` - `idleTimeout` — Minutes before disconnect (0 to disable) - `directTools` — Global default for all servers - `disableProxyTool` — Hide `mcp` proxy once direct tools are cached - `autoAuth` — Auto-run OAuth on tool calls - `sampling` — Allow MCP servers to sample through Pi models - `samplingAutoApprove` — Skip sampling confirmation prompts (required for non-UI sessions) ### Debugging Enable server stderr output: ```json { "mcpServers": { "problematic": { "command": "npx", "args": ["-y", "debug-mcp"], "debug": true } } } ``` ## MCP UI Integration Servers can ship interactive UIs via [MCP UI standard](https://github.com/MCP-UI-Org/mcp-ui). When a tool returns UI metadata, pi-mcp-adapter opens it in a native window (macOS with Glimpse) or browser. ### Installing Glimpse (macOS) ```bash pi install npm:glimpseui ``` **Force browser rendering:** ```bash export MCP_UI_VIEWER=browser ``` **Require native rendering:** ```bash export MCP_UI_VIEWER=glimpse ``` ### UI Communication Flow