pi-subagent-mcp
This MCP server exposes pi as a sub-agent for coding assistants, letting you spawn, drive, monitor, and attach to pi sessions.
Run tasks:
pi_dispatchspawns a pi session on a task in a given cwd, with optional model override, project approval, and interactive dialog handling.Send messages:
pi_sendmessages a task in auto/prompt/steer/followUp modes.Monitor progress:
pi_statusgives lightweight state;pi_readdoes incremental event-buffer reads;pi_waitblocks until finish, dialog, or timeout and returns a summary.Handle dialogs: With interactive sessions, UI dialogs appear as
pendingRequest; answer them withpi_respond(value/confirm/cancel).Control sessions:
pi_abortcancels the current operation,pi_closekills the process, andpi_listenumerates all tasks.Attach to terminal pi:
pi_bridgesfinds bridge-enabled pi sessions;pi_attachattaches to one,pi_notifypushes text to its TUI, andpi_detachdisconnects while leaving it alive.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pi-subagent-mcp Ask pi to review the current code and report any issues"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
pi-subagent-mcp
MCP server that exposes pi (pi --mode rpc)
as a sub-agent for MCP-capable coding assistants (e.g. Kimi CLI).
Build
npm install
npm run buildRelated MCP server: pi-sylvan
Tools
Tool | Purpose |
| Spawn a pi session on a task ( |
| Message a task ( |
| State, streaming flag, last assistant text, current tool, |
| Incremental event buffer read ( |
| Block until the run finishes or a dialog needs answering; returns last assistant text + progress snapshot ( |
| Answer a |
| Abort current operation; session stays alive |
| Kill the process, drop the task |
| All tasks |
| List pi sessions running elsewhere (e.g. in a terminal) that have the bridge extension and can be attached |
| Attach to a bridge session ( |
| Disconnect an attached task; the pi session stays alive |
| Push text onto an attached pi's TUI console ( |
Extension UI dialogs (bidirectional interaction)
pi extensions can block on select/confirm/input/editor dialogs
(extension_ui_request). By default (interactive: true) the server surfaces these as
pendingRequest in pi_status/pi_wait — which returns early — and the caller answers
with pi_respond. With interactive: false (unattended runs) dialogs are auto-cancelled,
preserving the original behavior.
Note: project-local pi extensions (.pi/extensions/) only load when the project is
trusted — pass approve: true to pi_dispatch to grant that for the run. Also, pi
delays the command response for extension commands that block on a dialog; the server
therefore treats dialog activity as command acceptance so pi_dispatch/pi_send
return instead of deadlocking.
Attaching to terminal pi sessions (bridge)
pi's RPC mode is stdio-only, so a pi already running in your terminal cannot be
attached retroactively. The bridge extension solves this: installed once, every pi
session started afterwards (interactive TUI included) exposes a Unix socket at
~/.pi/bridge/<sessionId>.sock that this server can attach to.
Install (user scope, loads in every pi session):
pi install /absolute/path/to/extensions/bridge.tsThen from any MCP client:
pi_bridges → discover running sessions
pi_attach { sessionId } → get a taskId; pi_send / pi_wait / pi_read /
pi_status / pi_abort work as usual
pi_notify { taskId, message } → text appears on that pi's TUI console
pi_detach { taskId } → disconnect; the terminal session stays aliveLimitations: sessions started before the install can never be attached; attached
sessions answer their own extension dialogs in their terminal (no pendingRequest);
session replacement (/new, /resume) ends the attachment (re-attach via
pi_bridges); Unix sockets only (no Windows named pipes). See
docs/design/terminal-bridge.md.
Configuration
Environment variables:
PI_SUBAGENT_SESSION_DIR— where pi session files are stored (default:.pi-subagent/sessions/next to the package).PI_SUBAGENT_PI_PATH— override the pi binary path (default:pi).
MCP registration (example): point your client at node /path/to/dist/src/server.js.
Test
npm test # unit + smoke + (if pi is installed and logged in) integrationAdditional end-to-end scripts in scripts/ (acceptance-test.mjs,
mcp-e2e-test.mjs, dialog-e2e-test.mjs, bridge-e2e-test.mjs). Issues found during development are
logged in docs/issues/; design notes in
docs/design/.
Available Tools
9 toolspi_abortB
Abort the pi task's current operation. The session stays alive; you can keep sending messages.
Inputs: taskId (required).
pi_closeA
Terminate the pi process and remove the task from the registry. Session files stay on disk.
Inputs: taskId (required).
pi_dispatchA
Dispatch a task to a new pi sub-agent session (spawns pi --mode rpc in cwd). Returns immediately with a taskId; use pi_wait to block for the result or pi_read to inspect progress.
Inputs: cwd (required), task (required), name, model, +2 more.
pi_listA
List all pi tasks and their states.
Inputs: no named parameters.
pi_readA
Read buffered events of a pi task (tool calls, message updates, etc.). Pass 'since' = the latest seq you already saw for incremental reads.
Inputs: taskId (required), limit, since.
pi_respondA
Answer a pending UI dialog reported as 'pendingRequest' by pi_status/pi_wait. Pass 'value' for select/input/editor, 'confirmed' for confirm, or 'cancelled: true' to dismiss.
Inputs: taskId (required), requestId (required), value, cancelled, +1 more.
pi_sendA
Send a message to a pi task. mode 'auto' (default): direct prompt when idle, steering message while it is working. 'followUp' queues until the agent fully stops.
Inputs: taskId (required), message (required), mode.
pi_statusA
Lightweight status of a pi task: state, streaming flag, last activity, last assistant text, current tool. Includes 'pendingRequest' when pi is blocked on a UI dialog awaiting pi_respond.
Inputs: taskId (required).
pi_waitA
Block until the pi task's current run finishes (state idle/aborted/error), a UI dialog needs answering, or timeoutMs elapses. Returns the final state, the last assistant text in 'summary', and 'pendingRequest' when pi is waiting for pi_respond.
Inputs: taskId (required), timeoutMs.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
pi_status, pi_read, and pi_wait all concern state but are clearly differentiated as snapshot, event stream, and blocking wait respectively. pi_dispatch and pi_send are also distinct (create new vs. message existing). No two tools appear to do the same thing.
All nine tools are prefixed with pi_ and use lowercase imperative-style names (dispatch, send, read, wait, respond, abort, close, list). The only mild outlier is pi_status, which uses a noun rather than a verb, but it still fits the established pattern and creates no confusion.
With nine tools, the server is in the ideal range for its purpose. Each tool addresses a specific aspect of the subagent lifecycle without redundancy or bloat.
The set covers the full workflow: dispatch to create, send to communicate, status/read/wait to observe, respond to handle dialogs, abort to interrupt, close to clean up, and list to enumerate. There are no missing operations that would trap an agent mid-workflow.
Maintenance
Related MCP Connectors
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Related MCP Servers
- AlicenseCqualityCmaintenanceEnables MCP hosts to delegate coding tasks to Pi CLI as a programmable sub-agent with session tracking and process management.73MIT
- AlicenseNot gradedqualityCmaintenanceExposes Sylvan's MCP tools to a Pi coding agent, enabling management of spaces and developer shells.MIT
- AlicenseNot gradedqualityCmaintenanceAn MCP bridge for the Pi coding agent running in WSL, enabling task execution, research, review, and session management through MCP.MIT
- AlicenseNot gradedqualityDmaintenanceEnables Claude Code to delegate coding implementation and testing to a local pi agent via MCP tools, including dispatching task books, monitoring status, steering or aborting runs mid-execution, and retrieving results and transcripts.4MIT