@ineersa/my-pi-mcp-adapter

MCP (Model Context Protocol) bridge for Pi coding agent. ToolSearch discovery · direct tools · lazy/eager/keep-alive lifecycle · TOON encoding · metadata cache.

⚠️ Requirement

This extension requires pi-mono from the refresh-tools-between-turns branch.

The setActiveTools API is not yet in pi-mono main. Without this branch, ToolSearch cannot activate discovered tools, and direct tool registration won't work correctly.

Why this fork?

This is a slimmed, enhanced fork of Nico Bailon's excellent pi-mcp-adapter. Here's what's different:

| Feature | Upstream (Nico) | This fork | |---|---|---| | Tool discovery | Single mcp mega-tool with JSON-in-JSON args | ToolSearch — search by keyword, load exact tools. Each MCP tool has its own typed schema. | | Token efficiency | ~200 tokens for proxy, but LLM must construct args-as-JSON | ~2000+ tokens saved per turn by only shipping active tool schemas | | Direct tools | directTools in config | Same, plus MCP_DIRECT_TOOLS env var for subagents | | TOON encoding | — | −27% token savings on JetBrains search results via TOON compression | | /mcp panel | Interactive TUI overlay | Text-based status (/mcp, /mcp tools, /mcp reconnect) | | OAuth flows | Full OAuth with callback server | needs-auth detection only — tool calls gracefully skipped | | MCP UI | Browser/Glimpse integration | Not included | | Tool activation | Proxy-based (all tools through one schema) | Individual tool registration — each MCP tool is a first-class Pi tool with its own typed schema |

The key architectural shift: Instead of a single mcp proxy tool with generic {tool?, args?, search?, connect?} schema, every MCP tool is registered individually with its full typed schema. ToolSearch gives the LLM keyword-based discovery, and only the tools it needs are active at any time. This saves thousands of tokens per turn while making tool calls type-safe.

Quick Start

Install

This package is part of the my-pi monorepo. Install via the one-command installer:

npx @ineersa/my-pi

Or install standalone:

pi install npm:@ineersa/my-pi-mcp-adapter

Configure a server

Create ~/.pi/agent/mcp.json:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "some-mcp-server"]
    }
  }
}

Reload & discover

/reload

Then ask your agent:

"Search for available MCP tools related to files"

The agent calls ToolSearch({ query: "files" }), discovers matching tools, and uses them with full typed schemas on the next turn.

Features at a glance

| Feature | Description | More | |---|---|---| | 🔍 ToolSearch | Search & load MCP tools by keyword. ~2000+ tokens saved per turn. | Examples → | | ⚡ Direct tools | Frequently-used tools active from turn 1. Config + env var. | Examples → | | 😴 Lazy startup | Servers connect on first tool call. No startup delay. | Examples → | | 🔄 Lifecycle modes | lazy, eager, keep-alive per-server. | Examples → | | ⏱️ Idle timeout | Auto-disconnect inactive servers. Configurable per-server. | Examples → | | 📦 Metadata cache | Tool schemas cached to disk. Register tools without live connections. 7-day TTL. | Examples → | | 🚀 npx binary resolution | Bypasses ~143MB npm parent process. Direct binary invocation. | Examples → | | 🗜️ TOON encoding | JSON→TOON compression. −27% tokens on JetBrains results. | Examples → | | 📊 Call statistics | Per-server/per-tool counters. Find your most-used tools. | Examples → | | 📥 Config imports | Import MCP servers from Cursor, Claude, Codex, Windsurf, VS Code. | Examples → | | 📁 Project-local config | .pi/mcp.json overrides user-global ~/.pi/agent/mcp.json. | Examples → | | 📖 Resource tools | MCP resources exposed as callable Pi tools. | Examples → | | ⏳ Failure backoff | 60s cooldown after failed connections. | Examples → | | 🔐 Bearer auth | Env var or static token. OAuth servers gracefully skipped. | Examples → | | 🛡️ Collision guard | Tools shadowing builtins silently skipped. | Examples → | | 🔀 Cross-server dedup | Handles name collisions in prefix: "none" / "short" modes. | Examples → | | 📡 Status bar | Connected/total server count in Pi footer. | Examples → |

Configuration Reference

File locations

| Priority | File | Scope | |---|---|---| | 1 (highest) | .pi/mcp.json | Project-local overrides | | 2 | Imported configs | From other tools | | 3 (base) | ~/.pi/agent/mcp.json | User global |

Per-server fields

| Field | Type | Default | Description | |---|---|---|---| | enabled | boolean | true | Disable without removing from config | | command | string | — | Executable for stdio transport | | args | string[] | [] | Command arguments | | env | object | — | Environment variables (${VAR} supported) | | cwd | string | — | Working directory | | url | string | — | HTTP endpoint (StreamableHTTP/SSE) | | headers | object | — | HTTP headers (${VAR} supported) | | auth | "bearer" or false | — | Authentication type | | bearerToken | string | — | Static bearer token | | bearerTokenEnv | string | — | Env var name for bearer token | | lifecycle | "lazy" / "eager" / "keep-alive" | "lazy" | Connection lifecycle mode | | idleTimeout | number | global default | Minutes before idle disconnect | | startupTimeoutMs | number | 30000 | Connection timeout at startup | | exposeResources | boolean | true | Expose MCP resources as callable tools | | directTools | boolean or string[] | false | Make specific tools always active | | excludeTools | string[] | — | Hide specific tools from LLM | | debug | boolean | false | Show server stderr |

Global settings

| Field | Type | Default | Description | |---|---|---|---| | toolPrefix | "server" / "short" / "none" | "server" | Tool name prefix style | | idleTimeout | number | 10 | Global idle timeout in minutes | | toonEncode | boolean or string[] | — | Enable TOON encoding (true = all, array = specific servers) | | captureStats | boolean or object | — | Enable call statistics |

Commands

| Command | Description | |---|---| | /mcp or /mcp status | Show server connection status | | /mcp tools | List all available tool names | | /mcp reconnect | Reconnect all enabled servers | | /mcp reconnect <server> | Reconnect a specific server |

Environment variables

| Variable | Description | |---|---| | MCP_DIRECT_TOOLS | Comma-separated server/tool specifiers. * = all servers, server_name = all tools from that server, server/tool = specific tool, __none__ = no direct tools | | MCP_UI_DEBUG=1 | Enable debug logging |

Architecture

┌─────────────────────────────────────────────────────────┐
│                     Pi Agent                              │
│  ┌──────────┐  ┌──────────────┐  ┌──────────────────┐   │
│  │ Builtins │  │  ToolSearch  │  │  Direct MCP       │   │
│  │ (active) │  │  (active)    │  │  Tools (active)   │   │
│  └──────────┘  └──────┬───────┘  └──────────────────┘   │
│                       │                                  │
│                       │ discover ▼                       │
│               ┌───────▼────────┐                         │
│               │ Deferred MCP   │  Inactive until         │
│               │ Tools          │  discovered via         │
│               │                │  ToolSearch             │
│               └────────────────┘                         │
└──────────────────────┬──────────────────────────────────┘
                       │
          pi-mcp-adapter layer
                       │
   ┌───────────────────┼───────────────────┐
   │ lifecycle manager │ metadata cache    │
   │ health checks     │ ~/.pi/agent/      │
   │ idle timeout      │ mcp-cache.json    │
   └───────────────────┼───────────────────┘
                       │
             ┌─────────┼──────────┐
             │ stdio   │ HTTP      │ SSE
             ▼         ▼           ▼
          MCP Svr   MCP Svr     MCP Svr

Documentation

| Document | Content | |---|---| | examples.md | All 17 examples with JSON configs and usage patterns | | architecture.md | Full technical architecture — module map, lifecycle, data flow, transport layer | | settings.md | Detailed settings reference | | usage.md | Usage overview | | maintenance.md | Module map, key events, tool registration flow | | CHANGELOG.md | Version history |

License

MIT © 2026 Nico Bailon (original) · Ineersa (fork additions: ToolSearch, TOON encoding, direct tool activation)

This project is a fork of pi-mcp-adapter by Nico Bailon, modified and maintained as part of the my-pi monorepo. All original copyright and permission notices are preserved. See LICENSE for the full text.

The following components are new in this fork:

• ToolSearch — keyword-based tool discovery replacing the mcp proxy mega-tool
• TOON encoding — JSON→TOON compression for token-efficient MCP responses
• Tool activation via pi.setActiveTools() (requires pi-mono refresh-tools-between-turns)
• Slimmed scope: no OAuth flows, no MCP UI panel, text-based /mcp commands only