pi -adapter

The Pi MCP Adapter lets you access MCP servers through the Pi environment without bloating your context window. It acts as a proxy so you can discover and call MCP tools on demand, while the actual servers are started lazily only when you use a tool. This keeps your conversations compact and lets Pi’s agent search, describe, and call tools efficiently. The adapter exposes a single proxy tool by default, and it caches metadata so you can search and describe tools even before any server is actively connected. You can still opt into direct tools on a per-server basis if you want a shorter tool list in the agent’s UI.

To use it, install the Pi MCP Adapter package, configure your MCP server entry, and then use the mcp function to search, describe, or call tools. For example, you can search for a tool like “screenshot” or describe a specific tool to understand its parameters. When you call a tool, the adapter will lazily start the corresponding MCP server (if not already running) and execute the request, returning the result. This provides a lean workflow where only the needed tools consume tokens and resources.

Prerequisites:

• A Pi environment with internet access (Pi OS or compatible).
• Node.js available on the Pi (required for npx-based server execution).

Installation steps:

1. Install the Pi MCP Adapter via Pi’s package manager:

pi install npm:pi-mcp-adapter

2. Restart Pi to ensure the adapter is loaded:

sudo reboot

3. Create or update your MCP configuration at ~/.pi/agent/mcp.json to point at the adapter:

{
  "mcpServers": {
    "pi-mcp-adapter": {
      "command": "npx",
      "args": ["-y", "pi-mcp-adapter"],
      "lifecycle": "lazy",
      "idleTimeout": 10
    }
  }
}

4. (Optional) If you want direct tools for a server, adjust per-server settings as described in the README (directTools, etc.).

Notes and tips:

• Servers are lazy by default; they connect when you first call a tool, then may disconnect after idle timeout. Metadata is cached to keep search/describe functional even when servers are not connected.
• You can keep the proxy tool as the default experience or enable per-server direct tools for a smaller, targeted tool set.
• If you need to force tool availability without a live connection, you can run /mcp reconnect <server> in the Pi overlay and restart the service.
• The example configuration uses npx to resolve and execute the MCP server on demand, avoiding large startup costs.
• Ensure your environment variables (env) and working directories (cwd) are correctly set if your MCP servers require them.