MCP in Pi Agent Platform
The platform installs pi-mcp-adapter for token-efficient MCP access and manages servers across four configuration layers.
Where to start
Enter /piagent-mcp to open a menu. You do not need to memorize subcommands:
MCP
Servers — 2/3 ready
Doctor — 1 need attention (recommended)
Inspect a server
Approve a repository server — 1 waiting
Turn a server off
Add a server
All subcommandsThe menu reflects the current project. It does not offer "turn back on" when no server is disabled or "approve" when nothing is waiting. When an action requires a server, it asks which one unless only one choice exists.
Every menu item also has a direct command:
/piagent-mcp doctor show what is blocked and what it needs
/piagent-mcp status show the full table
/mcp show live connection state from the adapter
/mcp-auth <name> authenticate one OAuth serverIn a terminal, use the same command family without the slash: piagent-mcp list or piagent-mcp doctor. Adding and removing server definitions is terminal-only. See Server management.
Three similar names that are not connected
No code maps a capability name to an MCP server ID. Declaring "github" in mcpCapabilities does not enable the MCP server named github, and the reverse is also false.
| Item | Location | Meaning |
|---|---|---|
| mcpCapabilities: ["github"] | .pi/piagent-profile.json | A capability label for the tool registry |
| toolCapabilities | base-policy.json | Maps a tool named github to a capability |
| github server | ~/.config/mcp/mcp.json | The actual MCP server, running through Docker |
Four configuration layers
All four files are read. The --scope option of piagent-mcp uses these names.
| Scope | File | Use |
|---|---|---|
| global | ~/.config/mcp/mcp.json | Default shared configuration for multiple agents and projects |
| pi-global | ~/.pi/agent/mcp.json | Pi-specific global overrides |
| project | .mcp.json | Repository-specific, committable server definitions |
| pi-project | .pi/mcp.json | Pi-specific overrides for one repository |
Cloning a repository also brings its .mcp.json. Servers from these scopes must pass the approval gate before use.
Pinned presets
piagent-setup and piagent-install install pi-mcp-adapter and seed the core preset by default. Skip this with --no-mcp.
| Preset | Servers | Purpose |
|---|---|---|
| minimal | — | Safe settings only |
| docs | Context7 | Current framework and library docs |
| browser | Chrome DevTools, Playwright | UI/runtime inspection and browser automation |
| github | GitHub MCP | Issue, PR, repository, and release workflows |
| design | Figma remote | Design-to-code through Figma OAuth |
| design-local | Figma desktop | Local Dev Mode MCP |
| web | Context7, Chrome DevTools, Playwright | Frontend and web workflows |
| core | Context7, Chrome DevTools, GitHub | Default team baseline |
| popular | core + Playwright + Figma | A broader development baseline |
| all | popular + Figma desktop | Complete preset |
Every server is pinned by version or digest. An MCP server is code running on the operator's machine with the operator's credentials, so floating tags would turn each session into an unattended supply-chain decision.
Servers connect lazily and are not checked until first use. Authentication and readiness explains which servers can actually run.
Token efficiency
pi-mcp-adapter exposes all servers through one proxy tool named mcp instead of loading every tool schema into startup context. Defaults include directTools: false, outputGuard, and idleTimeout.
The proxy tool mcp is not in alwaysAllowedTools or toolCapabilities, so enforce mode blocks all MCP access. Adding mcpCapabilities cannot bypass that earlier block. The only exception is trusted-full-access.