pi-mcp-kit

MCP Gateway for Pi — stdio/SSE/Streamable HTTP transports, session recovery, connection pooling, structured error handling.

Packages

Package details

extension

Install pi-mcp-kit from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-mcp-kit
Package
pi-mcp-kit
Version
1.0.0
Published
Jul 31, 2026
Downloads
153/mo · 153/wk
Author
huanghui-dev
License
MIT
Types
extension
Size
137.2 KB
Dependencies
0 dependencies · 3 peers
Pi manifest JSON
{
  "extensions": [
    "./index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-mcp-kit

简体中文

Lightweight Model Context Protocol (MCP) gateway extension for Pi. Routes, pools, and lazy-loads configured local and remote MCP servers through a single proxy tool.

Features

  • Multi-transport protocol support: Supports stdio, SSE, and Streamable HTTP MCP transports.
  • Lazy client instantiation and pooling: Loads cached tool metadata without opening every server connection at startup.
  • Compact contextual discovery: Lets agents search cached capabilities on demand and call an exact returned tool name.
  • Structured JSON arguments: Accepts object arguments and forwards them to the selected MCP server for validation and execution.
  • Fail-loud tool routing: Requires exact tool names and explicit { server, tool } routing for ambiguous names.
  • Bounded transport and output budget: Enforces a 10 MiB transport message limit and spills oversized output to local temporary files.

Requirements

  • Node.js 20.0.0 or later
  • @earendil-works/pi-coding-agent, @earendil-works/pi-tui, and typebox
  • Configured local or remote MCP servers

Installation

pi install npm:pi-mcp-kit

Configuration

MCP server configurations are loaded from the following locations:

Path Description
~/.pi/agent/mcp.json Primary global MCP configuration.
~/.config/mcp/mcp.json Fallback global configuration when the primary file is absent.
.pi/mcp.json or .mcp.json Project configuration, only when local configuration is enabled and the workspace is trusted.
~/.cursor/mcp.json, ~/.claude/mcp.json, or Claude Desktop configuration Auto-discovered third-party configurations, subject to command, environment, and header checks.

The /mcp command manages connections and refreshes cached tools. Add or edit server definitions in the applicable configuration file.

Usage

In the Pi terminal interface:

  • /mcp: Open the interactive MCP connection control panel.
  • /mcp <serverName>: Toggle the connection state for a configured server.

Agents can discover and call MCP tools through the proxy mcp tool.

Security

Extension packages execute with the user's system privileges. Review source code before installing any extension.

This extension can spawn local subprocesses via stdio and connect to remote endpoints via SSE or Streamable HTTP. Configure only trusted commands and endpoints. Credentials in environment variables or headers are passed directly to the configured target servers.

Development

git clone https://codeberg.org/huanghui/pi-mcp-kit.git
cd pi-mcp-kit
npm ci
npm run check
npm test
npm pack --dry-run --json

Contributing

Issues and pull requests are welcome on Codeberg. Before submitting changes, ensure npm run check and npm test pass cleanly.

License

MIT