pi-mcp-extension

Connect Pi to any MCP server. Supabase, DeepSource, Playwright, Context7, filesystem, databases — if it speaks MCP, Pi can use it.

pi-mcp-extension is a production-ready Model Context Protocol client extension for the Pi coding agent. It manages server connections, discovers tools, and bridges them into Pi so the LLM can call them directly.

Features

• Multi-transport — stdio subprocesses, streamable-http (including "http" and URL-only shorthand), and legacy sse out of the box
• Auto-discovery — Paginated tools/list with cursor following (MCP 2025-03-26 spec)
• Live tool refresh — notifications/tools/list_changed triggers re-discovery without restart
• Clean cancellation — AbortSignal propagation via notifications/cancelled
• Smart reconnection — Fixed delay retry schedule (1s → 3s → 5s → 10s → 30s), configurable max retries, and automatic recovery when a server transport closes unexpectedly
• Health checks — Opt-in periodic pings to detect stale connections
• Safe process lifecycle — Child PID tracking (StdioClientTransport.pid) with safety-net SIGKILL for orphaned subprocesses
• Stable tool names — Sanitized, collision-avoiding names (max 64 chars) that stay constant across reconnects
• No tool churn — Activate/deactivate pattern ensures tools don't flicker during reconnection
• Layered config & trust boundary — Global <agent dir>/mcp.json, project .pi/mcp.json (loaded only in trusted projects via ctx.isProjectTrusted()), and Pi 1.x extension-registered servers (pi.registerMcpServer())
• Rich tool results & annotations — MCP image content passthrough (ImageContent), plus readOnlyHint, destructiveHint, idempotentHint, openWorldHint surfaced in tool descriptions
• On-demand agent tools & commands — mcp_status and mcp_connect agent tools plus /mcp, /mcp:start, /mcp:stop, and /mcp:auth slash commands with server-name autocomplete
• Structured error handling — Distinct error codes for config, connection, protocol, and tool-level failures
• OAuth 2.1 — Browser and headless/SSH authorization with PKCE, protected-resource discovery, Dynamic Client Registration, startup prompts for eager servers, cross-process lock recovery, token refresh, and secure local persistence (see OAUTH.md)

Installation

pi install npm:pi-mcp-extension

Or try without installing:

pi -e npm:pi-mcp-extension

Quick Start

1. Install the extension:

   pi install npm:pi-mcp-extension
   

2. (Pi 1.x) Disable Pi's built-in mcp extension so Pi does not warn that both extensions are enabled at the same time — either run pi config and uncheck mcp under Built-in extensions, or add "extensions": ["-builtin:mcp"] to ~/.pi/agent/settings.json:

   {
     "extensions": [
       "-builtin:mcp"
     ]
   }
   

3. Create a config file at ~/.pi/agent/mcp.json (global) or .pi/mcp.json (project-level):

   {
     "mcpServers": {
       "supabase": {
         "transport": "streamable-http",
         "url": "https://mcp.supabase.com/mcp",
         "lifecycle": "eager"
       }
     }
   }
   

4. Start Pi — your MCP tools are ready. Use /mcp to check server status.

Configuration

Servers can be configured via JSON files or registered programmatically by other Pi 1.x extensions:

Full Example

{
  "settings": {
    "toolPrefix": "mcp",         // Tools appear as mcp_<server>_<tool> (default: "mcp")
    "requestTimeoutMs": 30000,   // Per-request timeout in ms (default: 30000)
    "maxRetries": 5              // Max reconnection attempts, 0-10 (default: 5)
  },
  "mcpServers": {

    // ── HTTP-based servers ───────────────────────────────────────────────────
    "supabase": {
      "transport": "streamable-http",
      "url": "https://mcp.supabase.com/mcp",
      "auth": {
        "type": "oauth"
      },
      "lifecycle": "eager"
    },
    "deepsource": {
      "url": "https://mcp.deepsource.io/mcp", // "transport" defaults to "streamable-http" when "url" is set
      "lifecycle": "eager"
    },

    // ── Legacy SSE servers ───────────────────────────────────────────────────
    "legacy-server": {
      "transport": "sse",
      "url": "https://example.com/sse",
      "lifecycle": "lazy"
    },

    // ── stdio subprocess servers ─────────────────────────────────────────────
    "pathfinder": {
      "command": "/path/to/pathfinder-mcp",
      "transport": "stdio",
      "lifecycle": "eager"
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@context7/mcp"],
      "transport": "stdio",
      "lifecycle": "lazy"
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
      "transport": "stdio",
      "lifecycle": "lazy",
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Global Settings

In project-level .pi/mcp.json, settings keys carry no defaults — only the keys explicitly stated in the project file override global settings.

Per-Server Config

For Pi 1.x compatibility, server entries also accept type as an alias for transport, "http" as an alias for "streamable-http", oauth as an alias for auth, and timeout (in seconds) as an alias for requestTimeoutMs.

OAuth Config

Configured under auth (or oauth). Token and client state are persisted per server in <agent dir>/mcp-auth/<hash>.json (0700 directory, 0600 files on POSIX) with atomic writes and automatic backup of corrupt state files. See OAUTH.md for architecture and troubleshooting details.

Commands

Server-name arguments provide autocomplete suggestions from the configured MCP servers. /mcp:auth suggests only servers configured for OAuth.

Agent tools mcp_status and mcp_connect let Pi inspect configured servers and connect one named server without routine slash commands. mcp_status reports lifecycle, connection state, discovered and active tool counts, credential presence, and safe action hints without returning tokens, headers, or authorization URLs. mcp_connect activates discovered tools before returning success. Connection failures return fixed actionable categories instead of raw server response text.

OAuth startup, headless/SSH, and concurrency behavior

• Interactive sessions required for browser auth: Print and RPC sessions fail promptly when interactive authorization is required.
• Startup prompt for eager OAuth servers: Silent startup and background reconnects never open a browser unprompted or trigger Dynamic Client Registration when no client credentials are stored. When an eager OAuth server needs interactive authorization at startup in an interactive Pi session, Pi presents a sequential <name> needs authorization prompt (Authorize now / Not now). Choosing Authorize now runs the interactive OAuth flow; choosing Not now leaves the server stopped, shows a run /mcp:auth <name> footer hint, and remembers the decline for the rest of the session.
• Headless and SSH support: While authorization is pending, Pi displays the authorization URL and offers Retry: open browser again, Paste redirect URL, and Cancel authentication. On remote/SSH or headless machines, open the URL locally and either forward the callback port (ssh -L <port>:127.0.0.1:<port>) or paste the browser's final http://127.0.0.1:<port>/callback?code=...&state=... redirect URL into Paste redirect URL. Only https: (or loopback http:) authorization URLs are passed to the system browser opener.
• Coordinated connects and cross-process locks: Concurrent connect requests join an in-flight attempt, while --reset supersedes a normal connect and shares one pending reset. Cross-process interactive flows are serialized per server via <agent dir>/mcp-auth/<hash>.json.lock with a 30s heartbeat and automatic reclamation of locks from dead local PIDs or stale heartbeats (>90s), while allowing silent token refreshes to persist rotated tokens.

Connection readiness and active tools

mcp_status reports tools.discovered and tools.active for each server. Connection state ready means the MCP handshake and discovery completed. It does not mean that another Pi extension has kept every discovered tool active.

mcp_connect checks current tool activation before reporting success, including when the server is already connected. If discovered tools are inactive, it reports that condition instead of overriding another extension's tool restrictions. Check the active tool policy or conflicting extension. A reconnect is not a substitute for fixing an extension that removes tools at each user turn.

How It Works

┌─────────────────────────────────────────────────────────┐
│  Pi Agent                                               │
│                                                         │
│  ┌──────────┐    ┌────────────────┐    ┌─────────────┐  │
│  │ index.ts │───▶│ server-manager │───▶│ tool-bridge  │  │
│  │ (entry)  │    │ (lifecycle)    │    │ (MCP → Pi)   │  │
│  └──────────┘    └───────┬────────┘    └──────┬──────┘  │
│       │                  │                     │         │
│       ▼                  ▼                     ▼         │
│  ┌──────────┐    ┌──────────────┐    ┌──────────────┐   │
│  │ config   │    │ MCP SDK      │    │ TypeBox      │   │
│  │ (Zod)    │    │ (transport)  │    │ (schema)     │   │
│  └──────────┘    └──────────────┘    └──────────────┘   │
└─────────────────────────────────────────────────────────┘
         │                  │
         ▼                  ▼
   Global/Project    ┌──────────────┐
   mcp.json files    │ MCP Servers  │
   + Extensions      │ (stdio/http) │
                     └──────────────┘

1. Config is loaded from global <agent dir>/mcp.json, trusted project .pi/mcp.json (checked via ctx.isProjectTrusted() on session_start), and extension-registered servers (pi.getMcpServers() / mcp_servers_change), with mcp.json taking precedence over extension-registered servers and project entries overriding global ones
2. Eager servers connect at session_start (offering a sequential Authorize now / Not now prompt when an eager OAuth server needs authorization in an interactive session); lazy servers wait for mcp_connect, /mcp:start, or /mcp:auth
3. Tools are discovered via paginated tools/list calls (cursor-based, up to 100 pages) before a server enters ready
4. JSON Schema → TypeBox conversion registers tools with Pi-compatible parameter schemas
5. Pi tools are registered as <prefix>_<server>_<tool> (sanitized, max 64 chars with hash suffix) and pass through text and image content blocks (ImageContent)
6. Tools activate/deactivate automatically as servers connect/disconnect
7. AbortSignal is wired through to notifications/cancelled for clean cancellation
8. Reconnection & recovery uses a fixed delay schedule with configurable max retries on initial failure, health check failure, or unexpected transport close (client.onclose)
9. list_changed notifications trigger re-discovery, deactivating stale tools automatically
10. Session shutdown cancels pending auth/connection flows, stops the callback server, deactivates all tools, and cleanly stops all servers (with a SIGKILL safety net for stdio child processes)

MCP Spec Compliance

Implements the MCP 2025-03-26 specification for tool clients:

Development

# Install dependencies
npm install

# Type check (strict mode)
npm run typecheck

# Run all tests
npm test

# Run integration tests only (real stdio server)
npm run test:integration

Testing

The test suite includes:

• Config & Pi 1.x compatibility — Zod schema, $PI_CODING_AGENT_DIR resolution, global/project merge, project trust boundary (ctx.isProjectTrusted()), Pi 1.x schema aliases (type: "http", URL-only HTTP, oauth, timeout), and dynamic pi.getMcpServers() / mcp_servers_change
• Server lifecycle & coordination — Connect, retry, unexpected close recovery, shutdown with PID SIGKILL safety net, health check, concurrent connect/reset coordination, and cancellation
• OAuth 2.1 & auth locks — Challenge discovery, PKCE, Dynamic Client Registration, startup authorization prompts, headless/SSH redirect URL paste-back, URL scheme validation, cross-process lock heartbeat and stale lock reclamation
• Tool bridge & management tools — JSON Schema → TypeBox conversion, name sanitization, image content passthrough, isError filtering, activate/deactivate, mcp_status / mcp_connect, and slash command completions
• End-to-end integration — Real mock MCP and OAuth servers over stdio and HTTP with tool discovery and execution

License

MIT