Create, update, migrate, and debug MCP server configuration for Pi using pi-mcp-adapter. Use when adding an MCP server, editing ~/.pi/agent/mcp.json, importing MCP configs, switching from legacy MCPorter workflows, or documenting MCP setup. Use proactively when auth, server wiring, direct tools, or environment-variable based config is involved.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Create, update, migrate, and debug MCP server configuration for Pi using pi-mcp-adapter. Use when adding an MCP server, editing ~/.pi/agent/mcp.json, importing MCP configs, switching from legacy MCPorter workflows, or documenting MCP setup. Use proactively when auth, server wiring, direct tools, or environment-variable based config is involved.
MCP Management
Manage Pi MCP servers with pi-mcp-adapter.
Use this skill when:
adding a new MCP server
updating an existing MCP server
migrating away from MCPorter
documenting MCP setup for Pi
debugging ~/.pi/agent/mcp.json
deciding whether to use proxy mode or direct tools
configuring OAuth for remote MCP servers
importing configs from other tools (Cursor, Claude Desktop, VS Code, etc.)
working with MCP UI integrations
Preferred Architecture
Going forward, use:
pi install npm:pi-mcp-adapter
global config: ~/.pi/agent/mcp.json
optional project config: .pi/mcp.json
secrets in shell env, preferably ~/.zshrc.local
Do not store long-lived tokens directly in MCP config if environment variables can be used instead.
How It Works
One mcp proxy tool in context (~200 tokens) instead of hundreds
Servers are lazy by default — connect on first tool call, not at startup
Tool metadata cached to disk (~/.pi/agent/mcp-cache.json) so search/list/describe work without live connections
Idle servers disconnect after 10 minutes (configurable), reconnect automatically on next use
npx-based servers resolve to direct binary paths, skipping the ~143 MB npm parent process
Specific tools can be promoted from proxy to first-class Pi tools via directTools config
Per-server directTools overrides the global setting.
Direct tools register from the metadata cache (~/.pi/agent/mcp-cache.json), so no server connections needed at startup. On the first session after adding directTools to a new server, tools fall back to proxy-only and the cache populates in the background. Restart Pi and they'll be available. To force: /mcp reconnect <server> then restart.
Use direct tools sparingly. For servers with 75+ tools, stick with proxy or pick specific tools with a string[].
Import Existing Configs
Already have MCP set up in another tool? Import it:
Run /mcp-auth <server> to initiate the OAuth flow. See OAUTH.md in the pi-mcp-adapter repo for details.
MCP UI Integration
MCP servers can ship interactive UIs. When a tool has a _meta.ui.resourceUri, the adapter opens it in Glimpse (native macOS window) if installed, otherwise falls back to the browser.
Session reuse: calling the same tool again pushes new results to the existing window
Bidirectional messaging: UI can send prompts/intents back to the agent
Tool consent: gates whether UIs can call MCP tools (never/once-per-server/always)
Retrieve UI messages:
mcp({ action: "ui-messages" })
Set viewer preference via env: MCP_UI_VIEWER=browser or MCP_UI_VIEWER=glimpse.
Usage Reference
Mode
Example
Status
mcp({ })
List server
mcp({ server: "name" })
Search
mcp({ search: "screenshot navigate" })
Describe
mcp({ describe: "tool_name" })
Call
mcp({ tool: "...", args: '{"key": "value"}' })
Connect
mcp({ connect: "server-name" })
UI messages
mcp({ action: "ui-messages" })
Note: args is a JSON string, not an object.
Search includes both MCP tools and Pi tools (from extensions). Pi tools appear first with [pi tool] prefix. Space-separated words are OR'd. Tool names are fuzzy-matched on hyphens and underscores.
