pi-mcp

Pi extension that ports OpenCode-style MCP client support to Pi.

Requirements

Pi-MCP requires Node.js 20 or newer. It negotiates the stateless MCP 2026-07-28 protocol when available and automatically falls back to compatible 2025-era servers.

Install

From GitHub:

pi install git:github.com/dmmulroy/pi-mcp

For a temporary run:

pi -e /Users/dmmulroy/Documents/pi-mcp

Configuration

The extension reads OpenCode-compatible MCP config from, in order:

1. PI_MCP_CONFIG as a JSON string or path to a JSON/JSONC file
2. .pi/mcp.json or .pi/mcp.jsonc
3. opencode.json, opencode.jsonc, .opencode/opencode.json, .opencode/opencode.jsonc
4. ~/.pi/agent/mcp.json or ~/.pi/agent/mcp.jsonc

Supported flat OpenCode shape:

{
  "mcp": {
    "playwright": {
      "type": "local",
      "command": ["npx", "-y", "@playwright/mcp"],
      "enabled": true,
      "timeout": 30000
    },
    "docs": {
      "type": "remote",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${DOCS_TOKEN}"
      }
    }
  }
}

Also supported:

{
  "mcp": {
    "timeout": 30000,
    "startup": "lazy",
    "servers": {
      "playwright": {
        "type": "local",
        "command": ["npx", "-y", "@playwright/mcp"]
      }
    }
  }
}

startup controls connection timing:

In direct tool mode, startup: "lazy" means MCP tools are not registered at startup. Open /mcp, select a server, and press c to connect it, or press r to reload the configuration and connect enabled servers. Use startup: "eager" if you want direct MCP tools to appear automatically without blocking Pi startup.

In proxy tool mode, the mcp gateway registers immediately. With startup: "lazy", it connects enabled servers on demand.

"eager" starts connecting enabled servers in the background after Pi startup. Eager connects run in parallel and do not block Pi’s session_start handler.

${ENV_VAR} placeholders in environment, headers, url, and cwd are expanded from the process environment.

Command

/mcp opens a keyboard-driven server manager inspired by Pi’s worktree manager. It shows connection, OAuth, tool, prompt, resource, target, and configuration details without adding a separate slash command for every operation.

• ↑/↓ selects a server.
• enter or c connects or reconnects it.
• d disconnects it for the current runtime.
• a starts OAuth when available.
• l confirms and removes stored OAuth credentials.
• p selects and sends one of the server’s prompts.
• r reloads configuration and reconnects enabled servers.
• esc closes the manager.

Outside TUI mode, /mcp reports the current server statuses without opening the interactive manager.

In direct tool mode, connected MCP tools are registered as Pi tools using OpenCode’s sanitized name convention:

_