MCPInstall

pi-mcp-adapter

by reason-machinesAI & Agents

Token-efficient MCP adapter for Pi coding agent that enables MCP server integration without burning context window

Installs
202
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/reason-machines/mcp-skills --skill pi-mcp-adapter
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads pi-mcp-adapter automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

pi-mcp-adapter

Skill by 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

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:

{
  "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:

{
  "mcpServers": {
    "figma": {
      "url": "http://localhost:3845/mcp",
      "headers": {
        "Authorization": "Bearer ${FIGMA_TOKEN}"
      }
    }
  }
}

OAuth Configuration

For servers requiring OAuth:

{
  "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:

// 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:

{
  "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

{
  "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:

{
  "mcpServers": {
    "figma": {
      "url": "http://localhost:3845/mcp",
      "directTools": true,
      "excludeTools": ["get_figjam", "figma_get_code_connect_map"]
    }
  }
}

Lifecycle Management

Lifecycle Modes

{
  "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

{
  "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:

{
  "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:

# 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:

{
  "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:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/Documents"]
    }
  }
}

Advanced Settings

Complete Settings Reference

{
  "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:

{
  "mcpServers": {
    "problematic": {
      "command": "npx",
      "args": ["-y", "debug-mcp"],
      "debug": true
    }
  }
}

MCP UI Integration

Servers can ship interactive UIs via MCP UI standard. When a tool returns UI metadata, pi-mcp-adapter opens it in a native window (macOS with Glimpse) or browser.

Installing Glimpse (macOS)

pi install npm:glimpseui

Force browser rendering:

export MCP_UI_VIEWER=browser

Require native rendering:

export MCP_UI_VIEWER=glimpse

UI Communication Flow

  1. Agent calls tool with UI resource: mcp({ tool: "launch_dashboard", args: "{}" })
  2. Adapter fetches UI HTML from _meta.ui.resourceUri
  3. UI opens in native window or browser
  4. UI can call MCP tools and send messages back
  5. Agent retrieves messages: mcp({ action: "ui-messages" })
  6. Agent responds, enabling bidirectional conversation

Session Reuse

When the agent calls the same tool while its UI is open, the adapter pushes new results to the existing window instead of replacing it. Enables live updates without losing current view.

Common Patterns

Multi-Server Project Setup

{
  "settings": {
    "toolPrefix": "server",
    "idleTimeout": 15,
    "directTools": false
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${PROJECT_ROOT}"],
      "lifecycle": "keep-alive",
      "directTools": ["read_file", "write_file", "list_directory"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      },
      "directTools": ["search_repositories", "get_file_contents", "create_issue"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    }
  }
}

Working with Resources

MCP servers can expose resources (files, data) that aren't tools:

// List resources from a server
mcp({ action: "resources", server: "filesystem" })
// Returns: List of available resources with URIs

// Read a specific resource
mcp({ 
  action: "read-resource", 
  server: "filesystem", 
  uri: "file:///Users/me/project/README.md" 
})

Enable/disable resource tools:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/projects"],
      "exposeResources": true
    }
  }
}

Default is true. Set to false to hide resource-access tools.

Subagent Integration

Subagents can request direct MCP tools in frontmatter:

---
name: github-reviewer
tools:
  - read
  - edit
  - mcp:github
---

Review pull request and create detailed comments using GitHub MCP tools.

mcp:server-name syntax requests all direct tools from that server.

Troubleshooting

Server Won't Connect

Check config syntax:

cat .mcp.json | jq .

Enable debug output:

{
  "mcpServers": {
    "failing-server": {
      "command": "npx",
      "args": ["-y", "problem-mcp"],
      "debug": true
    }
  }
}

Force reconnect:

Run /mcp and press Enter on the server, or:

mcp({ action: "reconnect", server: "failing-server" })

Tools Not Appearing

Check cache:

Direct tools load from cache at ~/.pi/agent/mcp-cache.json. On first run after adding directTools, cache won't exist yet.

Force cache refresh:

# In Pi
/mcp reconnect <server-name>

Verify tool registration:

// List all available tools
mcp({ list: true })

// Search for specific tool
mcp({ search: "expected_tool_name" })

OAuth Not Working

Manual OAuth trigger:

  1. Run /mcp
  2. Navigate to OAuth server
  3. Press Enter or ctrl+a

Enable auto-auth:

{
  "settings": {
    "autoAuth": true
  }
}

Check client credentials:

For client_credentials grant, ensure env vars are set:

export API_CLIENT_ID="your-client-id"
export API_CLIENT_SECRET="your-secret"

High Token Usage

Problem: Too many direct tools burning context.

Solution 1 — Use proxy only:

{
  "mcpServers": {
    "huge-server": {
      "command": "npx",
      "args": ["-y", "mega-mcp"],
      "directTools": false
    }
  }
}

Solution 2 — Select specific tools:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "directTools": ["search_repositories", "get_file_contents"]
    }
  }
}

Solution 3 — Hide proxy tool:

{
  "settings": {
    "disableProxyTool": true,
    "directTools": true
  }
}

Only works when all needed tools are registered direct and cached.

Environment Variables Not Expanding

Ensure proper syntax:

{
  "env": {
    "CORRECT": "${MY_VAR}",
    "ALSO_CORRECT": "$env:MY_VAR",
    "WRONG": "$MY_VAR"
  }
}

Check variable is exported:

echo $MY_VAR
# Should print value

export MY_VAR="value"

Server Keeps Disconnecting

Adjust idle timeout:

{
  "mcpServers": {
    "chatty-server": {
      "command": "npx",
      "args": ["-y", "active-mcp"],
      "idleTimeout": 0
    }
  }
}

Or use keep-alive:

{
  "mcpServers": {
    "critical": {
      "command": "npx",
      "args": ["-y", "important-mcp"],
      "lifecycle": "keep-alive"
    }
  }
}

File Locations

  • Global shared config: ~/.config/mcp/mcp.json
  • Pi global override: ~/.pi/agent/mcp.json (or $PI_CODING_AGENT_DIR/mcp.json)
  • Project shared config: .mcp.json
  • Pi project override: .pi/mcp.json
  • Tool cache: ~/.pi/agent/mcp-cache.json (or $PI_CODING_AGENT_DIR/mcp-cache.json)

Key Commands Summary

CommandPurpose
/mcpOpen interactive config overlay
/mcp setupGuided first-run configuration
/mcp reconnect <server>Force server reconnection
mcp({ search: "query" })Find tools by keyword
mcp({ list: true })List all available tools
mcp({ describe: "tool" })Get tool schema
mcp({ tool: "name", args: "json" })Execute MCP tool
mcp({ action: "resources", server: "name" })List server resources
mcp({ action: "ui-messages" })Get pending UI messages

Example: Complete Chrome DevTools Setup

{
  "settings": {
    "toolPrefix": "server",
    "idleTimeout": 5
  },
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"],
      "lifecycle": "lazy",
      "directTools": [
        "take_screenshot",
        "get_console_logs",
        "execute_javascript"
      ],
      "excludeTools": ["deprecated_tool"]
    }
  }
}

Usage:

// Direct tool (appears in agent's tool list)
chrome_devtools_take_screenshot({ format: "png", fullPage: true })

// Or via proxy
mcp({ 
  tool: "chrome_devtools_get_console_logs", 
  args: '{}' 
})

// Search for other tools
mcp({ search: "navigate" })

FAQ

What does the pi-mcp-adapter skill do?

Token-efficient MCP adapter for Pi coding agent that enables MCP server integration without burning context window

How do I install pi-mcp-adapter?

Run npx skills add https://github.com/reason-machines/mcp-skills --skill pi-mcp-adapter in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/pi-mcp-adapter/ (personal) or .claude/skills/pi-mcp-adapter/ (project).

Which AI agents can use pi-mcp-adapter?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is pi-mcp-adapter safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains pi-mcp-adapter?

It is published by reason-machines in reason-machines/mcp-skills. It has 202 recorded installs.

More from reason-machines/mcp-skills

View all →

codebase-memory-mcp-intelligence

reason-machines/mcp-skills

High-performance code intelligence MCP server that indexes codebases into knowledge graphs for structural queries, call traces, and architecture analysis

AI & Agents505 installs

playwright-mcp-server

reason-machines/mcp-skills

Browser automation MCP server using Playwright's accessibility tree for LLM-friendly web interaction

AI & Agents285 installs

tradingview-mcp-assistant

reason-machines/mcp-skills

AI-assisted TradingView chart analysis and automation via Chrome DevTools Protocol for Claude Code

AI & Agents262 installs

lanhu-mcp-collaboration

reason-machines/mcp-skills

Open the skill to read its SKILL.md instructions.

AI & Agents245 installs

chrome-devtools-mcp-automation

reason-machines/mcp-skills

Expert guidance for Chrome DevTools MCP server - browser automation, debugging, and performance analysis for AI agents

AI & Agents239 installs

github-mcp-server

reason-machines/mcp-skills

Open the skill to read its SKILL.md instructions.

AI & Agents237 installs

Popular ai & agents skills

View category →

google-agents-cli-publish

google/agents-cli

This skill should be used when the user wants to "publish an agent", "publish my ADK agent", "register an agent with Gemini", "publish to Gemini" (formerly Gemini Enterprise), or needs guidance on the agents-cli publish gemini command. Also use when the user wants to "manage agents in Agent Registry", "list/update/delete registered agents", or "register an MCP server". Covers ADK vs A2A registration modes, programmatic and interactive usage, flag reference, auto-detection from deployment metadata, Agent Registry fleet management, and troubleshooting. Part of the agents-cli skills suite. Do NOT use for deployment (use google-agents-cli-deploy).

AI & Agents513.9K installs

google-agents-cli-eval

google/agents-cli

This skill should be used when the user wants to "run an evaluation", "evaluate my agent", "evaluate my ADK agent", "write an eval dataset", "analyze eval failures", "compare eval results", "optimize agent", or needs guidance on the Gemini platform eval methodology and the Quality Flywheel. Covers eval metrics, dataset schema, LLM-as-judge scoring, and common failure causes. Applies to any agents-cli project, whatever framework the agent is written in. Do NOT use for agent API code patterns (ADK: use google-agents-cli-adk-code), deployment (use google-agents-cli-deploy), or project scaffolding (use google-agents-cli-scaffold).

AI & Agents513.5K installs

skill-creator

anthropics/skills

Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.

OfficialAI & Agents416.4K installs

codex-pet

prime-skills/runcomfy-agent-skills

Codex Pet generator on RunComfy. Build a Codex-compatible Codex Pet spritesheet.webp + pet.json from a single reference image, drop it into ${CODEXHOME:-$HOME/.codex}/pets/ / and Codex picks it up as a custom Codex Pet next to the 8 built-ins. This skill produces the exact Codex Pet atlas Codex expects (1536x1872 PNG/WebP, 8 cols x 9 rows, 192x208 cells, 9 animation states — idle, running-right, running-left, waving, jumping, failed, waiting, running, review). Calls OpenAI GPT Image 2 edit ONCE via the local RunComfy CLI as runcomfy run openai/gpt-image-2/edit to produce a canonical Codex Pet pose, then assembles all 9 animation rows programmatically with ImageMagick micro-transforms — no Codex Pro, no $imagegen, no OPENAIAPIKEY required, only RUNCOMFYTOKEN. Triggers on "codex pet", "create codex pet", "make codex pet", "hatch codex pet", "/hatch image", "desktop pet codex", "codex pets", "spritesheet.webp", or any explicit ask to build a custom pet for OpenAI Codex.

AI & Agents402.1K installs

full-output-enforcement

leonxlnx/taste-skill

Overrides default LLM truncation behavior. Enforces complete code generation, bans placeholder patterns, and handles token-limit splits cleanly. Apply to any task requiring exhaustive, unabridged output.

AI & Agents401K installs

executing-plans

obra/superpowers

Use when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available

AI & Agents245.7K installs