pi-session-mcp

A local, stdio-only Model Context Protocol (MCP) server that lets a coding agent such as Codex or Claude Code delegate work to a Pi coding-agent session, under rules that the operator sets.

The client never chooses a directory, a model or a permission level. It selects from workspace and execution-profile aliases that you define in a local configuration file, starts a session, sends prompts, polls the turn and closes the session. Pi Session MCP embeds the Pi SDK, keeps all state in memory and talks only over stdin and stdout.

Pi Session MCP is an independent project. It is not affiliated with or endorsed by the makers of Pi, OpenAI or Anthropic. Product names are used only to describe compatibility.

Why use it

Codex and Claude Code are good at driving a task. Pi is a coding agent that runs against many model providers, including local OpenAI-compatible endpoints. Pi Session MCP connects the two: your main agent stays in charge and hands selected work to a Pi session that you configured.

Reasons to do that:

• A second model without leaving your agent. A read-only Pi session on another model can review a change, answer a question about a codebase or give a second opinion. The main agent asks, polls and reads the answer.

• Bulk reading stays out of the main context. The Pi session does the exploring. Only its final answer returns to the client, capped at 64 KiB, so the main agent's context stays small.

• Delegated work on a model of your choice. An execution profile binds a provider, a model and a thinking level. Routine work can go to a local or cheaper model while the main agent keeps the hard parts.

• Follow-up turns keep their context. A session stays open across prompts, so a follow-up question does not pay for the same exploration twice.

• You set the limits, not the agent. The client can only pick from the workspaces and profiles in your configuration file. It cannot name a directory, a model, a provider or a permission level, and the default profile is read-only.

• Exactly the extra tools a task needs. A profile can grant individual tools of local stdio MCP servers to its sessions, and nothing else from those servers.

• Role instructions you control. A profile can select Pi skills from a catalog in your configuration, such as the implementation and review skills this package ships, or your own versions of them. The client cannot choose skills. The package also ships an orchestration skill for the controlling agent, which setup installs into Claude Code and Codex.

• Predictable to automate. Sessions and turns have a small set of states and stable error codes. Results contain no paths, credentials, prompts or raw provider errors.

• Small footprint. No daemon, no network listener and no stored state. An offline doctor checks an installation, and setup registers, verifies and removes the server reproducibly.

It is not the right tool when:

• you want to work with Pi yourself. Run Pi directly;

• you need remote access, several users or sessions that survive a restart. These are out of scope by design;

• you need to contain untrusted code. A coding profile limits Pi's tools, but it is not an operating-system sandbox.

Related MCP server: pi-cli-mcp

Status

The package version is 0.11.1.

Since 0.9.0, per-repository execution modes make host writes explicit and block host coding for container/read-only aliases, and setup provisions, accepts, collects and resets rootless-Podman container writers on Linux.

• Pre-1.0. The public tool contract is stable within a minor line: a change to tools, fields, states or error codes needs a new minor release.

• Linux and macOS, Node.js 22.19.0 or newer. macOS is tested in CI on macOS 15 and 26 on Apple silicon; Intel Macs run the same code but are untested. Setup acceptance on a real Mac is recorded for Claude Code only; Codex is still pending. See Acceptance. On other platforms setup refuses with platform_unsupported.

• Clients: Codex CLI and Claude Code. The setup command does not pin client versions: it accepts a client whose public mcp command output matches the expected contract and fails closed otherwise.

• Out of scope by design: HTTP, a web UI, persistence, resume, remote access and multi-user behavior. One trusted local MCP peer talks to one server process.

• Not a sandbox. A coding profile restricts the Pi tools that a session may use. It does not isolate the process from the operating system.

• Acceptance. Every release passes the provider-free checks. The last live two-client acceptance (Level 3) ran on Pi SDK 1.1.0 with one provider pair on Linux and has not been repeated on later SDK pins; see Acceptance.

How it works

Codex or Claude Code  ──MCP over stdio──▶  pi-session-mcp  ──embedded Pi SDK──▶  Pi session  ──▶  model provider
      (client)                           (this server)                      (in memory)

The client starts node dist/main.js as a child process. Pi Session MCP reads its configuration once, exposes eight tools, and runs Pi sessions inside that process through the embedded Pi SDK. Pi's existing local authentication is reused and never stored, printed or returned.

The tool contracts define every field, state and error code.

Quick start

npm install -g pi-session-mcp@<version>

mkdir -p "$HOME/.config/pi-session-mcp"
cp "$(npm root -g)/pi-session-mcp/pi-session-mcp.example.json" "$HOME/.config/pi-session-mcp/pi-session-mcp.json"   # then edit it
chmod 600 "$HOME/.config/pi-session-mcp/pi-session-mcp.json"
export PI_SESSION_MCP_CONFIG="$HOME/.config/pi-session-mcp/pi-session-mcp.json"

pi-session-mcp-doctor
pi-session-mcp-setup --dry-run --target claude-code:user:pi-session-mcp
pi-session-mcp-setup --apply --target claude-code:user:pi-session-mcp
pi-session-mcp-setup --verify --target claude-code:user:pi-session-mcp

Use codex:user:pi-session-mcp for Codex. The example configuration contains placeholders only: replace the workspace, provider and model with real local values, and never add credentials to the file. The example also registers the two worker skills with builtin: references, which resolve to the skills in the package, so the copied example needs no path edits for skills (see Pi skills).

--apply registers the server and also installs the controller skill pi-session-orchestration for that client, so the agent knows how to drive Pi worker sessions: Claude Code user and local get ~/.claude/skills/, Claude Code project gets .claude/skills/ of the project, and Codex gets ~/.agents/skills/. Setup never replaces a skill it did not install or that you modified. To adjust a skill, copy it into the override directory next to your configuration file and edit the copy:

pi-session-mcp-setup --apply --customize-skill pi-session-review

To add a skill of your own, create skills/<name>/SKILL.md next to the configuration file and reference it as builtin:<name>. Do not edit the installed package or the installed copy in the client.

pi-session-mcp-doctor is an offline health check. pi-session-mcp-setup plans by default, changes a client registration or skill only with an explicit operation, and never replaces an existing divergent registration or a skill it did not install. Neither needs credentials, a provider or a model.

The installation guide also covers installing from a release tag with the exact locked dependency tree, the configuration rules, existing registrations, configuration changes, upgrades and removal.

Configuration

{
  "workspaces": {
    "my-project": "/absolute/path/to/my-project"
  },
  "executionProfiles": {
    "safe-readonly": {
      "default": true,
      "permissionProfile": "read-only",
      "provider": "your-configured-provider",
      "model": "your-configured-model",
      "thinkingLevel": "medium"
    }
  }
}

• A workspace alias maps to a directory. Clients can select aliases only.

• An execution profile binds a permission profile (read-only or coding), a provider, a model and a thinking level. Exactly one profile is the default, and it must be read-only.

• A profile can grant individual tools of local stdio MCP servers to its sessions; see External MCP tools in embedded sessions.

• An optional top-level skillCatalog maps skill aliases to builtin:<name> (a skill of the package or of your override directory) or to a SKILL.md file, and a profile's optional skills selects aliases from it. A profile without skills gets no skills. See Pi skills.

• An optional top-level "events": { "delivery": "spool" } turns on content-free turn events, so that a Claude Code hook can wake the controller when a turn ends instead of polling. It is off by default and changes nothing for Codex. See Wake the controller.

• The server reads the file once at startup. Start a new client session after changing it.

Run it by hand

pi-session-mcp          # npm installation
npm start               # release checkout

This starts the server on stdin and stdout. PI_SESSION_MCP_CONFIG must name the configuration file; the server never looks for one in its working directory. Do not type ordinary text into the process and do not redirect diagnostics to stdout: stdout carries MCP frames only.

To explore the tools without a coding agent, use the pinned MCP Inspector:

npm run build
npm run inspect

Listing tools and testing input validation needs no provider credentials. An accepted prompt needs existing local Pi authentication and an available provider and model.

Inspector 2.x keeps its server catalog in ~/.mcp-inspector/. Without an OS keychain it also stores secrets there unencrypted; MCP_INSPECTOR_SECRET_STORE=memory keeps them in memory only.

Security model

• Local and single-peer. No network listener, no daemon between client sessions, no persisted session state.

• Aliases instead of paths. No tool accepts a working directory, a model, a provider or a credential.

• Explicit policy file. The configuration path comes only from PI_SESSION_MCP_CONFIG. A file in the working directory, which is the client's project, is never read as configuration.

• Sanitized results. Public errors are stable codes. They contain no paths, prompts, provider errors, authentication data or credential locations. assistantText can repeat workspace content and must be treated as sensitive.

• Fail closed. Unknown fields, unknown aliases, unexpected client output and divergent registrations are rejected, not repaired.

• Bounded waiting. Session creation, prompt acceptance, abort, close and shutdown have fixed server-side deadlines.

The threat model states the assumptions and the limits, including what a coding profile does not protect against.

Documentation

Operate:

• Installation

• Client setup reference: manual registration, the tool flow, deadlines and troubleshooting

• External MCP tools in embedded sessions

• Pi skills in execution profiles

• Changelog

Contract and design:

• Tool contracts

• Architecture

• Threat model

• Setup lifecycle design

• Doctor contract

• ADR 0001: stdio first

• ADR 0002: embedded Pi SDK

• ADR 0003: no new feature phase after the MVP

• ADR 0004: setup accepts clients by contract, not by version

• ADR 0007: execution profiles select Pi skills from an operator catalog

• ADR 0011: turn events and controller wake

Maintain:

• Acceptance

• Synthetic profile evaluation: current results, provider-free harness and gated live plan

• Maintenance roadmap

• Post-0.8.1 audit and backlog snapshot

• Releasing

• Contributing

• Security policy

Development

npm ci
npm run typecheck
npm run build:cli
NODE_OPTIONS=--unhandled-rejections=strict npm test
npm run build

These are the checks that CI runs, with the same strict handling of unhandled promise rejections. Tests use a fake Pi adapter or a scripted model and need no provider credentials. Every direct dependency is pinned exactly, and the lockfile is committed. The project rules for contributors and coding agents are in AGENTS.md.

The Pi SDK moves quickly, so a nightly canary checks the unchanged sources against the newest published SDK without touching the pin. Releasing describes how to update the pin, record a client contract, patch audit advisories and prepare a release.

License

MIT