pi-mcp-bridge

A minimal pi extension that exposes MCP server tools to pi via stdio transport.

Packages

Package details

extension

Install pi-mcp-bridge from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-mcp-bridge
Package
pi-mcp-bridge
Version
0.1.0
Published
May 20, 2026
Downloads
not available
Author
tmonk
License
MIT
Types
extension
Size
19.6 KB
Dependencies
0 dependencies · 2 peers
Pi manifest JSON
{
  "type": "extension",
  "extensions": [
    "./index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-mcp-bridge

A minimal MCP client extension for pi.

Attach any MCP server to pi. The extension spawns the server as a persistent subprocess, discovers its tools via the standard MCP handshake, and registers them so the pi agent can call them directly — no per-call startup overhead, no stubs.

Install

# From pi.dev gallery
pi install https://github.com/tmonk/pi-mcp-bridge

# Or try without installing
MCP_SERVER_CMD="python -m my_mcp_server" pi -e https://github.com/tmonk/pi-mcp-bridge "Run my tool"

Usage

# Load with an MCP server
MCP_SERVER_CMD="python -m my_mcp_server" pi "Run a query with my MCP tool"

# With a working directory and extra args
MCP_SERVER_DIR=~/projects/my-server MCP_SERVER_CMD="node server.js" MCP_SERVER_ARGS='["--port", "8080"]' pi "..."

# With pi's isolation flags
MCP_SERVER_DIR=~/projects/my-server pi -p --no-extensions --no-skills "Use the registered tool"

How it works

  1. On load — spawns the MCP server as a persistent subprocess and completes the initialization handshake (initialize → notifications/initialized).
  2. Discovery — issues tools/list, then calls pi.registerTool() for each discovered tool with dynamically converted TypeBox parameter schemas.
  3. Execution — when the agent calls a tool, sends tools/call over the persistent connection and returns the result. No subprocess spawned per call.
  4. Cleanup — on session_shutdown, gracefully shuts down the server (SIGTERM → SIGKILL after 2s).

Configuration

Variable Description
MCP_SERVER_CMD Command to run the MCP server (required)
MCP_SERVER_DIR Working directory for the server (optional)
MCP_SERVER_ARGS JSON array of extra CLI arguments (optional)

Features

  • Persistent connection — single subprocess for all tool calls (10x+ faster for warm calls vs. spawn-per-call)
  • Dynamic schemas — MCP inputSchema → TypeBox conversion gives the LLM proper parameter types for each tool
  • Concurrent requests — JSON-RPC ID-based promise matching handles overlapping tool calls
  • Graceful shutdown — protocol-level shutdown + SIGTERM + SIGKILL fallback
  • Timeout protection — per-request timeout (default 30s) prevents hanging on unresponsive servers
  • Stderr forwarding — server diagnostics are forwarded to pi's stderr

Development

git clone https://github.com/tmonk/pi-mcp-bridge
cd pi-mcp-bridge
npm install
npm test

The extension is a single index.ts file. Pi loads it via jiti — no build step.

Test

npm test            # 35 tests (unit + integration + e2e)
npm run test:watch  # watch mode
npm run test:coverage

License

MIT