How to Add MCP Support to Pi (Step-by-Step)

Prerequisites

• Pi installed (see Pi Coding Agent)
• A prompt/context setup that includes AGENTS.md (see Prompt Engineering in Pi)
• Node.js 18+ or Docker for npx- and Docker-based MCP servers

The Pi Difference: MCP Is Opt-In

Pi (Mario Zechner's minimal terminal harness) deliberately ships without built-in MCP. The design principle is explicit: pi keeps the core small and pushes workflow-specific behavior into extensions, skills, prompt templates, and packages. No built-in MCP, sub-agents, permission popups, or plan mode — you build or install those.

That means enabling MCP in pi is a matter of installing the right package and wiring it into your session, not editing a config key. The exact mechanism depends on which pi package/extension provides MCP support — check pi pkg list or the pi package registry for an MCP server package.

Method 1: Install an MCP Package

The standard path is to install an MCP-providing package into pi:

pi pkg install mcp

Then verify it's available:

pi pkg list | grep -i mcp

Method 2: Wire an MCP Server Into a Session

If the package exposes MCP servers, configure them in the package's settings and reference the server's tools in your prompt:

pi "Use the filesystem MCP server to list every markdown file in docs/"

The pattern is the same as any pi tool: you prompt for the tool by name and pi routes the call to the underlying server.

Method 3: Skills + Extensions

Since pi is extension-driven, many MCP integrations arrive as skills or extensions rather than core config:

1. Install a skill that wraps an MCP server (e.g. a "github-mcp" skill)
2. Invoke it with /skill:name or reference it in your prompt
3. The skill carries the server config and tool definitions

See Agent Skills for the cross-tool SKILL.md standard that pi supports.

Verifying MCP Is Working

1. Run a read-only prompt that targets the server, e.g. pi --tools read,ls "Use the filesystem server to list README files"
2. Check the response includes tool results from the server (not just prose)
3. Confirm the package loaded without errors in the session

Security Considerations

• Least privilege — pi has no built-in permission prompts by design; use --tools allowlists and --no-tools for untrusted or read-only work
• Review before you trust — inspect .pi/settings.json before trusting a project with local settings/skills
• 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
• Prompt Engineering in Pi — context files, system prompts, slash commands
• Agent Skills — the cross-tool SKILL.md standard
• MCP Setup in Cursor — the same concepts in a batteries-included IDE