Use MCP servers with Pi without burning your context window.
$ npx -y skills add nicobailon/pi-mcp-adapter --agent claude-code
Repo: nicobailon/pi-mcp-adapter
What's inside
Use MCP servers with Pi without burning your context window.
https://github.com/user-attachments/assets/4b7c66ff-e27e-4639-b195-22c3db406a5a
Mario wrote about why you might not need MCP. The problem: tool definitions are verbose. A single MCP server can burn 10k+ tokens, and you're paying that cost whether you use those tools or not. Connect a few servers and you've burned half your context window before the conversation starts.
His take: skip MCP entirely, write simple CLI tools instead.
But the MCP ecosystem has useful stuff - databases, browsers, APIs. This adapter gives you access without the bloat. One proxy tool (~200 tokens) instead of hundreds. The agent discovers what it needs on-demand. Servers only start when you actually use them.
pi install npm:pi-mcp-adapter
Restart Pi after installation.
DeepSeek Harness (third-party bridge): Run the unmodified adapter in DSH via pi2dsh; see the verified dsh-TUI and Web MCP guide.
The adapter reads standard MCP files automatically. No extra setup needed if you already have them.
| You already have... | What happens |
|---|---|
.mcp.json or ~/.config/mcp/mcp.json | Pi uses it immediately. Use .mcp.json for project/team sharing and ~/.config/mcp/mcp.json for all projects. The first time you open /mcp, you'll see a short heads-up explaining which file Pi detected and that Pi only writes adapter-specific overrides to its own files. |
| Host-specific configs (Cursor, Claude Code, Codex, etc.) but no standard MCP files | Run /mcp setup to adopt those host configs into Pi. The setup flow shows exactly what it found, lets you pick which ones to import, and previews the exact file changes before writing. |
| Nothing configured yet | Run /mcp setup, choose project .mcp.json or global ~/.config/mcp/mcp.json, then scaffold a minimal config, add a curated known server, quick-add RepoPrompt, or inspect what the adapter discovered on your machine. |
If you prefer the terminal, you can also run pi-mcp-adapter init after install to scan for host-specific configs and add missing compatibility imports to the Pi agent dir (~/.pi/agent/mcp.json by default, or $PI_CODING_AGENT_DIR/mcp.json when set).
Preferred project config: .mcp.json
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": ["-y", "chrome-devtools-mcp@1.6.0"]
}
}
}
Preferred user-global shared config: ~/.config/mcp/mcp.json (for all projects). Pi also reads the tool-agnostic global paths ~/.agents/mcp.json and ~/.agents/mcp/mcp.json as compatibility inputs.
Pi-owned files are not additional normal setup choices. They hold Pi-specific settings, compatibility imports, and adapter-only overrides:
<Pi agent dir>/mcp.json — Pi global override (~/.pi/agent/mcp.json by default).pi/mcp.json — Pi project overrideHost-specific configs are detected and shown by /mcp setup and pi-mcp-adapter init, but they are compatibility inputs rather than normal setup paths and are not loaded automatically. The normal /mcp panel does not scan host-specific files when settings.hostConfigDiscovery is "off". To explicitly opt in to host-config fallback discovery, set settings.hostConfigDiscovery to "on" or run pi-mcp-adapter init --discover-host-configs. The default is "off"; "prompt" is available for integrations that want detection without activation. Host configs are lower precedence than every shared and Pi-owned source, and /mcp setup continues to offer explicit import adoption. Discovery reports source paths, provenance, and same-name conflicts; it never writes to external host files or silently launches commands from them.
Precedence is (later entries win):
~/.config/mcp/mcp.json~/.agents/mcp.json~/.agents/mcp/mcp.json<Pi agent dir>/mcp.json.mcp.json.pi/mcp.jsonAncestor discovery is off by default. To opt in, set settings.ancestorConfigRoots in a user-global config above, or in the explicitly selected --mcp-config/configPath file, for example "ancestorConfigRoots": ["~/work/team"]. Each root must be an explicit absolute path or ~/..., resolve to an existing directory under $HOME, and contain the canonical cwd. If several roots match, only the nearest (deepest) is used. Project .mcp.json and .pi/mcp.json files cannot enable discovery or extend the boundary.
Within the selected root, existing .mcp.json and <configDir>/mcp.json (normally .pi/mcp.json) files load between steps 4 and 5, from the root through parent(cwd), farthest first. Nearer directories override farther ones, Pi overrides shared config within each directory, and cwd files win over ancestors. Search never goes above the configured root or $HOME; the boundary limits discovery but is not a file-ownership or symlink-target sandbox. Only configure roots whose project files you trust. /mcp setup write targets and project-local /mcp disable and /mcp enable overrides are unchanged.
/mcp disable <server> and /mcp enable <server> persist only the disabled field in the project-local .pi/mcp.json, which is the highest-precedence Pi layer. Enabling removes the project flag when lower layers are enabled, or writes false when needed to override a disabled lower source. This applies even when the effective server came from a shared global/project file, an imported host config, or configPath; the source file is never rewritten and credentials are never copied. Run /reload after changing the flag so registered tool surfaces are refreshed. The manual equivalent is to add { "disabled": true } to a server in any normal MCP config. Supplied in-memory createMcpAdapter({ config }) configurations are isolated and do not read or write this project override; the commands are unavailable in that mode.
Servers are lazy by default — they won't connect until you actually call one of their tools. The adapter caches tool metadata so search and describe work without live connections.
mcp({ search: "screenshot" })
chrome_devtools_take_screenshot
Take a screenshot of the page or element.
Parameters:
format (enum: "png", "jpeg", "webp") [default: "png"]
fullPage (boolean) - Full page instead of viewport
mcp({ tool: "chrome_devtools_take_screenshot", args: { format: "png" } })
args can be a JSON object or a JSON string. Prefer the object form when your model handles it reliably; the string form remains supported for providers that need simpler schemas.
Two calls instead of 26 tools cluttering the context.
Use the shared MCP files when you want one setup to work across hosts, and Pi-owned files when you need Pi-specific overrides or settings.
| File | Purpose |
|---|---|
~/.config/mcp/mcp.json | User-global shared MCP config |
~/.agents/mcp.json | User-global tool-agnostic MCP config |
~/.agents/mcp/mcp.json | User-global tool-agnostic MCP config |
.mcp.json | Project-local shared MCP config |
<Pi agent dir>/mcp.json | Pi global override and compatibility imports (~/.pi/agent/mcp.json by default) |
.pi/mcp.json | Pi project override |
Pi-specific files are the write targets for imported or shared global servers when Pi needs to persist adapter-only settings such as directTools.
The adapter can load MCP servers from Agent Plugins packages when you list plugin directories in settings.agentPluginPaths:
{
"settings": {
"agentPluginPaths": ["./plugins/acme-tools"]
},
"mcpServers": {}
}
Each directory must contain a valid Agent Plugins 1.0 plugin.json. If it also has a root mcp.json, the adapter loads its mcpServers entries and prefixes them as <plugin>__<server>. The loader uses the Agent Plugins transport declared by each server type and skips invalid entries without blocking other servers. For stdio plugin servers, ${PLUGIN_ROOT} and ${PLUGIN_DATA} are expanded only in args, env, and cwd; the adapter sets both variables for the child process and stores plugin data under the Pi agent directory.
inheritEnv is an adapter-specific Pi field, not an Agent Plugins or OpenCode schema field. Do not add it to a plugin's strict mcp.json; to opt a plugin stdio server out of host-environment inheritance, set inheritEnv: false in a normal Pi override using the translated <plugin>__<server> name:
{
"mcpServers": {
"acme_tools__local": { "inheritEnv": false }
}
}
Agent Plugins is a portable package format. Native Pi MCP config remains .mcp.json, ~/.config/mcp/mcp.json, and Pi-owned overrides.
The adapter can opt into MCP servers and Pi skills from explicitly configured local Claude plugin directories:
{
"claudePlugins": [
{ "path": "./plugins/acme-tools", "mcp": true, "skills": true }
],
"mcpServers": {}
}
Each entry needs a non-empty path and must enable mcp, skills, or both. The root-level field can be set in any normal adapter config source; normal config-source precedence applies, and a higher-precedence claudePlugins array replaces a lower one. Relative paths in file-based config resolve from the active project cwd. For createMcpAdapter({ config }), relative plugin paths are normalized against process.cwd() when the factory is created; this explicit API-boundary snapshot keeps early registration and session startup on the same local bundle even when the host's context cwd differs. mcp: true reads only the plugin's root .mcp.json; skills: true discovers skills/**/SKILL.md inside the plugin and passes those files through Pi's normal resource discovery, including startup and /reload. A .claude-plugin/plugin.json manifest is optional, matching Claude's plugin format, but when present it must be valid JSON with a kebab-case name and valid standard field types. Manifest path overrides are intentionally not followed.
Claude plugin MCP server names are used as written. The first explicitly listed plugin wins same-name conflicts between plugin bundles, while every normal Pi MCP config source overrides these plugin defaults. ${CLAUDE_PLUGIN_ROOT} is expanded in plugin MCP server fields, and stdio servers receive it in their environment. Skills use Pi's existing skill parsing and conflict handling.
This is an explicit local trust boundary: the adapter does not discover, download, install, or update plugins; execute plugin hooks; or fetch skills from MCP instructions. It resolves plugin components inside each configured directory and rejects component symlinks that escape it. Config and skills are read during discovery, but MCP commands are still lazy and run only when normal adapter lifecycle/tool use connects that server. Enable mcp only for plugin directories whose commands and configuration you trust.
A Pi package can ship MCP servers for the installed adapter without requiring a separate MCP config file. Declare a package-relative config in its package.json:
{
"pi": {
"mcp": "./mcp.json"
}
}
View @nicobailon’s profileAn agent skill that turns complex terminal output into styled HTML pages you actually want to read. Ask your agent to explain a system architecture, review a diff, or compare requirements against a plan.
@nicobailonFAQ
pi-mcp-adapter is a Claude Code plugin with 1 hand-picked skill for development work, indexed on Flowy. Install it with the command on its page. It includes mcp-scripting. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
Is this plugin yours?
Claim it with GitHubSubmit a pluginPromote it