pi-mcp

Pi extension for connecting MCP (Model Context Protocol) HTTP servers

Features

• Connect to MCP servers via HTTP/SSE or Streamable HTTP
• Auto-discover tools available on servers
• Register MCP tools as native Pi tools
• Manage connections via slash commands
• Persistent configuration across sessions
• Global and per-project server configurations

Installation

Via npm (recommended)

npm install -g @eliemessiecode/pi-mcp

Via bun

bun install -g @eliemessiecode/pi-mcp

Via Pi

pi install npm:@eliemessiecode/pi-mcp

Via Git

pi install git:github.com/ElieMessieCode/pi-mcp

Manual

Copy the pi-mcp folder to:

• ~/.pi/agent/extensions/pi-mcp/ (global - all projects)
• .pi/extensions/pi-mcp/ (project-local)

Usage

Commands

Command	Description
/mcp add <name> <url> [options]	Add server (options: --global, --project, --insecure, --timeout)
/mcp remove <name>	Remove a server
/mcp list	List configured servers (grouped by scope)
/mcp connect [name]	Connect to server(s) - all if no name
/mcp disconnect [name]	Disconnect from server(s) - all if no name
/mcp tools [name]	List available tools
/mcp resources [name]	List available resources
/mcp prompts [name]	List available prompts
/mcp status	Show connection status
/mcp refresh [name]	Refresh tool list
/mcp scopes	Show config file paths
/mcp move <name> --global|--project	Move server between scopes
/mcp export [file]	Export servers to JSON
/mcp import <file>	Import servers from JSON
/mcp-status	Quick status overview
/mcp-logs	View debug logs
/mcp-logs clear	Clear debug logs

Examples

Add an MCP server (global):

/mcp add my-server https://my-mcp-server.com/mcp

Add a server for current project only:

/mcp add unity http://localhost:53559 --project

Add server with authentication:

/mcp add github https://api.github.com/mcp Authorization=Bearer ghp_xxx

Connect to all servers:

/mcp connect

Use an MCP tool (auto-registered):

Tools are automatically registered with the prefix: mcp_<server-name>_<tool-name>

Supported Protocols

• Streamable HTTP (recommended): JSON-RPC with SSE support
• SSE: Server-Sent Events for notifications
• Simple HTTP: Request-response JSON-RPC

Supported Data Types

MCP tools are automatically converted to Pi tools with:

• JSON Schema to TypeBox parameter conversion
• Supported types: string, number, integer, boolean, array, object
• Automatic description and documentation

Configuration Scopes

Scope	Path	Usage
Global	~/.pi/agent/mcp/servers.json	Shared across all projects
Project	.pi/mcp/servers.json	Specific to current project

Servers auto-connect on Pi startup.

Project Structure

pi-mcp/
├── index.ts           # Main extension
├── package.json       # Package metadata
├── README.md          # This documentation
├── LICENSE            # MIT license
├── CHANGELOG.md       # Version history
└── CONTRIBUTING.md    # Contribution guidelines

Compatible MCP Server Example

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

const server = new McpServer({
  name: "example-server",
  version: "1.0.0",
});

server.tool("get_weather", 
  { city: { type: "string", description: "City name" } },
  async ({ city }) => ({
    content: [{ type: "text", text: `Weather in ${city}: Sunny, 22C` }]
  })
);

server.start(3000);

Troubleshooting

Connection failed:

• Verify the URL is accessible
• Check authentication headers
• Use /mcp status to see errors

Tools not detected:

• Use /mcp refresh <name> to refresh
• Verify the server implements tools/list
• Check Docker logs if using Docker: docker logs <container-name>

Request timeout:

• Default timeout: 30 seconds
• Check network latency

Pi shows 0 tools:

• Ensure Unity Editor is running (for Unity MCP)
• Check the MCP plugin is connected in Unity
• View logs: /mcp-logs

Roadmap

High Priority

• Auto-reconnect when server drops
• Periodic health check for server connections
• Tool cleanup when server disconnects

Medium Priority

• MCP Resources support (/mcp resources)
• MCP Prompts support (/mcp prompts)
• TLS/SSL skip option (--insecure)
• Configurable timeout per server (--timeout <ms>)
• Move server between scopes (/mcp move <name> --global|--project)
• Export/Import server configuration

Low Priority

• Server groups (/mcp group add <name> <server1> <server2>)
• Tool filters (/mcp add x --filter="assets-*")
• Connection history
• Usage metrics
• Custom tool templates

Known Bugs

• Handle special characters in URLs
• More explicit timeout error messages
• Support Basic authentication

Contributing

Contributions are welcome!

1. Fork the repo
2. Create a branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT - see LICENSE for details

---

What's New in v1.2.0

• Auto-reconnect when server drops (up to 3 attempts)
• Periodic health check for server connections (30s interval)
• Automatic tool cleanup when server disconnects
• MCP Resources support
• MCP Prompts support
• TLS/SSL skip option (--insecure)
• Configurable timeout per server (--timeout <ms>)
• Move server between scopes (/mcp move)
• Export/Import server configuration

---

Repository: github.com/ElieMessieCode/pi-mcp