Installation and MCP Guide

Pi 1.0 Coding Agent Setup: Install, Configure MCP, and Run Codemode

SitePoint TeamPublished inAI·Programming·
October 3, 2026

The AI briefing for Developers

Stay up to date with AI tools, model releases, and developer workflows that matter.

Weekly. Free. One click to leave.

SitePoint Premium
Stay Relevant and Grow Your Career in Tech

• Premium Results
• Publish articles on SitePoint
• Daily curated jobs
• Learning Paths
• Discounts to dev tools

7 Day Free Trial. Cancel Anytime.

Pi 1.0 is the first stable release of Pi, an open-, 2026, and this Pi 1.0 coding agent setup guide takes you from install to a first MCP server and a first codemode script. Every command below comes from the official Pi documentation

How to Set Up Pi 1.0 and Configure MCP Servers

1. Install Pi with npm install -g --ignore-scripts @earendil-works/pi-coding-agent (Node.js 22.19 or newer) or the pi.dev installer script.
2. Verify the install with pi --version, then start pi in a project folder.
3. Log in to a model provider with /login.
4. Add an MCP server with pi mcp add and check it with pi mcp list.
5. Reload with /reload and let the model call the server from a codemode script.

Table of Contents

What Is Pi 1.0?

Pi describes itself as a minimal agent harness. It runs in your terminal, works on the files in your current folder, and skips features such as sub-agents and plan mode. You extend it with extensions, skills, prompt templates, and themes instead. It supports 15+ providers, including Anthropic, OpenAI, Google, and Ollama for local models.

The 1.0 release changed a few defaults and added features that matter for this guide. According to the changelog, the terminal UI now runs fullscreen by default (set tuiMode to "regular" to keep normal scrollback), codemode uses about 40% fewer prompt tokens, and MCP OAuth handling was hardened.

Pi is not Inflection AI’s Pi chatbot. The coding agent lives at pi.dev and in the earendil-works/pi repository on GitHub.

Install Pi 1.0

Pi ships as an npm package. The docs recommend --ignore-scripts so dependency lifecycle scripts do not run during installation, and Pi does not need them. This route needs Node.js 22.19 or newer:

npminstall-g --ignore-scripts @earendil-works/pi-coding-agentpi --version

On macOS or Linux you can use the installer script instead. The installer pins all dependencies, while npm does not pin transitive ones. As with any script piped into a shell, download and read it first if you want to inspect what it does:

curl-fsSL https://pi.dev/install.sh -o install.shless install.shsh install.sh

Then change into a project folder and start Pi:

cd /path/to/projectpi

Pi uses the working folder to find project files, instructions, and configuration, and to group saved sessions. Resume the last session for a folder with pi --continue.

Connect a Model

Pi needs access to a model through a provider. Inside Pi, run /login, pick a provider, and follow the prompts to use a subscription or store an API key. Run /model afterward to choose a different model. The models documentation covers environment-variable authentication, local models, and custom endpoints.

Add an MCP Server with pi mcp add

Pi connects to Model Context Protocol servers over stdio or streamable HTTP. Add a local stdio server, check the connection, then start Pi:

pi mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .pi mcp listpi

Everything after -- is the server command and its arguments. pi mcp add only writes the configuration and does not connect. pi mcp list connects to every enabled server and prints its state, tools, and errors. It exits with status 1 when an entry is invalid or an enabled server is not connected, so you can use it in scripts.

For a remote server, pass a URL and, if it needs a token, the name of an environment variable that holds it:

pi mcp add docs --url https://example.com/mcp --bearer-token-env-var DOCS_TOKENpi mcp list

Where the configuration lives

{"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"}}}

Values in env and headers can reference environment variables such as ${DOCS_TOKEN}, so you do not have to store a secret in the file. Keep servers with credentials in the user-level file, and use the project file only for servers the project requires. After you change a server outside a session, run /reload inside Pi. Use /mcp to inspect connections, sign in, reconnect, or disable a server.

Servers that use OAuth

Remote servers that use OAuth need no credentials in mcp.json. When the server rejects an unauthenticated connection, run pi mcp login <server> or /mcp login <server>. Pi opens the authorization page, stores tokens in ~/.pi/agent/mcp-auth.json, and refreshes them when they expire. pi mcp logout <server> deletes the stored credentials.

How Codemode Works

Codemode is a tool, not a separate mode. It lets the model write a JavaScript script that calls Pi’s other tools, including MCP tools. Only the script’s output goes back to the model, so a script can run several calls in parallel and filter large results before the model reads them. The script runs in a QuickJS sandbox with top-level await. The sandbox has no Node APIs, file system, network, or timers, so a script reaches the outside world only through tools.

You do not have to switch it on for MCP. Pi activates codemode when a server with the default codemode exposure connects. MCP tools are then named mcp__<server>__<tool>, and scripts call them as tools.mcp__<server>__<tool>(args). To keep codemode active without any MCP server, add this to ~/.pi/agent/settings.json:

{"defaultTools":["+codemode"]}

A script can start with an options line that caps output and sets a hard deadline:

Scripts find tools with searchTools(), describeTool(), or by filtering ALL_TOOLS. Tool calls are real: if a script fails partway, the calls it already made are not undone.

Control how tools reach the model

Each server has an exposure setting. The default, codemode, makes tools callable from scripts without declaring them to the model. deferred loads a tool only after tool_search finds it. direct declares it like a built-in tool, which suits a small set you use constantly. hidden makes it unreachable. You can override the setting for single tools with toolExposure:

{"mcpServers":{"github":{"url":"https://api.githubcopilot.com/mcp/","exposure":"deferred","toolExposure":{"search_code":"direct","delete_*":"hidden"}}}}

Safety and Troubleshooting

Pi shows each file read, search, command, and edit it makes, but it does not ask before every tool call. Review the changes when it finishes and use version control for important work. For untrusted or unattended work, run Pi in a container or another sandbox. The security documentation explains project trust and what Pi can access.

• A server is missing or failing: run pi mcp list. /mcp inside a session shows the full connection error and the tail of stderr from a failed stdio server.
• Config changes do not show up: run /reload after adding, removing, or editing a server outside the session.
• A project server is ignored: project .pi/mcp.json files are read only for trusted projects.
• Server logs: logging notifications are appended to ~/.pi/agent/mcp.log.
• Invalid entries: Pi reports them and skips them without blocking other servers. Server names may contain only letters, digits, _, and -.

What’s Next

From here, add more MCP servers, write an AGENTS.md with instructions Pi should follow in a folder, or try skills and prompt templates. Browse the official MCP servers repository for ready-made servers, and check each one’s README before you give it access to your files or accounts.

Sharing our passion for building incredible internet things.