How to Set Up MCP Servers in Pi (Step-by-Step)

Prerequisites

• Pi installed (see Pi Coding Agent)
• Node.js 18+ or Docker for npx- and Docker-based MCP servers

Built-in MCP Support

Pi includes MCP support. It connects to servers over stdio or Streamable HTTP, exposes their tools and resources to the model, and reads configuration from ~/.pi/agent/mcp.json (user) and .pi/mcp.json (project). The legacy SSE transport is not supported.

To disable MCP for one run, use --no-mcp. To disable the built-in extension without a replacement, set "extensions": ["-builtin:mcp"] in Pi settings or disable mcp under Built-in in pi config.

Method 1: CLI Commands

Add a local server, check the connection, then start Pi:

pi mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .
pi mcp list

These commands write to the user configuration by default. Add --local or -l to write the project file:

pi mcp add -l tools --env API_KEY='${TOOLS_KEY}' -- uvx tools-mcp

For a remote server:

pi mcp add docs --url https://api.githubcopilot.com/mcp/ --bearer-token-env-var GITHUB_TOKEN
pi mcp list

Manage servers with pi mcp add, pi mcp list, and pi mcp remove. Inside an interactive session, /mcp lets you inspect connections, sign in, reconnect, change exposure, and enable or disable servers. Run /reload after changing configuration outside the session.

Method 2: mcp.json

Pi uses the same mcpServers shape as other MCP clients:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
    }
  }
}

Stdio servers use command, args, env, and cwd. HTTP servers use url, headers, and oauth. Server names may contain only letters, digits, _, and -. A command selects stdio and a url selects Streamable HTTP; type is optional and must be stdio, http, or streamable-http when present.

Security Considerations

• Least privilege — use --tools allowlists, --exclude-tools, and --no-mcp for untrusted or read-only work
• Review before you trust — inspect .pi/mcp.json before trusting a project with local settings
• Keep secrets out of repos — pass API keys via environment variables, not in prompt files
• Package provenance — only install MCP packages from sources you trust

Troubleshooting

Further Resources

• MCP Servers directory — pick servers that match your tools
• Pi CLI Reference — MCP and tool commands
• Agent Skills — the cross-tool SKILL.md standard
• MCP Setup in Cursor — the same concepts in a batteries-included IDE

Sources

• https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/mcp.md
• https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/cli.md
• https://github.com/github/github-mcp-server