MCP Adapter

PiClaw ships pi-mcp-adapter, which exposes MCP servers to the agent through a single mcp tool plus /mcp commands.

Config locations

Preferred project-local config:

/workspace/.pi/mcp.json

Starter example:

cp /workspace/.pi/mcp.json.example /workspace/.pi/mcp.json

The adapter also understands the global Pi config at:

/config/.pi/agent/mcp.json

Use the project-local file when you want MCP servers tied to the current workspace.

Minimal example

{
  "mcpServers": {
    "filesystem": {
      "command": "bunx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "lifecycle": "lazy"
    }
  }
}

Common workflows

List MCP status / tools

mcp({})

Search for a tool

mcp({ search: "read file" })

Describe a tool

mcp({ describe: "filesystem_read_file" })

Call a tool

mcp({ tool: "filesystem_read_file", args: "{\"path\":\"./README.md\"}" })

args must be a JSON string.

Interactive commands

/mcp
/mcp tools
/mcp reconnect
/mcp reconnect filesystem
/mcp-auth <server>

Operational notes

• MCP servers are lazy by default and connect on first use.
• After editing .pi/mcp.json, restart the session or reload Pi so the adapter re-reads config.
• Prefer directTools only for small, high-value tool sets. Large MCP servers are usually better left behind the mcp proxy.