MCP

Pi’s built-in tools cover files and shell commands. For everything else, like live data, a company’s internal docs, or a third-party service, there’s MCP, the Model Context Protocol. It’s an open standard for small programs, called servers, that give an AI agent extra tools. Pi supports it out of the box.

Local and remote servers

An MCP server is either:

• Local: a command Pi starts on your computer and talks to over stdio, often via npx or uvx.
• Remote: a URL Pi connects to over streamable HTTP. Some remote servers need you to sign in.

Add a weather server

Let’s connect a local server that fetches live weather data from Open-Meteo, a free public weather API with no account or API key required. Run this in your terminal (or ask Pi to run it for you):

pi mcp add open-meteo -- npx -y -p open-meteo-mcp-server open-meteo-mcp-server

Everything after -- is the command Pi runs to start the server. This one needs Node.js. If you don’t have it, ask Pi to help you install it.

Check that the server starts and see what tools it offers:

pi mcp list

Then, inside your Pi session, run /reload to pick up the new server, and /mcp to see its status.

Where servers are configured

pi mcp add writes to ~/.pi/agent/mcp.json, which applies to every project. Add --local (-l) to write .pi/mcp.json in the current project instead. Project servers only load once the project is trusted (see the Trust lesson).

{
  "mcpServers": {
    "open-meteo": {
      "command": "npx",
      "args": ["-y", "-p", "open-meteo-mcp-server", "open-meteo-mcp-server"]
    }
  }
}

This is the same mcpServers format Claude Code, Claude Desktop, and Cursor use, so you can usually copy existing entries straight over.

A remote server is just a URL. For example, Cloudflare’s public documentation server needs no sign-in:

pi mcp add cloudflare-docs --url https://docs.mcp.cloudflare.com/mcp

For remote servers that use OAuth, you don’t put credentials in the file. Run /mcp and choose “Sign in”, or run pi mcp login <server>, and Pi opens the authorization page in your browser.

Try it

Ask Pi something only the weather server can answer:

What’s the weather forecast for Tokyo for the next three days?

Watch the tool calls. Pi searches for a weather tool, calls it, and answers from the result instead of from memory.

Why MCP doesn’t fill up your context

MCP servers can offer dozens of tools, and every tool definition the model sees costs context, whether you use it or not. Pi avoids that by not showing MCP tools to the model up front. Each server has an exposure setting that decides how its tools reach the model:

You can change a server’s exposure in /mcp. Tools are named mcp__<server>__<tool>, so the weather tool you just used is something like mcp__open_meteo__weather_forecast. The next lesson, Code mode, explains what those codemode scripts are.

Turning MCP off

Run pi --no-mcp to start a session with no MCP servers. To disable a single server, choose it in /mcp and disable it, or set "enabled": false on its entry.

If you’d rather have servers that start only when used and stop when idle, the community pi-mcp-adapter package replaces Pi’s built-in MCP support. If you installed it during an earlier version of this course, the built-in support stays off until you remove it with pi remove npm:pi-mcp-adapter and re-enable mcp under Built-in in pi config.

For OAuth options, project overrides, and resources, see Pi’s MCP documentation.