GuidesHosting choices

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.

November 18, 2026The Everpod team
The short answer

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.json
Copied

Why 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-mcp
Copied

The 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):

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 }
  }
}
Copied

Signing 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

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:

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

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.

Run the Pi coding agent on an always-on developer pod.

A developer pod is a permanent cloud computer (VPS), set up and secured for you, with your pick of Claude Code, Codex, OpenCode, Pi, Hermes and OpenClaw installed. Run more agents at once than your laptop can hold, and keep them working when it’s closed. From $24 a month, built in about ten minutes.