@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