pi-delegate-mcp

██████╗ ██╗    ██████╗ ███████╗██╗     ███████╗ ██████╗  █████╗ ████████╗███████╗
██╔══██╗██║    ██╔══██╗██╔════╝██║     ██╔════╝██╔════╝ ██╔══██╗╚══██╔══╝██╔════╝
██████╔╝██║    ██║  ██║█████╗  ██║     █████╗  ██║  ███╗███████║   ██║   █████╗
██╔═══╝ ██║    ██║  ██║██╔══╝  ██║     ██╔══╝  ██║   ██║██╔══██║   ██║   ██╔══╝
██║     ██║    ██████╔╝███████╗███████╗███████╗╚██████╔╝██║  ██║   ██║   ███████╗
╚═╝     ╚═╝    ╚═════╝ ╚══════╝╚══════╝╚══════╝ ╚═════╝ ╚═╝  ╚═╝   ╚═╝   ╚══════╝
                            ███╗   ███╗ ██████╗██████╗
                            ████╗ ████║██╔════╝██╔══██╗
                            ██╔████╔██║██║     ██████╔╝
                            ██║╚██╔╝██║██║     ██╔═══╝
                            ██║ ╚═╝ ██║╚██████╗██║
                            ╚═╝     ╚═╝ ╚═════╝╚═╝

MCP-Server, der den pi Coding-Agent als delegierbaren, steuerbaren Worker bereitstellt.

Richte Claude Code (oder einen beliebigen MCP-Host) darauf aus und delegiere Arbeiten an einen von pis ~38 Providern (DeepSeek, Grok, GLM, Kimi, Qwen, Codex, OpenRouter, lokales llama.cpp) – wobei der Kontext des Sub-Agenten außerhalb deiner Hauptkonversation bleibt.

Wofür es gedacht ist

Dein Haupt-Harness läuft auf einem teuren Modell mit einem Kontextfenster, das dir wichtig ist. Vieles von dem, was er tut, braucht dieses Modell nicht und schadet dem Kontext sogar aktiv: ein Repository nach jeder Aufrufstelle zu durchsuchen, eine 2000-Zeilen-Datei zu lesen, nur um eine Frage zu beantworten, zu prüfen, was ein Refactoring hinterlassen hat.

Übergib diese Arbeit stattdessen einem Delegaten:

• Kosten. Die Fleißarbeit läuft auf DeepSeek, GLM, Kimi, Qwen oder einem lokalen llama.cpp. Du bezahlst Frontier-Preise nur für das Denken, das sie wirklich braucht.

• Kontext. Der Delegat liest die Dateien mit seinem eigenen Budget und liefert ein Ergebnis. Die 200 KB, die er gelesen hat, gelangen nie in deine Konversation.

• Schadensradius. Delegaten sind standardmäßig schreibgeschützt (read, grep, find, ls), durchgesetzt beim Aufbau der Session. Ein günstiges Modell, das Erkundungsarbeit leistet, kann deinen Baum nicht anfassen, wenn du es nicht aktiv erlaubst.

Der Delegat ist immer der pi-Agent. Codex, Grok, DeepSeek und die übrigen liefern das Modell dahinter; dies ist kein Wrapper um ihre CLIs.

Related MCP server: handoff-mcp

Warum pi und nicht opencode oder ein CLI-Wrapper?

Ein Delegat ist nur dann steuerbar, wenn zwei Kanäle offen bleiben: Du musst ihn mitten in der Aufgabe umleiten können, und er muss dir eine Frage stellen und warten können, bis du antwortest. Die meisten Methoden, einen Coding-Agenten aus einem anderen Programm heraus anzusteuern, schließen beide.

pi -p und --mode json setzen ctx.hasUI = false. Ein so gestarteter Delegat ist konstruktionsbedingt Feuer-und-vergessen: Er kann keine Frage stellen, und du kannst ihn nicht umleiten.

Das SDK von opencode ist ein typisierter Client für einen eigenen Serverprozess: createOpencode() startet opencode serve und kommuniziert per HTTP mit ihm. Sauberes Design, aber es bedeutet einen zweiten Prozess, den man überwachen muss, und die Session-Oberfläche, die es bereitstellt (prompt, abort, revert, messages), bietet keine Steuerung während eines Turns und keinen Weg für den Agenten, den Aufrufer etwas zu fragen.

pi liefert createAgentSession als einbettbare Bibliothek. Dieser Server hält das Session-Objekt prozessintern, sodass session.steer() eine Nachricht nach dem aktuellen Tool-Aufruf und vor dem nächsten Modell-Aufruf platzieren kann, und ein synthetischer uiContext fängt die Fragen des Agenten ab und hält sie für answer bereit. Es wird nichts per Shell aufgerufen; nichts muss überwacht werden.

* Fragen stammen aus pi-Erweiterungen, daher ist dieser Kanal nur für Delegaten geöffnet, die mit extensions: true gestartet wurden. Siehe Websuche und andere Erweiterungs-Tools.

(Die Tabelle vergleicht den Delegationskanal, nicht die Sandboxing-Fähigkeiten; opencode hat seine eigene Berechtigungskonfiguration. Siehe Standardmäßig schreibgeschützt dafür, was dieser Server durchsetzt und was nicht.)

Tools

Installation

Erfordert Node.js 22.19+ und eine funktionierende pi-Installation, die einmal angemeldet wurde (pi, dann /login).

Claude Code

claude mcp add pi -e PI_DELEGATE_MODEL=openrouter/stealth/ox-alpha -- npx -y pi-delegate-mcp

Beliebiger MCP-Host, über .mcp.json

{
  "mcpServers": {
    "pi": {
      "command": "npx",
      "args": ["-y", "pi-delegate-mcp"],
      "env": { "PI_DELEGATE_MODEL": "openrouter/stealth/ox-alpha" },
      "timeout": 1800000
    }
  }
}

npx löst das Paket bei jedem Start auf. Um es festzulegen, installiere es global und rufe das Binary direkt auf:

npm install -g pi-delegate-mcp

{ "mcpServers": { "pi": { "command": "pi-delegate-mcp", "timeout": 1800000 } } }

Halte den Server-Schlüssel kurz, da er jedem Tool-Namen vorangestellt wird (mcp__pi__spawn).

Aus dem Quellcode

git clone https://github.com/howznguyen/pi-delegate-mcp && cd pi-delegate-mcp
npm install && npm run build && npm link

Erster Start

Bitte deinen Agenten, etwas zu delegieren. Er ruft einmal init auf, um zu erfahren, was dieser Server erreichen kann, und dann spawn:

{ "id": "audit-01", "label": "who still imports onnxruntime",
  "prompt": "Search this repo for anything still importing onnxruntime and list the files.",
  "cwd": "/path/to/repo" }

{ "sessionId": "audit-01", "state": "running", "model": "opencode-go/deepseek-v4-flash",
  "activeTools": ["read", "grep", "find", "ls"] }

spawn kehrt sofort zurück. Frage mit status nach der geordneten Tool-Spur und der Antwort ab, oder mit sessions, wenn mehrere unterwegs sind. Wenn init fehlschlägt, sagt er genau, was fehlt: pi nicht installiert, kein Provider angemeldet oder ein Modell-Scope, der nichts findet.

Die Modellnamen in den Beispielen unten sind beispielhaft. Führe models aus, um zu sehen, was deine eigene pi-Installation tatsächlich erreichen kann.

Nachvollziehbarkeit

spawn und run akzeptieren beide deine eigene id und ein Freitext-label:

{
  "id": "search-audit-01",
  "label": "what ONNX removal left behind",
  "prompt": "...",
  "model": "opencode-go/deepseek-v4-flash"
}

IDs sind [A-Za-z0-9._:-], 1-64 Zeichen, müssen alphanumerisch beginnen und unter live Sessions eindeutig sein. Weglassen für eine UUID.

Beendete Sessions bleiben über status und sessions lesbar, anstatt zu verschwinden, sodass du zurückgehen und prüfen kannst, was ein Delegat tatsächlich getan hat. Die neuesten PI_DELEGATE_HISTORY (Standard 50) werden aufbewahrt; forget entfernt eine vorzeitig.

status liefert eine geordnete toolCalls-Spur: jedes Tool, das der Delegat ausgeführt hat, mit Argumenten und Zeitangaben. Füge verbose: true hinzu, um Aufruf-IDs und Ergebnisse zu erhalten:

{
  "seq": 1,
  "id": "call_467b4bb4…",
  "name": "bash",
  "state": "ok",
  "ms": 10,
  "args": "{\"command\":\"echo hello-trace\"}",
  "result": "hello-trace\n"
}

Argumente und Ergebnisse werden gekürzt (PI_DELEGATE_TRACE_ARGS, PI_DELEGATE_TRACE_RESULT), wobei die entfernte Länge festgehalten wird, sodass ein einzelnes read einer großen Datei deinen Kontext nicht überfluten kann.

Einem Delegaten einen weiteren Turn geben

Ein fertiger Delegat ist nicht verbraucht. pi behält seine Session im Speicher, sodass follow_up denselben Agenten erneut auffordert, wobei alles, was er bereits gelesen hat, weiterhin im Kontext ist:

{ "sessionId": "search-audit-01", "prompt": "Now check whether the build files reference it too" }

{ "sessionId": "search-audit-01", "state": "running", "turnsSoFar": 1 }

Der Delegat macht dort weiter, wo er aufgehört hat. Er hält immer noch die Dateien, die er im ersten Turn gelesen hat, sodass die zweite Frage einen Modell-Aufruf kostet statt einer neuen Session, die das Repository erneut liest.

Das ist der günstige Weg, eine Konversation mit einem Delegaten zu führen. Einen frischen zu spawnen bedeutet, die Aufgabe neu zu erklären und dafür zu bezahlen, dass er dieselben Dateien erneut liest – und seine Antwort kommt ohne die Überlegungen an, die dorthin geführt haben.

follow_up verweigert einen Delegaten, der noch arbeitet, denn einen mitten in der Aufgabe umzuleiten, ist das, wofür steer gedacht ist. Die beiden sind nicht austauschbar: steer landet zwischen Tool-Aufrufen bei einem laufenden Agenten, follow_up startet einen neuen Turn bei einem beendeten.

Fan-out

spawn_batch startet einen ganzen Stapel in einem Aufruf. Aufgaben erben die Stapel-Ebene von model, cwd, tools und extensions und überschreiben sie einzeln dort, wo es nötig ist:

{
  "idPrefix": "audit",
  "model": "opencode-go/deepseek-v4-flash",
  "cwd": "/repo",
  "tools": ["ls"],
  "tasks": [
    { "prompt": "What still imports onnxruntime?", "label": "imports" },
    { "prompt": "Which build files still reference ONNX?", "label": "build" },
    {
      "prompt": "Any ONNX model files left on disk?",
      "label": "artifacts",
      "model": "opencode-go/ox-alpha-free"
    }
  ]
}

Das benennt sie audit-01, audit-02, audit-03 und kehrt in wenigen Millisekunden zurück, da das Starten eines Delegaten nicht darauf wartet, dass er denkt.

Der Stapel wird validiert, bevor irgendetwas startet: ID-Format, innerhalb des Stapels doppelte IDs, bereits laufende IDs, blockierte Tools und jeder Modellname. Eine einzige schlechte Aufgabe lässt den Aufruf fehlschlagen und startet nichts. Ein halber Fan-out ist das schlechteste Ergebnis, denn du zahlst für die Delegaten, die gestartet sind, und musst trotzdem herausfinden, welche es nicht sind.

Frage den gesamten Stapel mit einem einzigen sessions-Aufruf ab, statt eines status pro Delegat. Wechsle nur für den Delegaten, den du tatsächlich lesen willst, zu status. steer und abort bleiben pro Session.

Modell pro Aufruf wählen

model überschreibt bei jedem Aufruf PI_DELEGATE_MODEL. Ein nicht auflösbarer Name ist ein harter Fehler, niemals ein stiller Rückfall auf das Standardmodell, denn ein stiller Rückfall ist der Weg, auf dem du am Ende ein Modell abrechnest, das du nie angefragt hast.

Welche Namen aufgelöst werden, entscheidet pis eigener enabledModels-Scope, den dieser Server durchsetzt und nicht nur anzeigt:

opencode-go/deepseek-v4-flash  -> ok      (listed in enabledModels)
opencode-go/glm-5.3            -> refused (out of scope)
knowns-hub/claude-opus         -> ok      (custom provider, see below)

Eigene Provider umgehen den Scope. Jedes Modell, das von einem Provider bedient wird, der in ~/.pi/agent/models.json deklariert ist, wird angeboten, selbst wenn enabledModels es nicht nennt – mit der Begründung, dass das manuelle Deklarieren eines Providers bereits eine Absicht ist, ihn zu nutzen. Deshalb kann die Liste viel länger sein als enabledModels: Drei Einträge im Scope plus zwei eigene Provider können leicht fünfzehn angebotene Modelle bedeuten. init sagt das explizit in models.scopeNote, wenn es zutrifft.

Zwei Schalter ändern das:

Rufe models auf, um zu sehen, was unter der jeweils geltenden Einstellung tatsächlich erreichbar ist.

Statuszeile

Claude Code erlaubt genau einen statusLine-Befehl, daher umschließt pi-delegate-statusline das, was du bereits ausführst, und fügt ein Segment hinzu, das die Delegaten dieses Workspace anzeigt:

{
  "statusLine": {
    "type": "command",
    "command": "PI_DELEGATE_STATUSLINE_WRAP=ccstatusline pi-delegate-statusline",
    "refreshInterval": 10
  }
}

Entferne PI_DELEGATE_STATUSLINE_WRAP, um nur das pi-Segment auszugeben.

π ▸ audit engine·t1·12s audit index·t2·8s   running, with turn counts and elapsed time
π ▸ migrate·t7·3m04s ?1 waiting             one delegate is blocked on a question
π ✓2                                        finished, nothing running

Welche Delegaten zu welcher Session gehören

Nur nach Verzeichnis zu filtern reicht nicht: Zwei Claude-Code-Sessions, die im selben Repository geöffnet sind, würden die Delegaten der jeweils anderen zeigen. Die Zuordnung verwendet stattdessen die Prozess-Abstammung.

Der MCP-Host startet einen Server pro Session, also zeichnet der Server process.ppid auf, die PID des Hosts. Die Statuszeile, die von demselben Host gestartet wurde, läuft durch ihre eigene Abstammung und behält nur die Zustandsdateien, deren hostPid sie dort findet. Gleiches Repo, zwei Sessions, kein Übersprechen. Der Verzeichnisfilter bleibt als Fallback für Zustandsdateien, die geschrieben wurden, bevor es das gab.

Der Zustand liegt in $XDG_STATE_HOME/pi-delegate-mcp/<pid>.json (PI_DELEGATE_STATE_DIR zum Verschieben). Dateien werden nur bei ESRCH entfernt, also wenn ihr Prozess nicht mehr existiert; EPERM bedeutet nämlich, dass der Prozess unter einem anderen Benutzer läuft. Server beenden sich außerdem von selbst, wenn stdin geschlossen wird oder die Host-PID verschwindet, sodass ein Host, der stirbt, ohne den Transport zu schließen, nichts hinterlässt.

Standardmäßig schreibgeschützt

Tools sind bei der Sitzungserstellung auf read, grep, find, ls beschränkt. Alles andere wird abgelehnt, bevor überhaupt eine Sitzung erstellt wird.

Um das zu erweitern, nenne die zusätzlichen Tools auf dem Server:

"env": { "PI_DELEGATE_ALLOW_TOOLS": "bash" }

oder PI_DELEGATE_ALLOW_WRITE=1, um alles zu erlauben.

bash ist kein Mittelweg. pi bringt kein Berechtigungssystem mit, also kann ein Delegate, der bash hält, Dateien schreiben, löschen und das Netzwerk erreichen, unabhängig davon, ob write und edit auf seiner Liste stehen. Diese beiden zu verweigern, während bash erlaubt ist, hält deine Absicht fest; es setzt nichts durch. Die Berechtigungsabfragen und Hooks von Claude Code sehen nie, was pi tut. Wenn du eine echte Grenze brauchst, führe diesen Server in einem Container aus.

Websuche und andere Erweiterungstools

Die eigenen Tools von pi sind read, grep, find, ls, bash, powershell, write, edit. Es gibt weder Suche noch Fetch darunter. Diese kommen von pi-Erweiterungen, die ihre eigenen Tools registrieren, und ein Delegate kann sie verwenden.

Setze extensions: true im Aufruf und erlaube die Toolnamen auf dem Server:

"env": { "PI_DELEGATE_ALLOW_TOOLS": "web_search,fetch_content" }

{ "prompt": "Find the current Node LTS version and tell me just the number",
  "extensions": true, "tools": ["read", "grep", "find", "ls", "web_search"] }

{ "seq": 1, "name": "web_search", "state": "ok", "ms": 2568,
  "args": "{\"query\":\"latest stable Node.js LTS version\",\"numResults\":5}" }

So gibst du einem Delegate Netzwerkzugriff, ohne ihm bash zu geben. web_search kann suchen und sonst nichts, und es durchläuft dieselbe Allowlist wie jedes andere Tool, also bleibt die Schreibschutz-Standardeinstellung für Aufrufe, die nicht darum bitten, unverändert.

Welche Tools existieren, hängt davon ab, was der Benutzer, der den Server ausführt, installiert hat. pi-web-access bietet web_search, fetch_content, source_check und get_search_content. pi-mcp-adapter überbrückt die MCP-Server in ~/.pi/agent/mcp.json und stellt sie als mcp bereit. pi hat keinen eigenen MCP-Client, daher ist diese Erweiterung der einzige Weg zu einem.

extensions: true vertraut jeder installierten Erweiterung, nicht nur der, die du wolltest. Sie werden als ein Set geladen, laufen mit den vollen Rechten des Prozesses dieses Servers, und einige öffnen Sockets und Timer, die die Sitzung überleben. Schalte es pro Aufruf ein, für die Delegates, die es brauchen, statt es standardmäßig anzulassen. Es kostet außerdem echte Startzeit, weshalb es aus ist, solange nicht darum gebeten wird.

Konfiguration

Langlaufende Aufgaben

Das MCP TypeScript SDK verwendet standardmäßig ein 60-Sekunden-Request-Timeout, das eine echte Aufgabe sprengen wird. Drei Verteidigungslinien, in der Reihenfolge der Bevorzugung:

1. Verwende spawn + status. Nichts blockiert, also greift kein Timeout.

2. run sendet regelmäßig Fortschrittsmeldungen, die das Timeout des Hosts zurücksetzen.

3. Erhöhe die Obergrenze mit "timeout" in .mcp.json oder MCP_TOOL_TIMEOUT in der Umgebung.

CLAUDE_AUTO_BACKGROUND_TASKS=1 veranlasst Claude Code, lange MCP-Aufrufe nach ~2 Minuten in den Hintergrund zu versetzen. Beachte, dass Fortschrittsmeldungen verworfen werden, sobald ein Aufruf in den Hintergrund verschoben wird, also wähle (1) oder (3), nicht beides.

Authentifizierung

Der Server verarbeitet keine Anmeldedaten. pi authentifiziert sich aus ~/.pi/agent/auth.json, danach aus Umgebungsvariablen. MCP-Hosts starten Server oft mit einer abgespeckten Umgebung, daher bevorzuge auth.json (führe pi einmal aus und /login) gegenüber dem Exportieren von Schlüsseln in einem Shell-Profil.

Entwicklung

npm install
npm run build       # tsc, src/*.ts -> dist/
npm run typecheck   # tsc --noEmit, strict
npm run test:ci     # offline: boots the server over stdio and lists its tools
npm test            # full suite: needs a logged-in pi, makes real model calls

test:ci ist das, was CI ausführt und woran prepublishOnly gekoppelt ist, weil es keine Anmeldedaten und kein Netzwerk benötigt. npm test lässt echte Delegates gegen echte Anbieter laufen, kostet also Geld und funktioniert nur dort, wo pi angemeldet wurde.

Releases werden über Tags gesteuert. npm version patch && git push --follow-tags führt den Build und die Tests aus und veröffentlicht dann über OIDC Trusted Publishing, sodass kein npm-Token irgendwo im Repository gespeichert wird.

Issues und Pull Requests sind willkommen. Wenn du einen Delegate meldest, der sich fehlverhalten hat, ist der toolCalls-Trace von status mit verbose: true das, was du anhängen solltest.

Verwandte Arbeiten

abatilo/pi-mcp-bridge schlägt den einfacheren Weg ein: starte pi --mode json -p --session-id <uuid> und lass pi die Sitzungen auf der Platte speichern, sodass die Bridge überhaupt keinen Zustand hält. Elegant und lesenswert. Dafür gibt sie Steuerung, Fragen und Tool-Kontrolle auf.

Lizenz

MIT