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

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

Medium Priority

• [x] MCP Resources support (/mcp resources)
• [x] MCP Prompts support (/mcp prompts)
• [x] TLS/SSL skip option (--insecure)
• [x] Configurable timeout per server (--timeout <ms>)
• [x] Move server between scopes (/mcp move <name> --global|--project)
• [x] 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