How to add MCP servers to the Pi coding agent
Pi has MCP built in since 0.99.0. Add a local or remote server with pi mcp add, where mcp.json lives, OAuth sign-in over SSH, and list or remove servers.
Pi has MCP built in since version 0.99.0 (September 29, 2026); posts and videos saying it has none predate that. Add a local server with pi mcp add <name> -- <command> and a remote one with pi mcp add <name> --url <url>. Servers go in ~/.pi/agent/mcp.json for every project, or with -l in the project’s .pi/mcp.json, which Pi reads only once you trust the project. pi mcp list checks the connections, pi mcp login signs in to a server that uses OAuth (over SSH you paste the redirected URL back), pi mcp logout forgets the sign-in and pi mcp remove deletes the entry. This page describes Pi 1.5.2, released November 10, 2026.
# a local server, started by Pi over stdio
pi mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .
# a remote server over streamable HTTP, key read from DOCS_TOKEN
pi mcp add docs --url https://example.com/mcp --bearer-token-env-var DOCS_TOKEN
pi mcp list # connect to each server, show state and tools
pi mcp login docs # OAuth sign-in, for servers that use it
pi mcp logout docs # delete the stored sign-in
pi mcp remove docs # delete the entry from mcp.jsonCopiedWhy older pages say Pi has no MCP
Because it didn’t, by choice. Mario Zechner, who wrote Pi, put it plainly in his November 2025 post on building it: “pi does not and will not support MCP.” His reason was context cost: servers load every tool description into each session, and he measured Playwright’s MCP server at “21 tools, 13.7k tokens” and Chrome DevTools’ at “26 tools, 18k tokens”. His alternative was command-line tools with a README the agent reads only when it needs one. MCP in Pi then meant an extension, such as pi-mcp-adapter.
Pi’s makers, now Earendil, reversed that in “You Said No MCP!”, the post that came with 0.99.0: “The MCP of today is not the MCP of yesteryear.” The original objection is answered in how the built-in support works. By default a server’s tools are not put on the model’s tool list at all: the model sees the server named in its prompt and reaches the tools from short JavaScript scripts (“codemode”), so a server’s tool descriptions are not sent with every request. pi.dev’s list of what Pi didn’t build now reads “No MCP Now with MCP+Codemode”, and adds that “MCP extensions are still supported too.” An installed extension that registers /mcp replaces the built-in support, as the guide to Pi extensions explains.
A local server
Everything after -- is the command Pi starts. Environment variables go before it as repeated --env KEY=VALUE, and --cwd sets the directory it runs in; both are refused for a remote server. Pi’s MCP documentation shows a project-only server whose key comes from your environment:
pi mcp add -l tools --env API_KEY='${TOOLS_KEY}' -- uvx tools-mcpCopiedThe single quotes matter: they keep the shell from expanding ${TOOLS_KEY}, so the file stores the reference and Pi fills it in when it starts the server. Without them, the key itself is written into mcp.json.
pi mcp add prints whether it Added or Replaced the server and the file it wrote; adding a name that exists overwrites it. Adding to an untrusted project’s file works, with a note that the file is ignored until you trust the project.
A remote server
Pi speaks streamable HTTP to remote servers. The older SSE transport is not supported, and an entry of type sse is rejected; a server offering both usually has the streamable endpoint at /mcp. Three ways to pass a credential, all from pi mcp add (source: the CLI’s code):
--bearer-token-env-var NAMEwrites anAuthorizationheader ofBearer ${NAME}: the variable’s name, not its value. Pi reads the variable each time it connects, so it has to be in the environment of whatever starts Pi.--header KEY=VALUE, repeatable, for any other header.- OAuth, by leaving both out and running
pi mcp loginafterwards;addsuggests it for a remote server with noAuthorizationheader.
The config file
The file uses the same mcpServers key as Claude Code and other clients, and the docs’ advice for moving over is to “Copy the existing mcpServers entry” into mcp.json and check it with pi mcp list; the docs describe no import from another client’s file. The two servers above look like this:
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
},
"docs": {
"url": "https://example.com/mcp",
"headers": { "Authorization": "Bearer ${DOCS_TOKEN}" },
"description": "Search and read the product documentation"
}
}
}Copied${NAME} is replaced from the environment in env and headers. A value starting with ! is run as a command instead, and the whole value must be the command: the docs’ example is "!echo Bearer $(gh auth token)", which keeps a token out of the file altogether. description is the one-line summary the model sees for the server; leave it out and Pi uses the first line of the server’s own instructions.
User and project. ~/.pi/agent/mcp.json applies everywhere; .pi/mcp.json in a project applies there, and only after you trust the project. When both name the same server, the project’s entry “replaces a user-level entry.” A project entry with no command, url or type only overrides settings, so this turns off one of your own servers in one project:
{
"mcpServers": {
"internal-tools": { "enabled": false }
}
}CopiedSigning in with OAuth on a server with no browser
pi mcp login <name> prints the sign-in address and tries to open a browser. Over SSH there is none to open: copy the address into the browser on your own machine and sign in. The server then sends that browser back to http://127.0.0.1:<port>/callback, which on your laptop goes nowhere, so the page fails to load. Pi’s docs: “If the browser runs on another machine, such as over SSH, paste its redirected URL into the sign-in screen.” Copy the whole address from the address bar and paste it where Pi asks for the URL the browser was redirected to.
Pi offers that prompt only when it runs in a terminal, so sign in from an SSH session, not from a script or a scheduled job. It waits 300 seconds by default (--timeout changes it), then prints that it signed in and how many tools the server has. Tokens are kept in ~/.pi/agent/mcp-auth.json, which deserves the same care as Pi’s auth.json. Most servers need no client set up in advance: since 1.5.0 Pi identifies itself with its own client metadata where the server supports it, and registers a client otherwise. One that wants a client you registered takes --oauth-client-id and --oauth-client-secret, and --oauth-callback-port fixes the callback port if the client allows only one.
pi mcp logout <name> deletes the stored sign-in, to sign in again or as someone else; it prints No stored credentials if there was none.
Listing, checking and removing
pi mcp listconnects to every enabled server and prints its state, transport, tools and errors;--jsonfor a script. It “exits with status 1” when an entry is invalid or an enabled server fails to connect, which makes it a check to run before a scheduled job./mcpinside a session lists the same, servers needing attention first, and lets you reconnect a server, sign in or out, change how its tools are offered, or turn it off. For a local server that failed it shows the error and the end of its stderr. Pi also logs to~/.pi/agent/mcp.log.pi mcp remove <name>deletes the entry from~/.pi/agent/mcp.json; add-lfor the project’s file. If the server is only in the other file, it says so and names the flag. To keep an entry but stop connecting to it, set"enabled": falseinstead.
The pi mcp commands load no extensions and “only see file-configured servers”, so a server an extension registers appears in /mcp but not in pi mcp list.
How the model sees the tools
Each server, or each tool with toolExposure, has an exposure, set with --exposure or in the file:
codemode, the default: “Callable from codemode scripts, but neither declared to the model nor listed in the codemode description.” Scripts find tools by searching for them.deferred: “Not declared until tool_search loads a match for the next model call.”direct: “Declared to the model like a built-in tool and also callable from codemode.”hidden: not reachable at all.
Use direct for the few tools a model should call without searching, and hidden for ones it should never touch, such as a server’s delete tools. MCP calls pass through Pi’s ordinary tool pipeline, so a permission extension that gates tool calls gates these too. A local server still runs as your user with your rights.
On a server, in an unattended run
- Start-up. Pi connects enabled servers in the background when a session starts; “The first prompt waits up to 10 seconds only for servers with direct tools.”
- Timeouts and retries. Each request to a server times out after 60 seconds unless
timeoutsays otherwise, and progress messages from the server reset the clock. Remote calls that fail on a network error or a 408, 429 or 5xx are retried twice. - Variables. A
${NAME}reference is read from Pi’s own environment, so a job run by cron or a service manager needs the variable set there, not only in your login shell. - Without MCP.
pi --no-mcpruns once with no MCP servers; to turn the built-in support off for good, disablemcpunder Built-in inpi config.
For installing Pi on the machine first, see installing Pi on Linux, and for what Pi is and leaves out, what the Pi coding agent is. The same servers in other agents: MCP servers in OpenCode, and a remote MCP server in Claude Code and Codex.