pi-local-mcp-adapter

Lightweight Pi extension that connects Pi to local MCP servers, since I felt that pi-mcp-adapter is too overkill for my own setup.

The adapter depends on @modelcontextprotocol/sdk for the core functionalities.

Setup

# Drop into Pi's extensions directory
git clone <this-repo> ~/.pi/agent/extensions/pi-local-mcp-adapter
cd ~/.pi/agent/extensions/pi-local-mcp-adapter
npm install

Configure your servers in ~/.pi/agent/mcp.json, then restart Pi.

Config

~/.pi/agent/mcp.json:

{
  "mcpServers": {
    "context-mode": {
      "command": "node",
      "args": ["/path/to/context-mode/start.mjs"],
      "lifecycle": "lazy"
    },
    "codebase-memory": {
      "command": "/path/to/codebase-memory-mcp",
      "lifecycle": "lazy"
    }
    // And so on...
  }
}

Server fields

| Field | Type | Default | Description | | ----------- | ------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------ | | command | string | required | Executable to run | | args | string[] | [] | Command arguments | | env | Record<string, string> | {} | Environment variables. Supports ${VAR} interpolation from process.env | | cwd | string | inherited | Working directory for the server process | | lifecycle | "lazy" \| "eager" | "lazy" | eager — connect on session start, stay connected. lazy — discover tools on start, disconnect, reconnect on first tool call | | enabled | boolean | true | Set to false to skip a server without removing its config |

Entries without a command field are ignored. Unknown fields are ignored.

Commands

Auto-suggestion hasn't been implemented yet.

| Command | Description | | ------------------------------- | ------------------------------------------------------------------ | | /local-mcp | Show server status — connected/disconnected, tool count, lifecycle | | /local-mcp reconnect | Reconnect all servers | | /local-mcp reconnect <server> | Reconnect a specific server |

How it works

On session_start, the extension reads mcp.json and connects to each enabled server over stdio. It calls tools/list to discover available tools and registers each one as a Pi tool via pi.registerTool() - no proxy, no gateway, every tool appears directly alongside read, bash, edit, etc.

Eager servers stay connected for the entire session.
Lazy servers disconnect after tool discovery and reconnect transparently on the first tool call.
On session_shutdown, all server processes are closed gracefully.
If a server process dies, the _connected flag is updated via the SDK's onclose callback. The next tool call returns a clear error — use /local-mcp reconnect to restore it.
If two servers expose a tool with the same name, the first server wins and a warning is logged.

MCP Servers