pi-mcp-adapter: Lazy MCP Servers & Token Costs

Overview

Pi can use MCP servers through this extension. The adapter exposes discovery and invocation through an mcp tool, instead of advertising every server tool schema at the start.

Use proxy discovery when you have many rarely used tools. Promote a small set of frequent tools with directTools when an extra discovery call costs more than their schema overhead.

What “about 200 tokens” measures

The README estimates about 200 tokens for the compact proxy tool definition. This project did not benchmark that number, and it is not an upper bound on a full session or today’s optional tool surface.

Search results and tool descriptions still enter the conversation when requested. Arguments, outputs and selected direct schemas add tokens too. Compare the same task and enabled tools with your model’s usage reporting; more direct tools can erode the initial saving.

A working configuration shape

After installation and restart, create a project .mcp.json using the mcpServers object shown below. This is the upstream Chrome DevTools example with explicit lazy lifecycle. It needs Node/npx and the MCP server’s browser prerequisites; the pinned server version is an example, not a recommendation of the latest release.

Shared global configuration lives in ~/.config/mcp/mcp.json. Pi-owned overrides use ~/.pi/agent/mcp.json and .pi/mcp.json. Host-specific configs are not silently adopted by default; /mcp setup can review and import them.

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@1.6.0"],
      "lifecycle": "lazy",
      "directTools": false
    }
  }
}

Lazy startup and cache behavior

Lazy is the default: a configured server need not run merely because Pi started. Tool metadata is cached in ~/.pi/agent/mcp-cache.json (or the configured Pi agent directory), so later search/list/describe operations can use cached definitions.

A new server has no metadata yet. Connect it once to discover tools; direct-tool registration can then load from cache and refresh when the live catalog changes. A cached definition is not a successful health check. /mcp reconnect <server> refreshes live state.

Choose direct tools deliberately

Per-server directTools: true exposes every tool schema; an array exposes only named original MCP tools; false keeps proxy-only access. directTools: "search" registers tools inactive and activates matches after mcp search.

Start with proxy-only, discover actual tool names, then add only frequent tools. Direct mode does not bypass server startup, authentication or approval. Enabling many schemas trades away the context benefit that motivated the proxy.

Verify discovery, then a read-only call

Open /mcp to inspect configuration, then request the two calls below in Pi. Connecting can start the configured local process; it populates metadata for the subsequent search. Select a read-only tool from the returned schema and provide its actual required arguments.

Confirm the server, schema and real tool result separately. If only discovery succeeds, cached metadata may be hiding an unavailable server. Authentication and service setup still belong to that server. This guide reviewed source/configuration without starting third-party MCP services.

mcp({ connect: "chrome-devtools" })
mcp({ search: "list pages" })

When a native extension is enough

If the only requirement is web search and page extraction, pi-web-access can provide native Pi tools without configuring MCP servers. Use the adapter when an existing MCP server supplies capabilities you need across databases, browsers or other services.