Pi MCP Adapter

TLH fork note: this fork is maintained for The Last Harness (tlh), where tlh automation bundles and pins it for compatibility. It is not intended as a general standalone distribution target outside that TLH use.

Requires Node.js 22.23.4+ (22.x), 24.22.1+ (24.x), or 26.12.1+ (26.x). Other release lines and prereleases are unsupported. HTTP transports, endpoint probes, OAuth, and provider requests fail closed on older runtimes, even if npm ignores engines. See runtime security and custom trust.

Use MCP servers with Pi without burning your context window.

https://github.com/user-attachments/assets/4b7c66ff-e27e-4639-b195-22c3db406a5a

Why This Exists

Mario wrote about why you might not need MCP. The problem: tool definitions are verbose. A single MCP server can burn 10k+ tokens, and you're paying that cost whether you use those tools or not. Connect a few servers and you've burned half your context window before the conversation starts.

His take: skip MCP entirely, write simple CLI tools instead.

But the MCP ecosystem has useful stuff - databases, browsers, APIs. This adapter gives you access without the bloat. One proxy tool (~200 tokens) instead of hundreds. The agent discovers what it needs on-demand. Servers only start when you actually use them.

pi-mcp-adapter vs Pi's built-in MCP

Since then, Pi 0.99 added MCP support of its own, which also keeps tool definitions out of context. Installing the adapter replaces it in Pi sessions. What you get by switching:

• Install many servers without paying for idle ones. The built-in starts every enabled server in every Pi session and keeps it running until the session ends. By default, the adapter starts a server when the model first calls it and stops it after 10 idle minutes.
• Fewer tokens on everyday calls. By default, the built-in runs every MCP call as a codemode script, even a single lookup. The adapter's scripts are off by default, so a lookup is one small JSON call to the mcp tool, which cost 10–33% less in our tests. For bulk work across many records, turn scripts on with settings.scriptMode; then it costs about the same as codemode.
• More servers work fully. Servers can ask you questions through forms, show interactive UIs, and offer prompt templates as slash commands. The built-in doesn't handle these.
• Predictable tool search. The adapter searches tool names and descriptions by words and supports explicit regular-expression searches.
• Sign-in tokens go in your OS keychain by default (an encrypted file is opt-in), not in a plain JSON file under ~/.pi/agent.
• Adding servers is easier. Add definitions to a config file or use /mcp-adapter setup, which previews writes before changing files. Servers already configured in Cursor, Claude Code, Codex, or VS Code can be imported with setup, which also adds presets such as Figma and GitHub.

The built-in has two things the adapter doesn't: Pi's permission extensions see each MCP call as its own tool call without changes, and it sends roots (the session directory) to servers. Pi's codemode works with both.

Over a session, measured with 100 small local servers:

Stopping a server doesn't take its tools away: the model can still search them, and a stopped server starts again on its next call (0.1–0.3 s for a small local server). For a server that must keep state between calls, set "lifecycle": "lazy-keep-alive". The first session briefly starts new servers, 10 at a time, to read their tool lists. Measurements and details.

The full comparison has every row with sources, as of Pi 0.99.2.

While the built-in is turned on, Pi may warn at startup and /reload that it was not loaded. The adapter does not modify Pi's user or project settings; disable the built-in explicitly in pi config when both extensions are installed. If you remove the adapter, turn the built-in back on there (details).

Install

pi install npm:@diegopetrucci/[email protected]

TLH automation should use this exact pinned install target. The upstream v5.0.0 tag is only the intake anchor; the fork-owned package identity and version are @diegopetrucci/[email protected] for bundled tlh integration. Version 5.2.0 is a fork-only minor release (5.1.0 plus #28); its tag and publication evidence are pending. Version 5.1.0 was a fork-only minor release (5.0.2 plus #25); its release evidence: Release-prep PR #26 was squash-merged as 10c0d731ff60e39b50b07c6bf2b322dfe0013a05 and ships #25. Annotated tag tlh-v5.1.0 object 8304d47e405627bac23570096eaa492c7a90881e targets that commit, and the GitHub release was latest at 5.1.0 publication. @diegopetrucci/[email protected] was published through trusted OIDC workflow run 42839376068 dispatched from main with input ref=tlh-v5.1.0, so registry provenance records workflow ref refs/heads/main and commit 10c0d73 (the tag target) rather than the tag ref; the Sigstore transparency log index is 3788141669. npm dist-tag latest was 5.1.0 at publication; the package has 235 files, integrity sha512-VDjhbUaQTLRtTgNtQOQ8VKj2GnP5nyA4OMTi8nQH25Fm0eODu+p73paHxFFdPPbKINj4V3XqQIOyGOiGpB/LJQ==, and engines ^22.23.4 || ^24.22.1 || ^26.12.1; gitHead is 10c0d73, and the registry provenance payload subject digest matches the integrity. Independent cryptographic signature verification, live-provider E2E, and fresh audits are not claimed. Version 5.0.2 was a fork-only patch (5.0.1 plus #22); its release evidence: Release-prep PR #23 was squash-merged as 069f061a3623dd9699e5a7dc8f0169360ecc495f and ships #22. Annotated tag tlh-v5.0.2 object 1e96356e9915fdb24ee2fe3f906959ca48116d80 targets that commit, and the GitHub release was latest at 5.0.2 publication. @diegopetrucci/[email protected] was published through trusted OIDC workflow run 39818321525 dispatched from main with input ref=tlh-v5.0.2, so registry provenance records workflow ref refs/heads/main and commit 069f061 (the tag target) rather than the tag ref; the Sigstore transparency log index is 3394249318. npm dist-tag latest was 5.0.2 at publication; the package has 231 files, integrity sha512-Z+S4grugsBND4g216tOMvpAcOBp0fpD8mt40pvWvM5DUqiFMoUFWtJWoFvzKCfQL7UueF+eCuLWnwsD6ahBUuA==, and engines ^22.23.4 || ^24.22.1 || ^26.12.1; gitHead is 069f061, and the registry provenance payload subject digest matches the integrity. Independent cryptographic signature verification, live-provider E2E, and fresh audits are not claimed. Version 5.0.1 was a fork-only patch on top of the upstream v5.0.0 intake; Release-prep PR #20 was squash-merged as f0d5d4efa884d1c6c84b301f8925beee94a54330 and ships #19. Annotated tag tlh-v5.0.1 object 9ec4f3c928fc7b898de762e4b0942a997b90b5d7 targets that commit, and the GitHub release was latest at 5.0.1 publication. @diegopetrucci/[email protected] was published through trusted OIDC workflow run 39778515390 dispatched from main with input ref=tlh-v5.0.1, so registry provenance records workflow ref refs/heads/main and commit f0d5d4e (the tag target) rather than the tag ref. npm dist-tag latest was 5.0.1 at publication; the package has 230 files, integrity sha512-yN1cFPst5nbgm88WxZ+s8AlKcEwJvoC9RshK/6tgQxBjdckTSglS/DASa3k3xLMyB/W8qUG1Fkz0LNGFnC2rbw==, and engines ^22.23.4 || ^24.22.1 || ^26.12.1; the registry provenance payload subject digest matches the integrity. Independent cryptographic signature verification, live-provider E2E, and fresh audits are not claimed. The v5.0.0 intake release was integrated through PR #17 at merge a305e43e0abac015e6aeb988b15f1bba23f62e46, published through OIDC workflow run 37613129066, and released as tlh-v5.0.0.

Maintainer note: upstream intake policy for this fork lives in docs/UPSTREAM-SYNC.md, with fork-only delta tracking in docs/tlh-patch-inventory.md.

Restart Pi after installation.

DeepSeek Harness (third-party bridge): Run the unmodified adapter in DSH via pi2dsh; see the verified dsh-TUI and Web MCP guide.

What happens on first run

The adapter reads standard MCP files automatically. No extra setup needed if you already have them.

If you prefer the terminal, you can also run pi-mcp-adapter init after install to scan for host-specific configs and add missing compatibility imports to the adapter config (~/.pi/agent/mcp-adapter.json by default, or $PI_CODING_AGENT_DIR/mcp-adapter.json when set).

Quick Start

Add a server to .mcp.json in your project:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

Servers are lazy by default — they won't connect until you actually call one of their tools. The adapter caches tool metadata so search and describe work without live connections.

mcp({ search: "screenshot" })

chrome_devtools_take_screenshot
  Take a screenshot of the page or element.

  Parameters:
    format (enum: "png", "jpeg", "webp") [default: "png"]
    fullPage (boolean) - Full page instead of viewport

mcp({ tool: "chrome_devtools_take_screenshot", args: { format: "png" } })

Two calls instead of 26 tools cluttering the context.

Common tasks

Commands

If settings.autoAuth is true, mcp({ connect: ... }), mcp({ tool: ... }), and direct tool calls automatically run OAuth when needed and retry once.

In interactive sessions, you can also authenticate from /mcp-adapter with ctrl+a or Enter on a server that needs auth. /mcp-auth without a server only opens a picker in the interactive UI. For gateway authorization and manual callback completion, see Remote/headless authentication.

On Pi 0.99 and later, servers you already signed in to with Pi's built-in MCP can reuse that sign-in: the adapter asks once per server, and /mcp-adapter offers ctrl+p to import them. See Import a sign-in from Pi's built-in MCP.

How It Works

• One mcp tool in context (~200 tokens) instead of hundreds
• Servers are lazy by default — they connect on first tool call, not at startup
• Tool metadata is cached to disk so search/list/describe work without live connections
• Idle servers disconnect after 10 minutes (configurable), reconnect automatically on next use
• npx-based servers resolve to direct binary paths, skipping the ~143 MB npm parent process
• MCP server validates arguments, not the adapter
• Remote keep-alive servers force-refresh their tool catalog during health checks, before user input, and before adapter-triggered turns, with bounded reconnect backoff
• Specific tools can be promoted from the proxy to first-class Pi tools via directTools config, so the LLM sees them directly instead of having to search

Limitations

• Each Pi session runs its own server processes; rmcp-mux can share one across sessions
• Compact MCP result rendering summarizes text, but inline images are still controlled by Pi's image display settings and may render below the compact text summary.
• Pi still owns one separator row before self-rendered tool output, so compact mode reduces adapter rendering height but cannot promise true zero-gap rows.
• MCP sampling support is text-only; context inclusion, tools, stop sequences, audio, and image content are rejected with explicit errors.
• MCP UI apps are off by default: the adapter does not advertise the io.modelcontextprotocol/ui capability and ui:// tools return ordinary inline results. Set MCP_UI_VIEWER to auto (previously the default), browser, glimpse, or orca to open tool UIs; none, off, disabled, and unknown values keep UI off (MCP UI integration).

Documentation

The full reference lives in docs/: