$ cat ~/map/pi-mcp.md

pi-mcp

An MCP server that runs and supervises pi agents over RPC: caged processes, hot resume, rip/resurrect, and agent chaining.

tools✓ Nov 2

Facts

repository: github.com/sr9000/pi-mcp ↗
GitHub Stars: ★ 0
Forks: 0
license: MIT
npm / mo: —
last push: Nov 1, 2026

install

uv sync --extra dev, then start with PI_MCP_DB, PI_MCP_AGENTS_DIR and PI_MCP_ACCESS_TOKEN set: uv run pi-mcp (stdio is the default transport; add --transport streamable-http --host 0.0.0.0 --port 8000 for HTTP). The run tool needs pi and bubblewrap on the host.

## TL;DR

A Python MCP server for running and supervising pi coding agents over pi's RPC mode: bubblewrap-caged pi processes stay alive between turns, an MCP client starts, prompts, rips, and resurrects agents through tools like run, send_message, and resurrect, and chained agents call back through scoped child mounts and per-agent tokens.

## Key points

$Keeps a pi --mode rpc process alive between turns (hot resume); an explicit resurrect cold-resumes a ripped or exited agent from its session file using the stored provider, model, context_size, mount rules, token group, and callback target, none of which can be overridden.
$Agents are bubblewrap-caged pi processes with SQLite-backed state, normalized mounts, idle keep-alive, and lifecycle counters for rips, retries, and self exits.
$Twelve MCP tools cover the lifecycle: list, get_info, run, rip, resurrect, send_message, remove, grep, list_tmp, grep_tmp, read_tmp, and read for the stdout or errors log.
$One public state per agent: active (turn running), idle (live and settled), ripped (explicitly stopped, session resumable), or exited (ended on its own, session resumable); a background refresh thread tracks live agents on a configurable pause.
$Per-agent context budgets: run(context_size=...) takes a minimum of 20,000 tokens and writes a private pi-agent/models.json whose window is context_size plus headroom, so pi autocompaction triggers before the projected context overflows.
$Chained agents receive AGENT_ID, can start children with callback_agent_id, and get a generated /tmp/pi-agent/mcp.json pointing at a loopback endpoint with a per-agent bearer token; child mounts are narrowed to the parent's grants and validation is transitive.
$Artifacts live under PI_MCP_AGENTS_DIR: stdout.log, errors.log, agent_session.jsonl, and a tmp/ directory bind-mounted at /tmp; read and list paths are scoped to that tmp/, and traversal or symlink escapes are rejected.
$Per-request HTTP auth on the main transport is not implemented yet — the transport process is bound to one PI_MCP_ACCESS_TOKEN; minted child tokens are mode 0600, never returned by tools, not stored in SQLite, and revoked on exit, rip, or remove.

## FAQ

Q How does it relate to Pi MCP Adapter?

They run in opposite directions: Pi MCP Adapter lets pi use MCP servers as tools without burning context, while pi-mcp exposes pi agents themselves to an MCP client, which starts and supervises them over RPC.

Q What does the host need to run agents?

The run tool needs pi and bubblewrap (bwrap) on the host; pi-mcp-fake can still seed fake sessions for trying the server without them.

Q Can a ripped agent be brought back?

Yes — resurrect starts a new process for the same agent id and session using the stored properties, which cannot be overridden; with a prompt it starts that turn immediately, without one it returns idle. send_message still requires a running process, so resurrect first.

Q Can a caged agent call the server itself?

Yes — each agent gets a generated /tmp/pi-agent/mcp.json pointing at a loopback endpoint whose bearer token is minted for that agent and accepted nowhere else; set PI_MCP_CHILD_MCP=0 to disable the child endpoint.

Q How do I read what an agent did?

read selects the stdout or errors log, grep proxies the host grep against a log stream, and list_tmp, grep_tmp, and read_tmp inspect the forwarded /tmp tree, scoped to that agent.

## References

## Related entries

## Guides

Last updated: Nov 1, 2026