pi-mcp-extension weekly downloads statistics

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:

Source	Precedence & Scope
.pi/mcp.json	Highest — Project-level overrides per server and per explicitly stated setting. Loaded on session_start only when the project is trusted (ctx.isProjectTrusted()); never read at bootstrap or in untrusted projects.
~/.pi/agent/mcp.json	Global — Applies to all projects (honors $PI_CODING_AGENT_DIR with ~ expansion when set: <agent dir>/mcp.json).
pi.registerMcpServer()	Extension-registered — Discovered via pi.getMcpServers() and updated live on mcp_servers_change events when replacing builtin:mcp. Any server with the same name in mcp.json takes precedence.

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"
    },…