pi-mcp

MCP server that lets Claude Code delegate work to non-Claude models (GPT-5.5, Gemini 3.1 Pro, and others) through pi, billed to a flat-rate subscription.

Why

Claude Code can only ever ask another Claude. Every subagent it spawns shares the same training, the same blind spots, the same failure modes, so three of them agree with each other more than the evidence warrants. For research and adversarial review, that correlation is the enemy.

The cost saving is secondary. The point is model diversity. A GPT-5.5 and a Gemini 3.1 Pro reviewing Claude's work will surface things Claude structurally will not.

Related MCP server: claude-code-codex-agents

Features

pi_ask parameters

Use output_file for anything long. A four-model research fan-out returning inline costs the caller tens of thousands of tokens of context. Returning a path costs a few hundred.

Prerequisites

• pi, authenticated (pi --list-models prints a table)

• bun

• uvx for mcp-server-fetch, the official keyless URL-to-markdown server

• A GitHub Copilot or ChatGPT subscription connected to pi

Installation

1. Clone and install:

   git clone https://github.com/SShadowS/pi-mcp.git
   cd pi-mcp
   bun install

2. Register with Claude Code:

   claude mcp add pi -s user -- bun --no-env-file run <path-to>/pi-mcp/src/pi-server.ts

   Keep --no-env-file. Claude Code starts the server in your project directory, and without the flag Bun loads that project's .env into the server. pi then inherits those keys.

3. Set a search API key (see Configuration). Restart your terminal so child processes inherit it.

Usage

From Claude Code, once registered:

pi_models()
pi_ask({
  model: "gpt-5.5",
  prompt: "Review U:/Git/myrepo/src/parser.ts for off-by-one errors.",
  output_file: "U:/tmp/gpt-review.md"
})

Run /mcp reconnect pi (or restart Claude Code) after any change to src/. Until then, tool results carry a warning that old code answered.

Configuration

Keys are read from the environment, or from a gitignored .env at the repo root (copy .env.example). They are never stored in the repo. Without a key, fetch still works and search reports plainly that it is unavailable.

[Environment]::SetEnvironmentVariable("SERPER_API_KEY", "<your-key>", "User")

Choose the provider per registration:

claude mcp add pi -s user -e PI_MCP_PROVIDER=openai-codex -- bun --no-env-file run <path-to>/pi-mcp/src/pi-server.ts

Model ids differ per provider, so call pi_models after switching. openai-codex models have a 272K context, smaller than Copilot's.

Which config serves which consumer

fetch and search must never go in a project's .mcp.json. Claude Code reads those, and Claude already has WebSearch and WebFetch.

Architecture

Claude Code
  |
  v  (stdio, MCP)
pi-server.ts            pi_ask / pi_models / pi_cleanup
  |
  v  spawn, cwd = pi-workspace/, --tools read,mcp, prompt on stdin
pi (sub-agent, GPT-5.5 / Gemini / ...)
  |-- read              absolute paths only
  |-- mcp -> fetch      uvx mcp-server-fetch
  |-- mcp -> search     search-server.ts (Serper / SerpAPI)

Why pi always runs in pi-workspace/

pi discovers MCP servers from exactly one place: the .mcp.json in its working directory. Not its own settings file, not ~/.mcp.json. And pi has no built-in web access, only an mcp gateway tool. So pi can reach the web if and only if its cwd holds a .mcp.json wiring one up.

runPi always spawns pi in pi-workspace/. Run it anywhere else and it silently loses the web: pi reports no error, it simply has no servers. That is why pi_ask has no cwd parameter, and why callers must pass absolute paths.

Putting fetch/search into each target repo's .mcp.json was rejected. Claude Code reads those too, and it would mean committing a search server into every repo pi is pointed at.

The leash, and why it is probed

--tools read,mcp restricts the sub-agent, but pi's --tools allowlist fails open: unknown tool names are silently ignored. A typo would change the boundary and error nowhere. The only proof is asking pi to cross it and watching it fail, which is what test/leash.test.ts does.

Accepted risk

Read access plus web reach is, in principle, an exfiltration path: a model can read a file and then fetch a URL with the contents in the query string. This is inherent to letting it read the code and reach the internet. It is accepted, not mitigated. Point this at code you would be relaxed about open-sourcing.

Sharp edges

Tests

bun test
bun run typecheck

test/leash.test.ts hits the real Copilot API deliberately (~30s). A mock would prove nothing about a security boundary.

Key Files

Author: Torben Leth (SShadowS@SShadowS.dk) License: MIT (see LICENSE)