Pi 1.0 Guide: Set Up MCP, Codemode, and Extensions Safely

Pi 1.0 is an open-source AI agent harness that works from the terminal, reads and edits files, and runs commands through a deliberately small toolset. The October 1, 2026 release was more than a version-number milestone. It added built-in Model Context Protocol support, introduced Codemode for composing tool calls in JavaScript, expanded model-routing options, and separated long-running application needs into the experimental Pi Durable package.

The attractive part of Pi is also the part that requires care. It is highly malleable, but it does not put an approval dialog in front of every tool call. A safe setup therefore starts with the working directory, operating-system permissions, credentials, and tool exposure rather than with an ambitious prompt. This guide walks through installation, provider login, MCP configuration, Codemode, extensions, practical workflows, and security boundaries using Pi’s official documentation checked on October 5, 2026.

Pi is an executable harness, not just a chat interface

Pi combines a terminal UI, model access, saved sessions, file and shell tools, and an extension runtime. You can connect a supported subscription or API key, use a compatible endpoint, or work with a local model. When a session starts, the working directory helps Pi discover files, project instructions, settings, and saved-session context.

The word harness matters. The model is only one component. The surrounding system decides what files the model can inspect, which tools it can call, how results are recorded, and whether a failed process can resume. Pi keeps that system intentionally compact and lets users add AGENTS.md instructions, prompt templates, skills, TypeScript extensions, MCP servers, and custom model routing when they are actually needed.

What changed in Pi 1.0

Change	Why it matters	Main caution
Built-in MCP	Connects tools and resources over stdio or Streamable HTTP.	Separate personal credentials from repository configuration and limit tool exposure.
Codemode	A QuickJS script can call tools in parallel and filter results before returning them to the model.	The script VM is isolated, but the file, shell, and MCP tools it calls still have real effects.
Virtual models and mid-conversation changes	Extensions can route stages to different models and adjust prompts or tools during a session.	Extensions run with the Pi process’s operating-system permissions.
Pi Durable	Provides a separate foundation for checkpointed, long-running, multi-conversation applications.	It is experimental and does not replace the stable terminal coding agent.

Pi 1.0.1 and 1.0.2 followed on October 3 and 4 with project-level MCP overrides, OAuth-related options, tool rendering improvements, and fixes. For a new installation, check the current stable release instead of assuming the first 1.0.0 tag is the best target.

Before you install

• A limited working folder: Start in a copy, a clean Git branch, or a separate worktree, not your entire home directory.
• Model access: You need a supported subscription, an API key, a local model, or a compatible endpoint. Pi is MIT-licensed, but provider pricing and terms still apply.
• Version control or backups: Make sure important edits can be reversed before an agent changes files.
• An isolation plan: Use a container, virtual machine, sandbox, or dedicated account for untrusted repositories and unattended work.
• Node.js when using npm: The direct npm installation requires Node.js 22.19 or newer.

Step 1: Install Pi and verify the working directory

On macOS or Linux, the official installer command is:

curl -fsSL https://pi.dev/install.sh | sh
pi --version

On Windows, Pi provides a PowerShell installer:

powershell -c "irm https://pi.dev/install.ps1 | iex"

You can also install the coding-agent package directly with npm. Pi’s documentation distinguishes the two paths: the installer pins transitive dependencies, while the npm path does not.

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Move into the folder Pi should work on before starting it:

cd /path/to/project
pi

A good completion check has three parts: pi --version prints a version, the footer shows the expected working folder and model status, and the session was created for the intended project. If the folder is wrong, exit before assigning work and start again from the correct location.

The terminal interface shown in Pi’s official Quickstart. Check the footer for the active folder, model, and session state. Source: Pi Documentation, accessed October 5, 2026.

Step 2: Connect a provider and begin with a read-only task

Run /login inside Pi, choose a provider, and follow the prompts to use a supported subscription or store an API key. Use /model afterward if you want to select another available model. Avoid pasting secrets into a project file or prompt. Prefer Pi’s login flow or documented environment-variable authentication.

Your first request should test visibility without changing the repository:

Explain this repository’s structure and the available check commands. Do not modify files yet.

Review the files, searches, and commands Pi displays. Visibility is useful for auditing, but it is not the same as a permission boundary. Pi does not ask for confirmation before every tool call.

Step 3: Separate user-level and project-level MCP servers

Pi 1.0 supports local stdio servers and remote Streamable HTTP servers. The official filesystem example can be added and checked with:

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

By default, the command writes a user-level server to ~/.pi/agent/mcp.json. Add --local or -l when a server belongs only to the current project and should be written to .pi/mcp.json. Project MCP configuration loads only after project trust is granted.

A practical division is to keep personal servers and credential-bearing connections in the user file. Put only repository-required definitions in the project file. Reference tokens through environment variables such as ${DOCS_TOKEN} instead of writing their values into JSON. After a change, run pi mcp list and inspect its exit status and errors. If the session is already open, use /reload.

Step 4: Minimize tool exposure

Connecting an MCP server does not mean every tool must be declared directly to the model. Pi offers four exposure modes:

• codemode: The default. Tools remain callable from Codemode scripts and are discovered when needed rather than being declared on every request.
• deferred: tool_search finds a relevant tool and declares it for the next model call. This fits large servers.
• direct: A small, frequently used toolset is declared like built-in tools.
• hidden: The tool remains registered but is unreachable by the model.

You can keep read operations discoverable while hiding delete or deployment operations with toolExposure patterns. MCP annotations such as readOnlyHint, destructiveHint, and idempotentHint can help a permission extension decide when to ask for confirmation, but those hints are not a security guarantee by themselves.

Tool-exposure controls in Pi’s official MCP documentation. Server defaults and per-tool toolExposure rules can be combined. Source: Pi Documentation, accessed October 5, 2026.

Step 5: Understand what Codemode does and does not isolate

Codemode lets the model write JavaScript that runs inside a QuickJS sandbox and calls Pi’s other tools. The script has no direct Node APIs, filesystem, network, or timers. It reaches the outside world only through tools and models. This makes it useful for parallel searches, structured aggregation, and filtering large tool results before they consume model context.

An MCP server with the default codemode exposure can activate it automatically. To enable Codemode for every session without depending on an MCP server, add it to ~/.pi/agent/settings.json or a trusted project’s .pi/settings.json:

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

For one invocation, remember that --tools replaces the full selection, so list every tool you need:

pi --tools read,bash,edit,write,codemode

The critical limitation is that QuickJS isolation does not automatically contain the effects of tools.bash(), file writes, or MCP calls. Tool calls completed before a script fails are not rolled back. Codemode is an orchestration and context-efficiency layer, not a substitute for an operating-system sandbox.

Practical workflow 1: Reduce several logs to evidence-backed hypotheses

The goal is to avoid placing entire large logs into model context. Mount a limited log directory read-only inside a container, define the file set and time window, and ask Codemode to run independent reads in parallel. The script can return only matching error lines, surrounding context, file names, and timestamps. Review for missing files, timezone consistency, source locations, and a clear separation between observed evidence and inferred causes. If logs are sensitive, confirm what data the chosen model provider receives.

Practical workflow 2: Compare documentation through an MCP server

Connect a documentation server with codemode or deferred exposure. Define the comparison fields in advance, such as supported operating systems, authentication methods, minimum versions, and licensing. Ask the agent to include only facts that retain a source URL and access date. The reviewer should verify that each table cell maps to the cited current document. Since the workflow is read-only, keep write and destructive tools hidden.

Practical workflow 3: Route planning and implementation through a virtual model

Pi extensions can register a virtual model that selects different models by stage. A planning stage might use a model suited to long context, while an implementation stage uses one focused on code editing. Supply the goal, protected paths, test commands, and cost limits. Keep the plan and the actual diff as separate outputs, then inspect /session for per-model cost and cache usage. This is flexible, but extension code can inspect prompts, tool calls, files, credentials, and session history, so load only code you have reviewed and trust.

Security checklist: project trust is not a sandbox

• Assume Pi can reach anything accessible to the operating-system user that launched it.
• Open untrusted repositories in a container, VM, sandbox, or dedicated user account and expose only required paths.
• Use narrowly scoped, short-lived credentials and keep them outside the execution environment when possible.
• Inspect .pi/extensions, .pi/mcp.json, and .pi/settings.json before trusting a project.
• Treat AGENTS.md files, code comments, command output, and remote content as possible prompt-injection inputs.
• Review extensions and package installers because they can run with Pi’s process permissions.
• Confirm important changes with Git diffs, tests, and recoverable backups.

Project trust reduces the risk that a folder silently loads executable extensions or MCP configuration at startup. It does not restrict what enabled tools can access after Pi begins running. Pi’s security documentation explicitly notes that watching the transcript and reviewing changes do not create a security boundary.

Troubleshooting

The pi command is missing

Open a new terminal and try pi --version. For an npm installation, verify Node.js 22.19 or newer and confirm that the global executable directory is on PATH. A Nix installation is updated with Nix commands rather than pi update.

An MCP server will not connect

Run pi mcp list first. Check invalid JSON, missing executables, unset environment variables, and required OAuth login. Inside a session, /mcp shows the full connection error and the end of stderr from a failed stdio server. Pi retries some transient network failures, but tool calls themselves are not retried automatically because the server may already have performed the action.

Too many tools are visible

Lower the server’s default exposure to codemode or deferred. Promote only a few frequently used read tools to direct, and hide destructive patterns. Confirm the effective result with pi mcp list and the Tools view under /mcp.

A Codemode script produces too much output or fails midway

Filter and aggregate before returning data instead of accumulating everything. Finish read and validation stages before bundling writes, because external tool calls completed before a failure may remain in effect. Store large results in a file through a tool and return a summary plus the path.

When Pi Durable becomes relevant

The standard Pi coding agent is designed for one person steering a terminal session. Pi Durable targets applications that must checkpoint every step, resume after a crash, run many conversations concurrently, or let several clients observe and steer the same work. It includes storage and task machinery for long-running agents, but as of October 5, 2026 it is explicitly experimental and its API may change. Learn the stable agent’s folder, model, MCP, and permission boundaries first, then evaluate Durable in a separate prototype.

Bottom line

Pi 1.0 is compelling because it does not try to preinstall every possible workflow. It provides a small terminal agent and lets you assemble MCP, Codemode, extensions, and model routing as needed. A sensible adoption sequence is installation, working-directory verification, provider login, a read-only check, MCP validation, minimal tool exposure, and operating-system isolation. Above all, keep the boundary between the QuickJS Codemode sandbox and the real permissions of the tools it invokes clear.

Official sources

• Earendil: Pi 1.0
• Pi Documentation: Quickstart
• Pi Documentation: MCP Servers
• Pi Documentation: Codemode
• Pi Documentation: Security
• Earendil: Pi Durable

Sources checked October 5, 2026.

한국어: Pi 1.0 사용법: MCP·Codemode 설정과 안전한 확장 가이드