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, 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
• Health checks — Opt-in periodic pings to detect stale connections
• Safe process lifecycle — PID tracking 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
• Global + project config — Layered config (project overrides global) with per-server tuning
• Tool annotations — readOnlyHint, destructiveHint, idempotentHint, openWorldHint surfaced in tool descriptions
• Structured error handling — Distinct error codes for config, connection, protocol, and tool-level failures

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. 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"
       }
     }
   }
   

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

Configuration

Config files are loaded from two locations. Project config overrides global config via shallow merge (server-level replacement).

Location	Scope
~/.pi/agent/mcp.json	Global — applies to all projects
.pi/mcp.json	Project — overrides global per-server

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",
      "lifecycle": "eager"
    },
    "deepsource": {
      "transport": "streamable-http",
      "url": "https://mcp.deepsource.io/mcp",
      "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

Field	Type	Default	Description
toolPrefix	string	"mcp"	Prefix for registered tools: <prefix>_<server>_<tool>. Must match ^[a-zA-Z][a-zA-Z0-9_]*$.
requestTimeoutMs	number	30000	Default per-request timeout in milliseconds
maxRetries	number	5	Max reconnection attempts (0–10) before giving up

Per-Server Config

Field	Type	Default	Description
transport	"stdio" | "streamable-http" | "sse"	"stdio"	Transport protocol
command	string	—	Executable to spawn (required for stdio)
args	string[]	[]	Arguments for the command
env	Record<string, string>	—	Extra environment variables for the child process
url	string	—	Server URL (required for streamable-http/sse)
lifecycle	"eager" | "lazy"	"lazy"	eager = auto-start on session start, lazy = manual via /mcp:start
requestTimeoutMs	number	global setting	Per-server timeout override
healthCheckIntervalMs	number	disabled	Opt-in ping interval for connection health monitoring

Commands

Command	Description
/mcp	Show status summary of all configured servers
/mcp <name>	Show detailed status and stderr log for a specific server
/mcp:start <name>	Start a server (resets retry count)
/mcp:stop <name>	Stop a running server and deactivate its tools

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  │
                     │ (stdio/http) │
                     └──────────────┘

1. Config is loaded from global and project files (project overrides global by server name)
2. Eager servers connect at session start; lazy servers wait for /mcp:start
3. Tools are discovered via paginated tools/list calls (cursor-based, up to 100 pages)
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)
6. Tools activate/deactivate automatically as servers connect/disconnect
7. AbortSignal is wired through to notifications/cancelled for clean cancellation
8. Reconnection uses a fixed delay schedule with configurable max retries
9. list_changed notifications trigger re-discovery, deactivating stale tools automatically
10. Session shutdown cleanly stops all servers and deactivates all tools

MCP Spec Compliance

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

Feature	Status
Protocol version 2025-03-26 (+ 2024-11-05 fallback)	✅
stdio transport	✅
streamable-http transport	✅
sse transport (legacy backwards compat)	✅
Cursor-based tools/list pagination	✅
tools/call with parameters	✅
roots/list capability (workspace root)	✅
notifications/tools/list_changed (live refresh)	✅
notifications/cancelled (AbortSignal)	✅
notifications/message (structured logging)	✅
isError: true distinction (protocol vs tool errors)	✅
Tool annotations (readOnlyHint, destructiveHint, etc.)	✅
Resources bridge	⏳ v2
Prompts bridge	⏳ v2
Sampling	⏳ v2

Development

# Install dependencies
npm install

# Type check (strict mode)
npm run typecheck

# Run all tests (47 tests)
npm test

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

Testing

The test suite includes:

• Config validation — Zod schema, global/project merge, defaults, error cases
• Server lifecycle — Connect, retry, shutdown, health check, race conditions
• Tool bridge — JSON Schema → TypeBox conversion, name sanitization, activate/deactivate
• End-to-end integration — Real mock MCP server over stdio with tool discovery and execution

License

MIT