Quick Start

Create Your Configuration File

After installing Pi MCP Adapter, create a configuration file at ~/.pi/agent/mcp.json:

touch ~/.pi/agent/mcp.json

Open the file in your favorite editor and add your first MCP server:

~/.pi/agent/mcp.json

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

Lazy by default: Servers won’t connect until you actually call one of their tools. The adapter caches tool metadata so search and describe work without live connections.

Discover Available Tools

Now restart Pi and search for available tools:

mcp({ search: "screenshot" })

You’ll see matching tools with their descriptions:

chrome_devtools_take_screenshot
  Take a screenshot of the page or element.

  Parameters:
    format (enum: "png", "jpeg", "webp") [default: "png"]
    fullPage (boolean) - Full page instead of viewport

Call Your First Tool

Call the tool using the proxy:

mcp({ tool: "chrome_devtools_take_screenshot", args: '{"format": "png"}' })

Arguments are JSON strings: The args parameter must be a JSON string, not a JavaScript object. Always use single quotes around the JSON and double quotes inside:

# Correct
args: '{"format": "png"}'

# Wrong
args: {"format": "png"}

The server will connect automatically on first use, execute the tool, and return the result.

Explore the MCP Tool

The mcp tool supports multiple modes:

Status - View all servers

mcp({})

Shows connection status and tool counts for all configured servers:

MCP: 1/1 servers, 26 tools

✓ chrome-devtools (26 tools)

mcp({ server: "name" }) to list tools, mcp({ search: "..." }) to search

List - Show all tools from a server

mcp({ server: "chrome-devtools" })

Lists all available tools from the specified server:

chrome-devtools (26 tools):

- chrome_devtools_navigate - Navigate to a URL
- chrome_devtools_take_screenshot - Take a screenshot
- chrome_devtools_click - Click an element
...

Search - Find tools by keyword

mcp({ search: "screenshot navigate" })

Searches across all tools using OR logic (space-separated words):

Found 3 tools matching "screenshot navigate":

chrome_devtools_take_screenshot
  Take a screenshot of the page or element.
  
  Parameters:
    format (enum: "png", "jpeg", "webp") [default: "png"]
    fullPage (boolean) - Full page instead of viewport

chrome_devtools_navigate
  Navigate to a URL.
  
  Parameters:
    url (string) *required*

Use includeSchemas: false to get compact results without parameter details:

mcp({ search: "screenshot", includeSchemas: false })

Describe - View tool parameters

mcp({ describe: "chrome_devtools_take_screenshot" })

Shows detailed information about a specific tool:

chrome_devtools_take_screenshot
Server: chrome-devtools

Take a screenshot of the page or element.

Parameters:
  format (enum: "png", "jpeg", "webp") [default: "png"]
  fullPage (boolean) - Full page instead of viewport

Call - Execute a tool

mcp({ tool: "chrome_devtools_take_screenshot", args: '{"format": "png", "fullPage": true}' })

Calls the tool with the provided arguments and returns the result.You can optionally specify the server to disambiguate:

mcp({ tool: "some_tool", args: '{}', server: "chrome-devtools" })

Connect - Force server connection

mcp({ connect: "chrome-devtools" })

Manually connects to a server and refreshes its metadata cache. Useful for:

Forcing immediate connection instead of waiting for first tool call
Refreshing metadata after server updates
Troubleshooting connection issues

Add More Servers

Expand your configuration to include multiple servers:

~/.pi/agent/mcp.json

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
    }
  }
}

Environment variable interpolation: Use ${VAR_NAME} syntax to reference environment variables from your shell. Pi MCP Adapter will automatically expand them.

Restart Pi and all servers will be available:

mcp({})

MCP: 0/3 servers, 75 tools

○ chrome-devtools (26 tools, cached)
○ github (32 tools, cached)
○ filesystem (17 tools, cached)

mcp({ server: "name" }) to list tools, mcp({ search: "..." }) to search

Servers show as cached because they haven’t connected yet. They’ll connect automatically when you use their tools.

Interactive Management Panel

Pi MCP Adapter includes an interactive management panel. Run:

/mcp

This opens a UI overlay showing:

Server connection status
Available tools per server
Direct vs. proxy tool configuration
Quick actions (reconnect, OAuth setup)

You can toggle tools between direct and proxy registration and the changes will be written to your config file.

Use /mcp reconnect to reconnect all servers or /mcp reconnect <server-name> for a specific server.

Import Existing Configurations

If you already have MCP servers configured in other tools, import them:

~/.pi/agent/mcp.json

{
  "imports": ["cursor", "claude-desktop"],
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

Supported import sources:

cursor - Cursor IDE
claude-code - Claude Code
claude-desktop - Claude Desktop app
vscode - Visual Studio Code
windsurf - Windsurf
codex - Codex

Servers defined in mcpServers override imported configurations.

Use Direct Tool Registration

By default, all tools are accessed through the mcp proxy. For frequently-used tools, you can register them directly so the LLM sees them alongside Pi’s built-in tools:

~/.pi/agent/mcp.json

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      },
      "directTools": ["search_repositories", "get_file_contents"]
    }
  }
}

Now search_repositories and get_file_contents appear as first-class tools. The LLM can call them directly without searching.

mcp({ search: "search repo" })
mcp({ tool: "github_search_repositories", args: '{...}' })

Context cost: Each direct tool adds ~150-300 tokens to your system prompt. Good for targeted sets of 5-20 tools. For servers with 75+ tools, stick with the proxy.

You can also register all tools from a server:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"],
      "directTools": true
    }
  }
}

Project-Specific Configuration

Add a .pi/mcp.json file in any project root for project-specific servers:

project-root/.pi/mcp.json

{
  "mcpServers": {
    "project-database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://localhost/myproject"
      }
    }
  }
}

Project configs override global configs when Pi is run from that directory.

Understanding Lifecycle Modes

Pi MCP Adapter supports three lifecycle modes:

Lazy (default)

Don’t connect at startup
Connect on first tool call
Disconnect after idle timeout
Cached metadata keeps search working

Best for: Most servers, especially resource-intensive ones

Eager

Connect at startup
Don’t auto-reconnect if dropped
No idle timeout by default

Best for: Servers you use frequently in a session

Keep-Alive

Connect at startup
Auto-reconnect via health checks
No idle timeout

Best for: Critical servers that must always be available

Example configuration:

~/.pi/agent/mcp.json

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"],
      "lifecycle": "lazy",
      "idleTimeout": 10
    },
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "lifecycle": "keep-alive",
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Next Steps

Configuration Guide

Learn about all available configuration options, transport modes, authentication, and advanced settings

Available Commands

Explore all /mcp commands for managing servers, viewing tools, and handling OAuth

Lifecycle Management

Deep dive into server lifecycle modes, idle timeouts, and connection management

Troubleshooting

Common issues and solutions for server connections, tool calls, and configuration

Pro tip: Start with lazy lifecycle and proxy-only tools. Add direct tools and change lifecycle modes as you identify your usage patterns.

Get Started

Core Concepts

Configuration

Usage

Advanced

Create Your Configuration File

Discover Available Tools

Call Your First Tool

Explore the MCP Tool

Add More Servers

Interactive Management Panel

Import Existing Configurations

Use Direct Tool Registration

Project-Specific Configuration

Understanding Lifecycle Modes

Lazy (default)

Eager

Keep-Alive

Next Steps

Configuration Guide

Available Commands

Lifecycle Management

Troubleshooting

Get Started

Core Concepts

Configuration

Usage

Advanced

Documentation Index

​Create Your Configuration File

​Discover Available Tools

​Call Your First Tool

​Explore the MCP Tool

​Add More Servers

​Interactive Management Panel

​Import Existing Configurations

​Use Direct Tool Registration

​Project-Specific Configuration

​Understanding Lifecycle Modes

Lazy (default)

Eager

Keep-Alive

​Next Steps

Configuration Guide

Available Commands

Lifecycle Management

Troubleshooting

Create Your Configuration File

Discover Available Tools

Call Your First Tool

Explore the MCP Tool

Add More Servers

Interactive Management Panel

Import Existing Configurations

Use Direct Tool Registration

Project-Specific Configuration

Understanding Lifecycle Modes

Next Steps