mcp-delegate

Ein MCP-Server, der Claude Code (als Orchestrator) ein Tool gibt, um eine Aufgabe an eine separate, vollwertige agentische Schleife zu delegieren, die auf einem anderen Modell läuft (lokal per Ollama oder remote per OpenRouter), mit eigenem Tool-Zugriff (Dateien, Bash usw.) und das Ergebnis am Ende zurückgibt – funktional äquivalent zu einem nativen Subagenten, aber modellunabhängig.

Siehe mcp-subagent-delegation-plan.md für den vollständigen Build-Plan, aufgeteilt in separate Commits/Checkpoints.

Status

Phase 1, 2, 3 and 4 abgeschlossen.

• delegate_task – einmalige Chat-Completion gegen einen konfigurierten OpenAI-kompatiblen Endpunkt (Ollama, LM Studio, vLLM, OpenRouter, ...).

• delegate_agentic_task – gibt dem delegierten Modell eine eigene Tool-Schleife (read_file, write_file, run_bash), die auf ein vom Aufrufer angegebenes Arbeitsverzeichnis beschränkt ist und läuft, bis es keine Tools mehr aufruft, max_iterations erreicht oder timeout_seconds überschreitet.

• list_recent_delegations – zeigt an, was früher ausgeführte Delegationen (mit einem der beiden Tools) tatsächlich getan haben, ohne in Logs zu stöbern oder irgendetwas erneut auszuführen.

• get_delegation_transcript – vollständiges Nachrichten-/Tool-Aufruf-Transkript für eine einzelne Delegation, wenn sie mit capture_transcript=True ausgeführt wurde (z. B. für Modellvergleichs-/Evaluierungs-Läufe).

Abweichung vom ursprünglichen Plan: Phase 2 sah vor, agent-loop als Subprozess zu kapseln. agent-loop unterstützt nur Linux/macOS/WSL, und dieser Server muss auf Windows nativ laufen. Deshalb haben wir die In-Process-Schleife gebaut, die in der Alternative von Phase 3 beschrieben wurde – gleiche Tool-Schnittstelle, keine Subprozess-/ANSI-Bereinigungs-Komplexität, und sie umgeht die AGPL-/Nicht-Kommerzielle-Lizenz von agent-loop komplett. Siehe delegate/agentic.py.

Sicherheitshinweis: working_dir ist vom Aufrufer vorgegeben, keine feste Sandbox – das delegierte Modell erhält unbeobachteten Datei-/Bash-Zugriff auf das Verzeichnis, auf das es zeigt. Datei-Tools (read_file/write_file) sind so eingeschränkt, dass sie innerhalb von working_dir bleiben; run_bash läuft mit diesen Verzeichnis als cwd, aber Shell-Befehle sind nicht vollständig sandboxed und können es verlassen (z. B. mit cd ..). Richte es auf ein Verzeichnis, in dem du damit okay bist, dass ein unbeaufsichtigtes Modell darin lesen, schreiben und Befehle ausführen kann.

Guardrail-Hinweis: Phase 4 des ursprünglichen Plans verlangte zu bestätigen, dass die eigenen Guardrails von agent-loop (Iterationslimit, Wiederholungserkennung) aktiv sind. Da wir agent-loop nicht verwenden, trifft das nicht direkt zu – unsere Schleife hat eigene max_iterations- und timeout_seconds-Grenzen (in Tests bestätigt), aber keine Wiederholungserkennung. Ein Modell, das zwischen zwei Tool-Aufrufen hängen bleibt, läuft bis zum max_iterations-Limit, statt frühzeitig erkannt zu werden. Es lohnt sich, das hinzuzufügen, falls das tatsächlich vorkommt.

Related MCP server: Thinking Agent MCP

Einrichtung

uv sync
cp .env.example .env             # fill in DELEGATE_BASE_URL / DELEGATE_API_KEY / DELEGATE_MODEL
cp models.json.example models.json   # optional: named backends, see below

Mehrere Backends

Beide Tools nehmen einen optionalen backend-Parameter entgegen, der base_url/model/api_key aus models.json holt, statt der Standard-Umgebungsvariablen DELEGATE_* – z. B. backend="ollama-local" für einen Aufruf und backend="openrouter-free" für einen anderen in demselben Durchgang, jeweils gleichzeitig. model überschreibt, wenn ebenfalls angegeben, nur die Modellstring innerhalb dieses Backends.

Verweise für einen Schlüssel auf eine Umgebungsvariable, statt sie direkt in models.json zu schreiben:

{
  "openrouter-free": {
    "base_url": "https://openrouter.ai/api/v1",
    "model": "nvidia/nemotron-nano-9b-v2:free",
    "api_key_env": "OPENROUTER_API_KEY"
  }
}

models.json ist gitignored, genau wie .env.

Parallelität

MCP-Tool-Aufrufe laufen bereits auf eigenen Worker-Threads, also laufen parallele Delegationen ohne extra Zusatz parallel. DELEGATE_MAX_CONCURRENCY (Standard 4, siehe .env.example) begrenzt, wie viele Delegationen – über beide Tools, egal welches Backend – gleichzeitig ausgeführt werden, um zu verhindern, dass ein großer Ausgang den lokalen Modellserver oder die Ratenlimits einer bezahlten API überlastet.

Server direkt starten (meistens nützlich, um zu prüfen, dass er ohne Fehler startet – er wartet danach auf stdio auf einen MCP-Client):

uv run server.py

Protokollierung

Jeder delegate_task-/delegate_agentic_task-Aufruf – Erfolg oder Fehler – wird in eine lokale SQLite-Datei delegations.db geloggt (gitignored, wird bei erster Verwendung angelegt): Tool, Backend, Modell, Aufgabentext, Start-/Endzeit, Iterationszahl, Erfolg/Fehler, eine gekürzte Ergebnis-/Fehler-Vorschau und Token-Nutzung, falls das Backend sie liefert. Du kannst sie über list_recent_delegations abfragen oder direkt mit sqlite3 delegations.db "select * from delegations order by id desc limit 20". Logging ist Best-Effort – ein Logging-Fehler bringt einen sonst erfolgreichen Vorgang nicht zu Fall.

Beide Tools hängen ebenfalls eine endgültige [tokens: N prompt / N completion / N total ($cost)]-Zeile an ihren sonstigen Rückgabewert an, wenn das Backend Nutzung meldet, damit der aufrufende Agent sie sofort sehen kann, ohne extra list_recent_delegations aufzurufen.

Kostenverfolgung

pricing.json bildet Modell-String → {input_per_million, output_per_million} USD-Raten ab. Wenn das aufgelöste Modell eines Aufrufs einen Eintrag hat, werden die Kosten aus dem tatsächlichen Token-Verbrauch berechnet, in delegations.db (Spalte cost_usd_) protokolliert und im [tokens: ...]-Suffix angegeben. Ein Modell ohne Eintrag protokolliert cost_usd_ = NULL – unbekannt, nicht als kostenlos angenommen – damit eine fehlender Eintrag nicht stillschweigend zu niedrige Ausgaben meldet. Lokal angehängt Modelle haben deshalb meist keinen Eintrag; wirklich kostenliche freie Modelle (z. B. OpenRouter-Modelle mit :free) erhalten einen expliziten {"input_per_million": 0, "output_per_million": 0}-Eintrag, statt weggelassen zu werden.

Anders als .env/models.json ist pricing.json kein Geheimnis oder umgebungsspezifisch, also wird es direkt committet, statt zu gitignoren. Die Preise ändern sich. Die Datei wurde bei OpenRouter's /api/v1/models am 2026-08-21 abgerufen, für Modelle, die in einem Modellvergleichs-Bake-Off, für das dieser Server erstellt wurde; ruf sie neu ab und aktualisiere sie, wenn du Modelsleistungs ändern willst.

Transkript-Erfassung (Modellvergleichs-/Eval-Läufe)

Beide Tools akzeptieren capture_transcript: bool = False. Wenn aktiviert, wird der vollständige Nachrichtenaustausch – jede Nachricht des Modells, jeder Tool-Aufruf und jedes Tool-Ergebnis, nicht nur die endgültige Antwort – protokolliert, und der Rückgabewert erhält ein Suffix [delegation_id: N]. Abholen kannst du mit mit get_delegation_transcript(delegation_id).

Das gibt es dafür, dieselbe Aufgabe durch mehrere verschiedene Modelle/Backends laufen zu lassen und nicht nur die Endgültige Antwort zu vergleichen, sondern auch wie jede Version dort hingekommen ist (Modell- bzw. `Anruf-Auswahl, fehlerhafte Tool-Aufrufe, Wiederholungen) – etwa für einen BewerVergleichswettbewerb aus, bevor man ein Modell für Produktion auswählt. Standardmäßig deaktiviert, da es zusätzlichen Logging-Overhead gibt, den man bei normaler Delegation sonst nicht benötigt.

Registrieren bei Claude Code

Eine projektspezifische .mcp.json ist bereits eingecheckt (uv run server.py). Starte Claude Code in diesem Verzeichnis neu oder führe claude mcp list aus, um zu bestätigen, dass der delegate-Server übernommen wurde, und bitte dann, delegate_task mit einem trivialen Prompt aufrufen zu lassen, um den Rundweg zu bestätigen.

Tools

• delegate_task(prompt, model=None, system_prompt=None, backend=None, capture_transcript=False) -> str – einmalige Chat-Completion gegen das konfigurierte Backend.

• delegate_agentic_task(task, working_dir, model=None, max_iterations=20, timeout_seconds=600, backend=None, capture_transcript=False) -> str – mehrstufige Delegation mit read_file/write_file/run_bash-Tools, eingeschränkt auf working_dir. Es gibt nur die endgültige Antwort zurück, nicht das vollständige Transkript, außer wenn capture_transcript=True ist.

• list_recent_delegations(limit=20) -> list[dict] – die zuletzt protokollierten Delegationen, neueste zuerst.

• get_delegation_transcript(delegation_id) -> list[dict] – vollständiges Transkript zur Delegation, die mit capture_transcript=True geloggt wurde.

delegate_task/delegate_agentic_task geben Fehler (schlechte Konfiguration, nicht erreichbarer Endpoint, Timeout, Iterationslimit) als "Error: ..."-Strings zurück, statt zu werfen, damit ein aufrufender Agent sehen kann, was passiert ist.