claude-mcp-bridge

Bridge Claude Code MCP server configurations into pi — auto-discovers and registers MCP tools from stdio, SSE, and streamable-HTTP servers.

What it does

• Config auto-discovery — scans for MCP settings in priority order:
  • PI_MCP_CONFIG env var (single file override)
  • Scoped search from cwd upward: .pi/mcp.json, .mcp.json, backend/.mcp.json, frontend/.mcp.json
  • Global: ~/.mcp.json, ~/.claude.json
  • First-seen server name wins on duplicates
• Protocol compatibility — auto-negotiates the stateless MCP 2026-07-28 protocol over stdio and streamable HTTP, then falls back to the 2025 initialize/session protocol for older servers
• Server transports — stdio, http (streamable HTTP), plus deprecated sse for legacy-server compatibility
• Lazy connections — by default the extension factory never waits for MCP servers; background connections start at session_start and tools register dynamically as servers become ready
• Tool schema cache — cached schemas are registered immediately from ~/.pi/agent/cache/claude-mcp-bridge/tools-v1.json and refreshed after connection
• Tool registration — each MCP tool becomes a pi tool named mcp__<server>__<tool>
• Tool toggle — enable/disable per-tool via /mcp-status overlay; persisted in ~/.pi/agent/claude-mcp-bridge-tools.json
• Auto-reconnect — exponential backoff on unexpected disconnection (up to 5 attempts)
• Status bar — footer shows connecting, connected, failed, offline, and cached states
• Large payload handling — responses > 30 KB are saved to a temp file with a truncated preview

Commands

| Command | Description | |---------|-------------| | /mcp-status | Interactive overlay: server list → actions (Tools toggle, Reconnect) |

Install

pi install npm:@ryan_nookpi/pi-extension-claude-mcp-bridge

Runtime controls

| Environment variable | Behavior | |----------------------|----------| | PI_OFFLINE=1 | Skip connections and reconnect timers while keeping matching cached tool schemas available | | PI_MCP_EAGER=1 | Wait for MCP connections during extension load (temporary rollback path) | | PI_MCP_CONNECT_TIMEOUT_MS | Override the per-server connection timeout (default: 30000 ms) | | PI_MCP_PROTOCOL_PROBE_TIMEOUT_MS | Override the stdio server/discover probe timeout for slow modern servers (default: min of 10000 ms and half the connection timeout) | | PI_MCP_TOOL_TIMEOUT_MS | Override the MCP tool call timeout (default: 60000 ms) |

Protocol compatibility

For stdio and streamable HTTP servers, the bridge uses the official TypeScript SDK's versionNegotiation: { mode: "auto" } flow:

1. Probe with server/discover for MCP 2026-07-28.
2. Use stateless, self-describing requests when the server supports it.
3. Fall back to the legacy initialize handshake when the server only supports a 2025-era protocol.

The stdio probe uses a shorter timeout than the full connection by default so a silent legacy server still has time to complete its initialize handshake. Set PI_MCP_PROTOCOL_PROBE_TIMEOUT_MS higher when a modern stdio server legitimately needs more than 10 seconds to start.

Explicit type: "sse" configurations stay on the legacy protocol because HTTP+SSE is deprecated and does not support the new stateless transport model. See the MCP 2026-07-28 changelog and the TypeScript SDK protocol version guide.

Notes

• Node.js 20 or newer is required by the MCP TypeScript SDK v2.
• ${ENV_NAME} in config values are expanded from environment variables.
• Cache fingerprints include only server names, transport types, URL hosts, and redacted command structure. Header and environment values are never persisted.
• URL paths and command argument values are intentionally excluded from fingerprints. Matching cached schemas can be briefly stale until live discovery refreshes them; rename the server or remove the cache before an offline-only run after such changes.
• Cache files are replaced atomically after every changed live tool discovery.
• A cached tool called before its server is ready waits for the existing connection attempt instead of starting a duplicate process.
• After changing MCP config (add/remove/rename servers), run /reload.