Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nicobailon/pi-mcp-adapter/llms.txt

Use this file to discover all available pages before exploring further.

​
Prerequisites

Before installing Pi MCP Adapter, ensure you have:
  • Pi coding agent installed and running
  • Node.js 16+ (for npm-based MCP servers)
  • Basic familiarity with JSON configuration files
Pi MCP Adapter is a Pi extension and requires Pi to be installed first. Visit the Pi repository for installation instructions.

​
Install via Pi Package Manager

The easiest way to install Pi MCP Adapter is through Pi’s built-in package manager: 
pi install npm:pi-mcp-adapter
This command will:
  1. Download the latest version from npm
  2. Install it to ~/.pi/agent/extensions/pi-mcp-adapter/
  3. Add the extension to your ~/.pi/agent/settings.json
  4. Install required dependencies
Restart Required: After installation, you must restart Pi for the extension to load.

​
Restart Pi

After installation completes, restart Pi: 
# Exit your current Pi session
exit

# Start Pi again
pi
The MCP adapter will now be active in your Pi session.

​
Manual Installation

If you prefer to install manually or need to install from source:
1

Create the extension directory

mkdir -p ~/.pi/agent/extensions/pi-mcp-adapter
cd ~/.pi/agent/extensions/pi-mcp-adapter
2

Clone the repository

git clone https://github.com/nicobailon/pi-mcp-adapter.git .
3

Install dependencies

npm install --omit=dev
4

Update Pi settings

Add the extension path to ~/.pi/agent/settings.json:
settings.json
{
  "extensions": [
    "~/.pi/agent/extensions/pi-mcp-adapter/index.ts"
  ]
}
If you already have other extensions configured, add the path to the existing extensions array.
5

Restart Pi

Exit and restart Pi to load the extension.

​
Verify Installation

To verify that Pi MCP Adapter is installed correctly:
1

Check for the mcp tool

After restarting Pi, the mcp tool should be available. You can verify by running:
mcp({})
If no servers are configured yet, you’ll see:
MCP: 0/0 servers, 0 tools
2

Check for the /mcp command

The /mcp command should also be available:
/mcp
This will show the server status (or indicate no servers are configured).
No servers configured? That’s expected! Continue to the Quick Start guide to configure your first MCP server.

​
Package Contents

The Pi MCP Adapter installation includes:
FilePurpose
index.tsMain extension entry point
types.tsTypeScript type definitions
config.tsConfiguration loading and parsing
server-manager.tsMCP server connection management
tool-registrar.tsTool registration and transformation
lifecycle.tsServer lifecycle and idle timeout management
metadata-cache.tsTool metadata caching for offline access
oauth-handler.tsOAuth authentication flow
mcp-panel.tsInteractive management panel

​
Dependencies

Pi MCP Adapter automatically installs these dependencies:
  • @modelcontextprotocol/sdk - Official MCP SDK for client connections
  • @sinclair/typebox - Type validation for tool schemas
  • zod (peer dependency) - Schema validation used by Pi

​
Troubleshooting

  1. Check that the path in settings.json is correct: 
    cat ~/.pi/agent/settings.json
  2. Verify the extension files exist: 
    ls -la ~/.pi/agent/extensions/pi-mcp-adapter/
  3. Check for errors in Pi’s startup output
If npm install fails:
  1. Navigate to the extension directory: 
    cd ~/.pi/agent/extensions/pi-mcp-adapter
  2. Manually run npm install: 
    npm install --omit=dev
  3. Restart Pi
Make sure you have the latest version of Pi that supports the package manager. Update Pi:
# Follow Pi's update instructions
If pi install is not available, use the manual installation method instead.

​
Updating

To update Pi MCP Adapter to the latest version: 
pi install npm:pi-mcp-adapter
Then restart Pi. The installer will overwrite existing files with the latest version.
Your MCP server configurations in ~/.pi/agent/mcp.json are preserved during updates.

​
Uninstalling

To remove Pi MCP Adapter:
1

Remove the extension directory

rm -rf ~/.pi/agent/extensions/pi-mcp-adapter
2

Update settings.json

Remove the extension path from ~/.pi/agent/settings.json:
settings.json
{
  "extensions": [
    // Remove this line:
    // "~/.pi/agent/extensions/pi-mcp-adapter/index.ts"
  ]
}
3

Optional: Remove configuration

If you want to remove all MCP server configurations:
rm ~/.pi/agent/mcp.json
rm ~/.pi/agent/mcp-cache.json
4

Restart Pi

Exit and restart Pi to complete the uninstallation.

​
Next Steps

Now that Pi MCP Adapter is installed, continue to the Quick Start guide to:
  • Configure your first MCP server
  • Search and discover available tools
  • Make your first tool call through the proxy
  • Explore advanced configuration options

Build docs developers (and LLMs) love

Get started for freeTalk to us