Add an MCP Server

pi-mcp-adapter

Step 1: Determine Scope

~/.pi/agent/mcp.json

.pi/mcp.json

Step 2: Determine Server Type

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "package-name@latest"],
      "env": { "KEY": "value" }
    }
  }
}

{
  "mcpServers": {
    "server-name": {
      "url": "http://localhost:8080/mcp",
      "headers": { "Authorization": "Bearer token" }
    }
  }
}

Step 3: Gather Configuration

command

url

command

args

env

cwd

url

headers

auth

"oauth"

"bearer"

bearerToken

bearerTokenEnv

lifecycle

"lazy"

"eager"

"keep-alive"

lazy

idleTimeout

debug

• lazy (default) — connects on first tool call, disconnects after idle timeout
• eager — connects at session start, no auto-disconnect
• keep-alive — connects at start, auto-reconnects if dropped

Step 4: Write the Config

1. Read the target config file if it exists
2. Merge the new server into the existing

   mcpServers

   object
3. Write the updated JSON

{
  "mcpServers": {
    "server-name": { ... }
  }
}

Step 5: Verify

1. Run

   /reload

   to pick up the new config
2. Use

   mcp({ connect: "server-name" })

   to test the connection
3. Use

   mcp({ server: "server-name" })

   to list available tools
4. Report success or troubleshoot connection errors