mcp-servers

MCP servers

This agent has a built-in MCP client. Servers are declared in mcp.json; their tools appear as mcp_<server>_<tool> once connected. The model can also always find and call MCP tools via a single mcp proxy tool (mcp({ search: "..." }) / mcp({ tool: "...", args }) without their schemas ever being loaded into context, and without a lifecycle: "lazy" server being connected until one of its tools is actually needed — see "Context window control" below.

Config files

File	Scope
~/.pi/agent/mcp.json	global (all projects)
<project>/.pi/mcp.json	project-local, only honored in trusted projects

Project entries override global entries with the same server name; project settings keys override global ones per key. Prefer project-local config for project-specific servers, global for personal/general-purpose ones. Create the file if it doesn't exist.

Applying changes: config is read at session start. After editing mcp.json, tell the user to run /reload (this re-reads config, restarts servers, and refreshes tools). You cannot run /reload yourself.

Config format

{
  "settings": {
    "toolPrefix": "mcp",
    "requestTimeoutMs": 30000,
    "maxRetries": 3,
    "searchResultLimit": 15
  },
  "mcpServers": {
    "<server-name>": { ... }
  }
}

settings is optional. Server names: keep them short and lowercase; they become part of tool names.

Local (stdio) server — spawned as a subprocess

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
      "env": { "SOME_VAR": "literal-value" }
    }
  }
}

• command is required; transport defaults to "stdio".
• env values are literals merged over the parent environment — there is no ${VAR} interpolation. If a server needs a secret, ask the user to provide it or reference their shell environment by launching via a wrapper script.
• Most published servers run via npx -y <package> (Node) or uvx <package> (Python). If unsure of the package name, search the web for " MCP server".