mcp-agents

MCP-Server, der KI-CLI-Tools kapselt — Claude Code, Antigravity CLI (agy) und Codex CLI — und Chrome DevTools MCP an einen remote geleasten Browser weiterreichen kann.

Voraussetzungen

• Node.js >= 26

• Mindestens eine der folgenden CLIs installiert und in Ihrem $PATH:

Nur die CLI, die Sie mit --provider auswählen, muss vorhanden sein.

Related MCP server: claudecode-mcp

Installation

npm install -g mcp-agents

Die globale Installation ist der schnellste und zuverlässigste Startweg. npx -y mcp-agents ist funktional äquivalent, sobald der MCP-Server läuft, aber der Start hängt vom npm-Paketauflösungs-/Cache-Zustand ab, bevor der MCP-Client eine Verbindung herstellen kann.

Tipp: Wenn die .mcp.json Ihres Projekts mcp-agents referenziert, fügen Sie npm install -g mcp-agents zu Ihrem Setup-Skript (z. B. bin/setup) hinzu, damit neue Entwickler es automatisch erhalten.

Schnelltest

# Default provider (codex)
mcp-agents

# Specific provider
mcp-agents --provider claude
mcp-agents --provider gemini

# Browser provider (example injected lease helper)
mcp-agents --provider browser \
  --browser_lease_command '["bin/box","--browser"]'

Der Server spricht JSON-RPC über stdio. Er gibt [mcp-agents] ready (provider: <name>) auf stderr aus, wenn er lauscht.

Anbieter & Tools

Jedes --provider-Flag wählt ein CLI-Backend aus:

Claude-Reviews

Für substanzielle Zweitmeinungen und Code-Reviews verwenden Sie die Hintergrund-Tools:

1. Rufen Sie claude-start mit dem vollständigen Review-Prompt und einem absoluten cwd auf.

2. Rufen Sie claude-status mit der zurückgegebenen jobId und dem cursor auf. Wiederholen Sie dies mit jedem neuen Cursor, bis der Zustand terminal ist.

3. Wenn der Zustand completed ist, rufen Sie claude-result auf. Fahren Sie ab nextOffset fort, bis done true ist.

4. Rufen Sie claude-cancel auf, wenn das Urteil nicht mehr benötigt wird.

claude-status long-pollt standardmäßig 10 Sekunden und akzeptiert wait_ms bis zu 60 Sekunden. Das Abbrechen einer Statusabfrage bricht den Job nicht ab. Jobs sind Einmal-Jobs und lokal zur aktuellen MCP-Verbindung: Es gibt keine Antwort-Sitzungen, und eine Trennung bricht aktive Arbeit ab. Der Server erlaubt 8 aktive und 32 aufbewahrte Jobs, behält terminale Jobs eine Stunde lang, paginiert Ergebnisse bei 32.768 Unicode-Codepunkten und lehnt ein Endergebnis über 10 MiB ab.

Hintergrund-Reviews haben eine bridge-eigene Zwei-Stunden-Frist. Betreiber können sie beim Starten des Servers durch --timeout <seconds> ersetzen; Aufrufer können einen Job nicht mit timeout_ms verkürzen. Claude ist auf claude-opus-4-8 mit Aufwand xhigh festgelegt und läuft als Leaf-Reviewer: Es behält Projektanweisungen und Repository-Kontext, deaktiviert aber Hooks, Subagenten, Skills, Slash-Befehle, externe MCP-Server und Mutations-Tools. Nur Read, Glob, Grep und schreibgeschützte Bash-Inspektion im Plan-Modus sind verfügbar; die Leaf-Anweisung verbietet außerdem Testausführung, Installationen, Delegation und externe Seiteneffekte. Zwischenergebnisse des Modells, Tool-Eingaben/-Ergebnisse, Pfade und Reasoning werden nicht über MCP weitergeleitet; nur bereinigter Phasenstatus und das endgültige Urteil werden offengelegt.

Verwenden Sie das blockierende claude_code-Tool nur für kleine Prompts, bei denen ein einzelner MCP-Aufruf bequem innerhalb des Client-Timeout abgeschlossen werden kann.

claude_code-Parameter

Alle zusätzlichen tools/call-Argumente werden ignoriert (z. B. model, effort oder config).

Claude ist auf claude-opus-4-8 mit Aufwand xhigh festgelegt; Aufrufer können Modell oder Aufwand pro Aufruf nicht ändern. Aufrufe laufen mit --output-format json; der Server parst die JSON-Nutzlast und gibt den result-Text des Assistenten zurück (oder einen MCP-Fehler, wenn is_error=true). Der längere Standardwert berücksichtigt tiefgehende Opus-Reviews; Aufrufer können weiterhin ein kleineres timeout_ms setzen, und Serverbetreiber können den Standardwert mit --timeout <seconds> überschreiben.

gemini-Parameter

Alle zusätzlichen tools/call-Argumente werden ignoriert (z. B. model oder model_reasoning_effort).

agy läuft immer mit --sandbox (Terminaleinschränkungen aktiviert); es gibt keinen Sandbox-Umschalter pro Aufruf.

browser (Remote-Chrome-Durchreichung)

Der Browser-Anbieter startet sofort einen lokalen chrome-devtools-mcp-Server und erwirbt dann beim ersten beworbenen Browser-Tool-Aufruf lazy einen Remote-Chrome-Lease. Der MCP-Server und alle von ihm geschriebenen Dateien bleiben lokal; nur CDP überquert den vom Betreiber bereitgestellten Loopback-Tunnel. Aufrufe, die während des Erwerbs eintreffen, teilen sich einen Provisionierungsversuch und bleiben in FIFO-Reihenfolge. Es gibt keine Wrapper-eigenen Acquire-, Status-, Release-, Job- oder Abbruch-Tools.

Schnelle Einrichtung mit crabbox

Am besten in Kombination mit crabbox: ephemere Single-Tenant-Boxen, die an ihren eigenen Caps sterben — die Lebensdauer, die ein Browser-Lease möchte, ohne ein Teardown, das man richtig hinbekommen muss.

Ihr acquire-Helfer erledigt vier Dinge: eine Box leasen; Chromium darauf mit --remote-debugging-port=<remote> starten; ssh -L 127.0.0.1:<local-cdp-port>:127.0.0.1:<remote> öffnen (fügen Sie ein passendes -R für --app-port hinzu, wenn die zu testende Seite auf Ihrer Maschine bereitgestellt wird); und sobald /json/version auf dem lokalen Port antwortet, ausgeben:

record_version=1
state=ready
generation=<opaque token>
local_cdp_port=<the port you were given>
browser_url=http://127.0.0.1:<that same port>

status prüft diesen Lease erneut, release baut ihn ab, und jeder Exit 69 hält die Spur fail-closed.

Der Anbieter hat kein Cloud- oder SSH-Wissen. Ein injizierter Befehl besitzt den Lease und empfängt diese argv-Formen:

acquire --session <id> --local-cdp-port <port> --viewport <WxH> [--app-port <port>]
status --session <id> [--generation <token>]
release --session <id> --generation <token> --reason idle|shutdown

Erfolgreiche Acquire-Ausgabe sind inerte UTF-8-key=value-Daten mit einem Version-1-Ready-Datensatz, Generation, ausgewähltem lokalem CDP-Port und passender Browser-URL. Exit 69 ist fail-closed: Der Aufruf gibt „GUI not verified — no browser box available“ zurück und startet niemals einen lokalen Browser. Ein vom Helfer gemeldeter Preflight-Fehler des lokalen Dev-Servers wird wörtlich beibehalten. Exit 75 meldet einen Loopback-Bind-Race; mcp-agents wählt einen neuen Port, startet den Downstream neu, spielt die ursprünglichen MCP-initialize-Fähigkeiten (einschließlich roots) und die initialized-Benachrichtigung erneut ab und versucht höchstens dreimal, ohne ein doppeltes initialize-Ergebnis offenzulegen.

chrome-devtools-mcp ist bewusst nicht gepinnt — der Fallback gleitet zur neuesten Version. Nichts hier hängt vom Reconnect-Verhalten einer bestimmten Version ab: Jedes Browser-Tool-Ergebnis wird gegen die Lease-Generation verifiziert, unter der es ausgestellt wurde, unabhängig davon, ob der Downstream einen Reconnect meldet. Eine neuere Version kann den Fail-closed-Vertrag also nicht stillschweigend schwächen. Die Auflösung ist deterministisch in dieser Reihenfolge:

1. --browser_command oder MCP_AGENTS_BROWSER_COMMAND (Befehlszeichenfolge oder JSON-argv).

2. Ein paketlokal auflösbares chrome-devtools-mcp, dann node_modules/.bin/chrome-devtools-mcp.

3. npx -y chrome-devtools-mcp@latest.

Der dritte Pfad kann das erste initialize auf die npm-Auflösung warten lassen. Für einen schnelleren Start installieren Sie chrome-devtools-mcp neben mcp-agents oder installieren Sie es woanders und zeigen Sie mit --browser_command auf seine ausführbare Datei. Pinnen Sie es dort, wenn Sie für eine bestimmte Bereitstellung eine feste Version benötigen. Der Browser-Downstream erfordert die Node-Versionen, die von der chrome-devtools-mcp-Version unterstützt werden, auf die er sich auflöst; die eigene >=26-Untergrenze dieses Pakets bleibt auf oder über dieser, da die ungepinnte Abhängigkeit der neuesten Version folgt.

chrome-devtools-mcp ist absichtlich eine Entwicklungsabhängigkeit, keine Laufzeitabhängigkeit. Ein Entwickler-Checkout nutzt daher den paketlokalen Pfad, während Nutzer des veröffentlichten Pakets den npx-Fallback verwenden, es sei denn, sie installieren das Paket neben mcp-agents oder geben einen expliziten Befehl an.

Der Viewport wird an den Lease-Helfer übergeben, damit dieser die Fenstergröße des Remote-Chromium festlegen kann; Chrome DevTools MCPs --viewport wird absichtlich weggelassen, da es beim Anhängen über --browserUrl wirkungslos ist.

Jeder vollständige Downstream-JSON-RPC-Frame setzt den Generation-Idle-Timer zurück; stderr und Teilausgaben tun das nicht. Idle-Release hat eine 60-Sekunden-Cleanup-Grenze, damit Remote-Chromium, SSH-Tunnel und die Box tatsächlich stoppen können. Shutdown-Release verwendet eine separate 15-Sekunden-Grenze und bleibt verfolgt und abgeräumt. Beide sind Best-Effort-Kostenoptimierungen. Wenn Chrome verschwindet, wird der unterbrochene native Connect-Fehler nicht erneut abgespielt. Ein Helferstatus von 69 reichert ihn mit browser_lease_replaced an und warnt ausdrücklich, dass der Browser ersetzt wurde, Zustand verloren ging, das unterbrochene Ergebnis unbekannt ist und Aufrufer den Zustand inspizieren müssen, statt blind erneut abzuspielen. Status 0 bewahrt den nativen Fehler; Status 70 bleibt unbekannt, statt als verlorener Lease falsch gemeldet zu werden. Der nächste Browser-Aufruf erwirbt erneut und nutzt den Reconnect-Pfad von Chrome DevTools MCP.

The client initialize frame and the downstream roots/list request/response are forwarded without ID or URI rewriting. An downstream-Neustart werden Antworten, die für den beendeten Prozess bestimmt waren, verworfen und seine Anfragekorrelationen werden zurückgezogen, bevor ein Ersatz eine ID wiederverwenden kann. Das erhält die lokale Dateischreib-Zulassung von Chrome DevTools MCP, weshalb --allowUnrestrictedPaths absichtlich nie übergeben wird. App- und MinIO-Preflight-Fehler werden getrennt und in Originalwortlaut gemeldet. Die Beschreibungen zu Performance trace und Lighthouse warnen, dass es sich bei der Messung eines Remot-Links nicht um ein Gate handelt, und upload_file warnt, dass ein lokaler Pfad nicht direkt an eine Stelle weitergehaben werden kann.

URL-Einschränkungen sind Opt-in, da eine reine Loopback-Standard falls OAuth- und Drittanbieter-Ressourcen aus dem passen würde. Eine abgehärtete, reine-Loopback-Bereitstellung kann zum Beispiel wiederholt werden:

--browser_allowed_url_pattern 'http://127.0.0.1/*' \
--browser_allowed_url_pattern 'https://127.0.0.1/*'

Verwenden Sie die engsten Muster, die mit der Zielanwendung kompatibel sind. Der Provider unterstützt kein experimentelles Seiten-ID-Routing: Ein Prozess besitzt eine Lease, ein Profil und einen Port.

codex (Pass-through)

Der Codex-Provider reicht transparent an Codex' native MCP server (codex mcp-server) in einer isolierten CODEX_HOME-Umgebung weiter. Die Bridge erstellt jedes Home unter dem privaten tmp/codex-homes/-Baum des Server-StartumgebungsVerzeichnisses, kopiert auth.json, schreibt eine minimale config.toml und erbt nicht deine reguläre externe MCP-Serverliste. So wird verhindert, dass Codex während Bridge-Aufrufen rekursiv andere Agententools (z. B. Claude oder Gemini) startet. Die übergeordneten und die generierten Home-Verzeichnisse verwenden status 0700; kopierte Anmeldeinformationen und generierte Laufzeitdateien 0600.

Das isolierte Home ist ein Authentifizierungs- snapshot: Es kann sich einen späteren codex login erst wieder ansehen, wenn die Bridge verwendet werden. Wenn Codex das Tune des unauthorized-Terminalereignisses berichtet, unterdrückt der Wrapper das doppelte-Ereignis und meldet einen einzelnen MCP-Tool-Fehler mit structuredContent.code als codex_auth_invalidated und action als reauthenticate_and_restart zurück. Neue Codex-Keine-Turns werden lokal abgelehnt, während Status, Ergebnis, Abbrechen, Anzeigen, Ping, Ping- und andere MCP-Operationen verfügbar bleiben. Halten Sie die Bridge an, führen Sie codex logout und codex login als derselbe OS-Benutzer aus, überprüfen Sie mit codex exec und verbinden dann Sie neu. Beim Aufräumen wird rotierte Auth HAAP nur zurückschreiben, wenn sich die isolierte Kopie geändert hat und die kanonische Auth noch mit dem Start-Snapshot übereinstimmt; eine veraltete Brücken kann daher nicht einen neueren manuellen Login oder die Token-Rotation einer anderen Brücke überschreiben.

Die einzige eindeutige nutzer-Stimme ist schneller Modus. Beim start liest die Brücke die Quell-$CODEX_HOME/config.toml und aktiviert den schnellen Modus im isolierten Home nur dann, wenn sie beide oberste service_tier = "fast"-Zeile und [features]. Schnell als true setzt. Teilweise, deaktivierte, fehlende oder aggressive Einstellungen bleiben im Standardmodus; alle anderen Benutzerkonfigurationen bleiben isoliert. Starten Sie den MCP-Server nach dem Ändern einer der beiden Einstellungen neu. Fast mode hat höheren ChatGPT-Credit- verbrauch bzw. API-Priority-abrechnung

Weitere Start-Standardwerte: sandbox_mode=workspace-write, approval_policy=never (für den gesamten Server mit --sandbox_mode/--approval_policy konfigurierbar), web_search=cached, check_for_update_in_startup=false, ignore_login_shell=false und history.persistence=none. Festgelegte Bridge-Feature-Standards sind: features.multi_agent=false, features.apps=false, features.plugins=false, features.hooks=false und features.skill_mcp_dependency_install=false; Stays on gle- / Plugin-Fähigkeiten – Figma, Gmail, Präsentationen usw. – bleiben deaktiviert. Native Subagenten werden zusätzlich verhindert mit [agents] enabled = false, denn beginnend bei Codex >= 0.145.0 das stabilisierte multi_agent-Feature-Flag allein nicht mehr die Collaboration-Tools aus dem Session-Kontext entfernt; Sessions werden per call per-call mit allow_subagents wieder angemeldet (s. u.). Diese [agents]-Zeile ist versionsabhängig: Bridge testet codex --version einmalig beim Start und lässt sie bei Codex < 0.145.0 aus, wo ein Boolean unter [agents] bei 0.102–0.144 einen fatalen Konfigurationsparser verursacht; das Feature-Flag steuert dort die Collaboration-Tools weiterhin allein. Wenn Version nicht parsebar ist, wird modernes Codex angenommen.

Workspace-write-Sitzungen haben network-Access standardmäßig aktiv, so dass Sandbox-Befehle lokale Dienste wie DynamoDB, Redis, OpenSearch und Minio erreichen. Setzen Sie --codex-workspace-network=false oder MCP_AGENTS_CODEX_WORKSPACE_NETWORK_ACCESS=false, um dies für das gesamte Server zu deaktivieren; CLI-Flag priorisiert vor der Umgebungsvariable. Das ist eine server-seitige Sandbox-Einstellung und bewusst nicht Teil der per-Call tool-Schemas.

Codex bietet keine Loopback-only-Begrenzung für diese Einstellung. Das Einschalten erlaubt Ausgangsnetzzugriff allgemein von commands in workspace-write-Sessions. Filesystem-Schreibens austauschprogrammdres Drehmomentbeschränkt. WRITABLE- und danger-full-access-Sessions verwenden nicht die sandbox_workspace_write-Einstellung.

Die Brücke ersetzt Codex breites, config-förmiges natives Schema durch eine bewusst enge Vertragsform:

Ja.

Now table for codex parameters.

| codex Parameter | Typ | Pflicht? | Beschreibung | "Erforderlich" maybe column. "Required" translate as "Erforderlich". Use vertical bars.

Modify "Typ" vs "Type". Good.

yes -> ja? We'll use "Ja".

no -> "Nein".

Output table:

We might want "Ja" instead of "yes". Use "Ja" non-code.

Let's craft:

The codex-reply table:

| codexereply Parameter | Typ | erforderlich | Beschreibung | | prompt | string | Ja | Folge-Benutzerprompt | | threadId | string | Ja | Nichtleere Thread-ID, aus codex gegeben | | goal | string | Nein | Optionale Ziel-Erinnerung auf Prompt-Ebene |

"Nonblank" -> "Nicht leer".

"Both schemas set additionalProperties: false. Unsupported, missing, or invalid Args..." Use "Beide Schemas setzen additionalProperties: false."

"Native escape hatches such as..." Translate: "Das umfasst nativ-Escape-Hatches wie config, approval-policy, developer-instructions, base-instructions und compact-prompt; zukünftige Upstream-Schemaergänzungen bleiben versteckt, bis mcp-agents sich intentional übernimmt." "hidden until etc." Use "absichtlich". Good.

"Model values outside the two curated choices are rejected same way." -> "Modellwerte außerhalb der beiden ausgewählten Optionen werden auf dem gleichen Weg abgelehnt."

Then "Native subagents." full: "I developed." Let's translate.

Native subagenzen. allow_subagents: true auf codex oder codex-start ermöglicht dieser Session, die in Codex eingebauten Multi-Agenten-Werkzeuge (spawn_agent, wait_agent, …) zu nutzen. Sie ist genau wie sandbox bereichsbezogen: Antworten erben es und können das nicht ändern. Standardmäßig ist es deaktiviert. Intern umschaltet das Flag ausschließlich die nativen Multi-Agenten-Tore (agents.enabled zzglund features.multi_agent, mit derselben Versionsbedingung wie oben) über eine pro-Aufruf-Konfiguration-Übersovverschreibung; alles andere am isoliert bleibt unverändert. Insbesondere die entfernte [mcp_servers] bleibt wirksam, sodass erzeugte Subagenten reine Codex-weite Prozessarbeiter – sie können nicht zurück in diese Bridge oder zu Claude, Gemini oder anderen externen MCP-Tools, und für die Komponente-agnostik sind die in Ihrem tatsächlichen $CODEX_HOME/agents/ & Z-Agen nicht hineinkopiert.

"Betrifft der Rest koncurrency, nicht Reichweite: Subagenten erben die sandbox_mode und approval_policy der laufenden Session können bei workspace-write und approval_policy=never mehrere Agenten einen gemeinsamen Workspace verändern. Codex koordiniertet das, aber zeigen Sie den Auftrag entsprechend herunter."

"approval_policy=never" paragraph as above.

Then "Startup flags ..." etc.

Need remember link "GXP6" in text.

Let's write all now.

One more nuance: "Regime includes native escape hatches such as..." Need "Unsere" etc. Maintain.

Also "Future schema additions" maybe "schema additions upstream" meaning "upstream schema additions" - "Upstream"-addition. Good.

Let's now produce final answer.Der Client initialize-Frame und die Downstream-roots/list-Anfrage/-Antwort werden ohne ID- oder URI-Umschreibung weitergereicht. Einem Neustart des Downstream-Prozesses werden Antworten, die für den beendeten Prozess bestimmt waren, verworfen und die zu ihren zugehörigen Korrelationen aus dem Prozess, bevor der Nachfolger eine ID wiederverwenden kann. Dadurch bleibt die lokale Dateischreib-Zulassungsliste von Chrome DevTools MCP erhalten, und --allowUnrestrictedPaths wird dementsprechend nie aktiv durchgesetzt. App- und MinIO-Preflight-Fehlern werden getrennt und im Originalwortlaut ausgegeben. Die Performance -trace- und Lighthouse-Beschreibungen weisen darauf hin, dass die Remote-Connect-Messung kein Gate ist, und upload_file warnt, dass ein lokaler Pfad nicht direkt an einem remote Chromium übergeben werden kann.

URL-Restriktionen sind vorhanden, weil eine reine Loopback-Standardkategorie OAuth- und Drittanbieter-Ressourcen brechen kann. Eine abgehärtete, nur-Loopback-Bereitstellung ist zum Beispiel wieder:

--browser_allowed_url_pattern 'http://127.0.0.1/*' \
--browser_allowed_url_pattern 'https://127.0.0.1/*'

Verwenden Sie die engsten Muster, die mit der Zielapp kompatibel sind. Der Anbieter aktiviert kein experimentelles Page-ID-Routing: ein Prozess Besitz eine Lease, ein - und Profil.

codex (Pass-through)

Der Codex-Anbieter leitet an den nativen MCP-Server weiter innerhalb eines isolierten Heimatverzeichnisses CODEX_HOME. Die Bridge erstellt den tmp/codex-homes/-Unterordner des Server-Starts, kopiert auth.json, erstellt eine minimale config.toml und erbt nicht die reguläre MCP-Serverliste. So verhindert, dass Codex beim Bridge-Aufruf den anderen Tools wie Claude oder Gemini startet. Die übergeordneten und erzeugten Home-Verzeichnisse nutzen den Modus 0700, kopierte Credentials und erzeugte Laufzeitdateien nutzen den Modus 0600.

Das isolierte Home ist ein Authentifizierungs- snapshot: es kann einen späteren codex login nicht sehen, bis die Bridge neu verbunden ist. Wenn Codex das typisierte nonautorized Terminal-Ereignis meldet, unterdrückt der Wrapper das event unterschieden und gibt ein MCP-Tool-Fehler mit structuredContent.code und codex_auth_invalidated, action und reauthenticate_and_restart zurück. Neue Codex-Turns werden abfallen, Statusausfall, Ergebnis, Ablkasken, aber immer noch MCP- und andere Operationen sind möglich. Bridge unterbrochen, codex logout und codex login als derselben OS-User ausführen, mit codex exec prüfen, dann wieder connecten. Bei Aufräumen wird Auth nur zurückschreiben, wenn sich isolierte Kopie geändert hat und die kanonische Auth noch Überseinstimmung mit Start. Ein Go Bridge kann keinen neuen manual Login oder andere Bridge-Token-Rotierung überbeschreiben.

Die einzige Freires-User-Einstellung ist Fast-Modus. Beim Start liest die Bridge das Original $CODEX_HOME/config.toml und aktiviert schnell Modus nur, wenn sie beide Ziele: top-level service_tier = "fast" und [features].fast_mode = true finden. Teilweise, deaktivierte, fehlende oder nicht lesbare Einstellungen bleiben Standard-Mode. Restart Master-Server danach.

Fast mode Mehrhöhe ChatGPT-Credit Continue

Weitere Start-Standards: sandbox_mode=workspace-write, approval_policy=never (für den gesamten Server --sandbox_mode / --approval_policy), social_search=cached, check_for_update_on_startup=false, allow_login_shell=false, history.persistence=none. Fixe Bridge-Feature: features.multi_agent=false, features.apps=false, features.plugins=false, features.hooks=false, features.skill_mcp_dependency_install=false. Native Subagenten zusätzlich disabled mit [agents] enabled = false, weil Codex >= 0.145.0 das stabile multi_agent-Flag allein nicht mehr die Kollaborationswerkzeuge entfernt. Diese Zeile ist Version-abhängig: Bridge mittelt codex --version einmalig beim Start und kann die Zeile bei Codex < 0.145.0 weglassen, sonst erhalten. Ein eine Hybrid bei 0.102–0.144 als fataler Konfigurationsfehler wertet.

Workspace-write-Sessions haben network enabled by default, damit Kommando de lokal services see können (DynamoDB, Redis, Open-B, MinIO). Setzen von --codex-workspace-network=false oder der env-variable deaktiviert; CLI-Flag zuerst.

Codex bietet kein localhost-only scoping für diese Einstellung. Ausgehendes Netz wird erlaubt, from workspace-write, Schreibens-Wir in Workspace und andere Wurzen restrikt, read-only/danger-full-access verwenden nicht.

Die Bridge ersetzt breite config-förmige Schema durch eine absichtlich kleine Beschreibung:

codex-reply:

prompt string yes#### Un Fam Fülltext Expect output.

Let's recursively infer: The target is de-DE. We must adhere to the list exactly. The paragraph above has the "weird" "The client initialize frame" phrase. We can translate as "Der Client-initialize-Frame" or "Der initialize-Frame des Clients". Good.

But wait, our final draft might have mistakes such as "Codexcode". We must rewrite carefully.

Let's now construct the final final in a formal translation, then send. But we need ensure no contradiction to "Preserve the exact structure of Markdown tables". The tables must match row/column count. Ensure the header separators have same number of pipes? The user says preserve exact structure, same number of rows/columns. We can use same number of columns. Our output should have the same amount for each table. We can use standard dash alignment; fine. We need not exactly the same number of spaces, only "same table structure." We can display "| ---- | ---- |" etc. It's okay.

Given the final draft might be lengthy; let's now produce final answer as polished translation, with valid German. But because it's possibly too long.

Before final, let's re-evaluate the source "mcp-agents intentional" etc.

We'll create final answer in the usual. We need output no "Here is". Use raw text.

Let's proceed.Der Client-initialize-Frame und die Downstream-roots/list-Anfrage/-Antwort werden ohne ID- oder URI-Umschreibung weitergeleitet. Bei einem Downstream-Neustart werden Antworten, die für den beendeten Prozess bestimmt waren, verworfen, und seine Request-Korrelationen werden zurückgezogen, bevor der Nachfolger eine ID wiederverwenden kann. Dadurch bleibt die lokale Dateischreib-Allowlist von Chrome DevTools MCP erhalten; --allowUnrestrictedPaths wird daher absichtlich nie übergeben. App- und MinIO-Preflight-Fehler werden getrennt und wörtlich gemeldet. Die Beschreibungen von Performance-Trace und Lighthouse warnen, dass eine Remote-Link-Messung kein Gate ist, und upload_file warnt, dass ein lokaler Pfad nicht direkt an ein Remote-Chrome weitergegeben werden kann.

URL-Einschränkungen sind Opt-in, da eine reine Standard-Loopback-Variante OAuth- und Drittkomponenten-Anlagen „brechen“ würde. Ein gehärtetes Loopback-only-Deployment kann zum Beispiel Folgendes:

--browser_allowed_url_pattern 'http://127.0.0.1/*' \
--browser_allowed_url_pattern 'https://127.0.0.1/*'

Verwenden Sie die engsten Muster, die mit der Zielanwendung kompatibel sind. Der Provider unterstützt kein experimentelles Page-ID-Routing: Ein Prozess besitzt jeweils eine Lease, ein Profil und einen Port.

codex (Pass-through)

Der codex-Provider reicht an den nativen MCP-Server von Codex (codex) in einem isolierten CODEX_HOME durch. Die Bridge erzeugt jedes Home-Verzeichnis unterhalb des privaten tmp/codex-homes/-Baums im Startverzeichnis des Servers, kopiert auth.json, schreibt eine minimale config.toml und übernimmt nicht die normale externe MCP-Serverliste. So kann Codex während der Bridge-Aufrufe nicht rekursiv andere AgentenvTools starten; also Claude oder Gemini. Die übergeordneten und die erzeugten Base-Directories verwenden den Modus 0700; kopierte Zugriffsdaten und generierte Laufzeitdateien verwenden 0600.

Das isolierte Home ist eine Authentifizierungs-Snapshot: Es sieht das isolierte Environment keinen späteren codex login, bis Bridge wieder verbindet. Wenn Codex das typisierte unauthorized-Terminalereignis meldet, unterdrückt der Wrapper das doppelte Ereignis und gibt einen MCP-Tool-Fehler mit structuredContent.code = codex_auth_invalidated sowie action = reauthenticate_and_restart zurück. Neue Codex-Turns werden in vom Ort abgelehnt, während Status-, Ergebnis-, Abbrechen-, Peek-, Ping- und andere MCP-Vorgänge verfügbar bleiben. Beenden Sie die Bridge, führen Sie codex logout und codex login als derselbige BS-Benutzer aus, prüfen Sie mit codex exec, und verbinden Sie sich dann erneut. Beim Aufräumen wird eine rotierte Authentifizierung nur zurückgeschrieben, wenn sich die isolierte Kopie geändert hat und die kanonische Auth noch dem Start-Snapshot entspricht; ein weiches Bridge kann also weder einen neueren manuellen Login noch die Tokens-Rotation einer anderen Bridge überschreiben.

Die einzige auf der Allowlist stehende Benutzervorgabe ist der Fast-Modus. Beim Start liest die Bridge die Quell-$CODEX_HOME/config.toml und aktiviert den Fast-Modus im isolierten Home nur dann, wenn sie sowohl das oberste service_tier = "fast" als auch [features].fast_mode = true findet. Teilweise, deaktivierte, fehlerhafte oder nicht lesbare-Einstellungen verbleiben beim Standardmodus; alle übrigen Benutzereinstellungen bleiben isoliert. Starten sie MCP-Server nach einer Änderung einer der beiden Einstellungen neu.

Fast Mode verbraucht einen höheren ChatGPT-Creditverbrauch bzw. API-Priority-Abrechnung.

Weitere Startvorgaben: sandbox_mode=workspace-write, approval_policy=never (für den gesamten Server mit --sandbox_mode / --approval_policy einstellbar), sandbox_execution_network=true, ... — must correct: sandbox_mode=workspace-write, approval_policy=never, web_search=cached, check_for_update_on_startup=false, allow_login_shell=false, history.persistence=none. Feste Bridge-Feature-Vorgaben sind features.multi_agent=false, features.apps=false, features.plugins=false, features.hooks=false, features.skill_mcp_dependency_install=false; Apps und Plugins bleiben deaktiviert, um ChatGPT-App-/Plugin-Fähigkeiten z. B. Figma, Gmail, Präsentationen außerhalb des Kontext der Bridge-Session zu halten. Native Subagenten werden zusätzlich deaktiviert mit [agents] enabled = false, da bei Codex >= 0.145.0 – das stabile multi_agent-Feature-Flag allein nicht mehr die Collaboration-Tools entfernt; Sessions ziehen per Call mit allow_subagents wieder ein (siehe unten). Diese [agents]-Zeile ist versionsbewusst: die Bridge probe codex --version once beim Start und lässt es bei Codex < 0.145.0 aus, wo ein Boolean untereinstelltweise unter [agents] ein fataler Config-Parser-Fehler (0.102–0.144) und das Feature-Flag die Collaboration-Tools weiterhin selbst gated. Eine nicht parsebare Version geht moderne Codex aus.

Workspace-write Sessions haben Netzwerkzugriff standardmäßig aktiv, damit Sandbox-Kommandos lokale Dienste wie DynamoDB, Redis, Open-Search und MinIO erreichen können. setzen Sie --codex-workspace-network=false oder MCP_AGENTS_CODEX_WORKSPACE_NETWORK_ACCESS=false, um serverweit zu deaktivieren; das CLI-Flag hat Vorrang vor der Umgebungsvariable. Dies ist eine server-seitige Sandbox-Einstellung und wird bewusst weggelassen aus dem per-Call-Tool-Gehäuse.

Codex bietet für diese Einstellung keine Loopback-only-Begrenzung. Das Aktivieren erlaubt allgemeinen ausgehenden Netzwerkzugriff von Kommandos in Workspace-Write-Sessions. Schreibzugriff auf das Dateisystem bleibt auf den workspace und andere konfigurierte Wurzel beschränkt; Read-only-session und danger-full-access-Sessions verwenden die Einstellung sandbox_workspace_write nicht.

Die Bridge ersetzt das breite, konfig-ähnliche native Schema von Codex durch eine bewusst Vertrag:

Beide Schemas definieren additionalProperties: false. Unsupported, fehlende oder ungültige Argumente werden lokal mit JSON-RPC -32602 abgelehnt, bevor Codex läuft. Daz include native escape hatcheswie config, approval-policy, developer-instructions, base-instructions und compact-prompt; künftige Schema-Erweiterungen aus dem Upstream bleiben verborgen, bis mcp-agents sie bewusst übernimmt. Andere Modelle als die beiden definierten werden auf dieselbe ablehnt.

Naträgersubagenten. allow_subagents: true auf codex oder codex-start gibt dieser Session Zugriff auf integrierten Multi-Agent-Tools von Codex (spawn_agent, wait_agent, …). Like sandbox ist sie sessionscoped: varied- Antworten erben die Einstellung, können sie nicht ändern und standardmäßig aus. Intern aktiviert das überflag die nativen Multi-Agent-Gatekeeping (agents.enabled, plus features.multi_agent, auf denselben Versionstor wie oben) über per-Call-Override; übrige isolierten Home-Verzeichnis bleibt unverändert. Der [mcp_servers]-Block bleibt aktiv, damit spawnierte Subagenten only Codex-in-process-Arten – nicht wieder in diese Bridge, und in einzelnen Claude / Gemini / andere MCP-Tools; eigene agent-Rollen aus der realen $CODEX_HOME/agents/ werden nicht übernommen. Der Rest ist Parallelität: Subagenten inheriten die sandbox_mode und approval_policy der Session. Unter workspace-write mit approval_policy=never können mehrere Agenten gleichzeitig in denselben Workspace schreiben. Codex koordiniert sie, aber the budget steht entsprechend.

approval_policy=never ist absichtlich für eine MCP-Bridge: Ein abgetrennter Tool-Call kein autonomes interaktives Quick-Approval-Screener führt. Betreiber können --approval_policy=untrusted oder on-request serverwide setzen, aber Anrufer können diese Richtlinie weder schwächen noch pro Request ändern. Jede neue Session muss weiter ihr Sandbox explizit angeben; die Schreibberechtigung bleibt Aufrufstelle sichtbar.

Startflags ( --model, --model_reasoning_effort) konfigurieren isolated native Codex defaults (gpt-5.6-sol and xhigh unless overridden). Each initial codex call can choose one of two models and one of four allowed reasoning effort levels:

Die Auswahlen gelten nur bei der Session-Erstellung. Fehlt einer, verwendet den Server default. Every codex-reply erbt beide Auswahl- und kann sie nicht ändern. Andere Modelle/Effort-Level sind durch bewusst geschlossen nicht erreichbar.

Rund um Beispiel: Ein readonly review beginnt mit:

{
  "prompt": "Review this diff",
  "cwd": "/absolute/path/to/project",
  "sandbox": "read-only",
  "model": "gpt-5.6-terra",
  "model_reasoning_effort": "high",
  "goal": "Find correctness and security defects"
}

Ziel-Injection. Set or pass --goal "…" at start. mcp-agents turns initial Ziel into Codex's native developer-instructions internally:

{
  "prompt": "Refactor the parser",
  "cwd": "/absolute/path/to/project",
  "sandbox": "workspace-write",
  "model_reasoning_effort": "xhigh",
  "goal": "Keep the public API unchanged"
}

Developer-Message persists for Thread; replies inherit them. Ein codex-reply mit goal wird zu einer kompakten Prompt-Memo, because non-Time-Tool message.

Bridge rewrites tools/list responses to advertise these curated schemas. Normal native frames are exactly byte-identical except for the keyed auth failure; locally generated validation/auth errors use the same frame-safe queue/limit discipline as progress and recover messages.

Priorität innerhalb eines Threads. Das auf dem anfänglichen codex-Aufruf gesetzte Ziel ist eine Developer-Rollen-Nachricht und bleibt für den gesamten Thread bestehen, hat also Vorrang: Ein anderes goal, das später auf einem codex-reply geliefert wird, ist nur eine Erinnerung auf Prompt-Ebene und wird das bestehende Ziel nicht zuverlässig überschreiben (live verifiziert — ein Reply-Ziel, das dem anfänglichen widerspricht, wird zugunsten des bestehenden ignoriert). Die Reply-Erinnerung funktioniert, wenn ihr kein widersprüchliches bestehendes Ziel entgegensteht. Um das Ziel mitten im Verlauf wirklich zu ändern, starten Sie einen neuen codex-Aufruf, anstatt es auf einem codex-reply zu ändern.

Hinweis — dies ist nicht das native /goal von Codex. Der /goal-Slash-Befehl von Codex (dauerhafter, threadbezogener Zielzustand mit Lebenszyklus/Budget/evidenzbasierter Fertigstellung) ist ein reines TUI-Feature — er wird in der Codex-Terminal-UI geparst und ist nicht über codex mcp-server erreichbar. Ein MCP-Prompt mit /goal … zu präfixieren aktiviert es nicht; der Text wird nur als Benutzernachricht durchgereicht. Dieser Wrapper steuert Codex daher mit developer-instructions (dem MCP-nativen Vehikel für ein bestehendes Ziel), was eine Prompt/Rollen-Konditionierung ist, nicht das native Ziel-Lebenszyklus-Subsystem.

Lebendigkeit pro Aufruf. Der Codex-Durchgriff verfolgt jeden offenen tools/call unabhängig. --codex_idle_timeout <seconds> (Standard 600, 0 deaktiviert) begrenzt, wie lange ein Aufruf ohne korrelierte Codex-Aktivität laufen darf. Nur ein Codex-Ereignis, das die _meta.requestId dieses Aufrufs trägt (oder seine passende Antwort oder interaktive Ausgabe), erneuert seine Leerlauf-Frist. Codex-stderr, Client-Pings, unzusammenhängende Anfragen und Ereignisse, die zu einem anderen Aufruf gehören, können einen festgefahrenen Aufruf nicht am Leben halten. Erreicht ein Aufruf seine Idle-Frist, schlägt der Wrapper nur diesen Aufruf mit einem JSON-RPC-Fehler (-32001) fehl, sendet Codex eine notifications/cancelled für diese Anfrage — best effort, bittet Codex also zu stoppen, statt es zu zwingen (siehe Abbruch unten) — unterdrückt die verspätete native Antwort des festgefahrenen Aufrufs und hält die Verbindung offen — Geschwister-Aufrufe und der stdio-Transport bleiben unberührt. Das ist wichtig, weil ein Schließen des stdio-Transports MCP-Clients wie Claude Code dazu bringt, den Server als failed zu markieren und jedes mcp__codex__*-Werkzeug für den Rest der Sitzung dauerhaft zu deregistrieren (stdio-Server werden nicht automatisch neu verbunden), sodass eine einzelne festgefahrene Überprüfung niemals die gesamte Brücke herunterreißen darf. Die Codex-Prozessgruppe wird bei einem echten Teardown (Client-Trennung, Signal oder stdout-EPIPE) weiterhin abgeräumt. Die eine Ausnahme: Wenn Codex mitten beim Schreiben eines Antwort-Frames festhängt (keine sichere Grenze, an der der Fehler eingefügt werden kann) und auch den Abbruch ignoriert, versucht der Wrapper es einmal erneut und eskaliert dann zu einem begrenzten Brücken-Teardown — es gibt keine Möglichkeit, einen sauberen Frame in einen teilweisen zu emittieren, also bleibt dem Client nur, sich mit einer frischen Brücke neu zu verbinden.

Abbruch. Ein Client-Abbruch (notifications/cancelled — jede ESC, abgebrochene Runde oder Subagent-Teardown) wird genauso behandelt: Er kostet genau eine Anfrage. --codex_cancel_grace <seconds> (Standard: 30) begrenzt, wie lange Codex Zeit hat, ihn zu bestätigen; bei Ablauf erledigt der Wrapper diese Anfrage-ID lokal, unterdrückt die verspätete Codex-Antwort und lässt die Brücke und alle Geschwister-Aufrufe weiterlaufen. Das Erledigen der Anfrage ist kein Beweis, dass Codex gestoppt hat — eine nicht bestätigte Runde wird als aufgegeben aufgezeichnet und kann weiterlaufen und schreiben. Die oben beschriebene Mid-Frame-Eskalation aktiviert eine zweite volle Gnadenfrist, sodass dieser Pfad ungefähr doppelt so lange dauert, bevor die Brücke finalisiert wird. Die Gnadenfrist ist bewusst großzügig — eine Codex-Mid-Turn-Runde führt Sandbox-Befehle aus und bedient MCP-Abbruch nicht schnell, sodass eine kurze Gnadenfrist den Eskalationspfad zum Standardpfad machen würde. Das ist wichtiger als der Timeout-Fall, weil das isolierte CODEX_HOME das sessions/-Verzeichnis von Codex enthält: Ein Brücken-Teardown macht jede threadId in diesem Prozess dauerhaft nicht wiederaufnehmbar, und der nächste codex-reply schlägt mit Session not found fehl.

[!WARNING] Das Aufgeben einer Anfrage stoppt Codex nicht. Der Wrapper bittet es zu stoppen, aber eine Runde, die den Abbruch ignoriert, läuft weiter — und schreibt weiter in den Arbeitsbereich — lange nachdem der Client aufgegeben hat. Jede Aufgabe wird mit ihrer thread_id und job_id auf stderr protokolliert und erneut protokolliert, wenn die Runde später endet, sodass ein unerwartet veränderter Baum erklärt statt geraten werden kann. Hintergrundjobs sind hier die scharfe Kante: Ein codex-start-Job lebt in der Job-Tabelle dieses Wrappers, nicht im Task-Register des MCP-Clients, sodass ein clientseitiges „Task stoppen“ ihn nicht erreichen kann — nur codex-cancel mit seiner jobId kann das. Da ein Job durch diesen Prozess gepollt wird, kann er eine Wiederverbindung nie überleben, sodass eine Client-Trennung jeden nicht-terminalen Job und jede offene Anfrage abbricht, und ein begrenzter Wind-Down räumt die Codex-Prozessgruppe ab, wenn sie trotzdem weiterarbeitet.

--timeout <seconds> wird auch für Codex-Aufrufe durchgesetzt (Standard: 7200) als unveränderliche harte Frist. Korrelierte Aktivität kann das Idle-Fenster verlängern, aber nie diese harte Frist. Setzen Sie die Wrapper-Frist unter die eigene Wanduhr-Tool-Timeout des MCP-Clients, wenn der Client immer die explizite Fehlermeldung des Wrappers erhalten muss, bevor er aufgibt.

Wenn die eingehende Anfrage _meta.progressToken liefert, sendet der Wrapper standardmäßige MCP-notifications/progress-Updates mit genau diesem Token. Er erfindet nie ein Progress-Token. Der erste nützliche Status ist sofort; spätere Updates werden auf höchstens eines pro Sekunde zusammengefasst, wobei der neueste Status gewinnt. Während sonst stillem Arbeiten wird alle 10 Sekunden eine Codex: still running-Meldung gesendet, die das Alter des letzten anfragekorrelierten Codex-Ereignisses enthält.

Statustext ist fail-closed. Die Brücke legt explizit attribuierte Kommentare, den aktiven Planschritt und generische Lebenszyklus-Zusammenfassungen für Befehle, Patches, MCP-Werkzeuge, Web/Bild-Arbeit und Subagenten offen. Sie legt keinen Final-Answer-Text, keine Überlegungen, keine Prompts, keine Befehlszeichenfolgen oder -ausgaben, keine Werkzeugargumente, keine Suchanfragen, keine Dateipfade und keine Token-Telemetrie offen. Nachrichten werden auf Leerzeichen normalisiert und auf 200 Unicode-Codepunkte begrenzt. Native codex/event-Frames bleiben byte-für-byte unverändert, außer dass ein typisiertes unauthorized-Fehlerereignis durch den einzelnen strukturierten Auth-Fehler oben ersetzt wird; Fortschritt ist ein paralleler MCP-Kanal und normalerweise UI-Status statt zusätzlichem Tool-Ergebnis/Modell-Kontext.

Optionale Hintergrundjobs. Bestehende codex- und codex-reply-Aufrufe bleiben blockierend und behalten ihr aktuelles Verhalten. Clients, die transkriptsichtbare Updates benötigen, können stattdessen die sechs Wrapper-eigenen Job-Werkzeuge verwenden, die von der Codex-Brücke beworben werden:

Bevorzugen Sie den blockierenden codex-Aufruf, auch für lange Builds. Er kostet einen Werkzeugaufruf statt einer Aufrufer-Runde pro Statusänderung, streamt weiterhin notifications/progress an eine progressionsbewusste UI und wird durch Abbrechen der Runde abgebrochen. Greifen Sie nur dann zu einem Job, wenn die Arbeit den Aufrufer überleben muss — sie muss weiterlaufen, nachdem Sie aufhören zu warten, oder ein anderer Agent muss sie später per jobId abbrechen können.

codex-peek — arbeitet diese Runde noch?

Ein blockierender Aufruf ist undurchsichtig, bis er zurückkehrt, was „festgefahren“ und „beschäftigt“ von außen identisch aussehen lässt. codex-peek beantwortet das, ohne etwas abzubrechen, um es herauszufinden: Es listet jede Codex-Runde in Flug auf, blockierend und Hintergrund gleichermaßen, schreibgeschützt und sofort, und akzeptiert optionale cwd- / threadId- / requestId-Filter.

Suchen Sie stattdessen nicht nach einem Pro-Runden-Prozess: codex mcp-server ist langlebig und multiplext jede Anfrage, also gibt es kein codex exec zu finden, und eine Prozesstabelle meldet nichts, während ein Build läuft.

Drei Antworten, die weniger bedeuten, als sie aussehen. Eine leere Liste ist kein Beweis, dass eine Runde beendet ist — eine aufgegebene Runde läuft weiterhin innerhalb von Codex, mit nichts in Flug, das zu melden wäre, und ihre Anzahl kommt als abandonedTurnsProcessWide zurück — benannt nach ihrem Umfang, weil eine aufgegebene Runde keinen Arbeitsbereich behält und daher nie durch einen Filter eingeschränkt wird. Ein großes elapsedSeconds ist kein Stillstand — es ist nur Wanduhr — und ein großes lastActivitySeconds auch nicht: Ein einzelner Werkzeugaufruf kann legitimerweise viele Minuten still laufen, also ist Stille unbewiesen, nie beendet. Abbrechen, um es herauszufinden, ist das Einzige, was nicht rückgängig gemacht werden kann. Und ein cwd-Filter verbirgt nie eine Runde, deren Arbeitsbereich unbekannt ist — er meldet sie mit cwdUnknown, weil „Ich kann es nicht sagen“ nicht stillschweigend zu „dort läuft nichts“ werden darf.

Das Startergebnis kehrt sofort mit einer undurchsichtigen jobId, einem Status-cursor und dem nächsten vorgeschlagenen Aufruf zurück. Wiederholte codex-status-Aufrufe erzeugen gewöhnliche MCP-Tool-Ergebnisse, sodass ein äußerer Agent oder Subagent weitergeben kann, was Codex tut, selbst wenn seine UI notifications/progress nicht rendert — die einzige Sichtbarkeit, die ein Job bietet, die ein blockierender Aufruf nicht bietet. Am aktuellen Cursor wartet ein Statusaufruf auf eine Änderung und gibt dann einen Heartbeat zurück; wait_ms kann von 0 bis 60000 gesetzt werden, und wenn es weggelassen wird, wird es auf das Statusintervall unten standardisiert (10000, wenn diese Taktung deaktiviert ist).

Zwei Dinge beenden eine Statuswartezeit, und beide sind für die Poll-Kosten relevant. Ein Cursor-Fortschritt wird serverseitig durch --codex_status_interval <seconds> (Standard 30) getaktet, wodurch Zwischenfortschritte gebündelt werden, anstatt den Cursor bei jeder Nachricht zu erhöhen. Der wait_ms-Heartbeat ist das andere Element und wird nicht durch dieses Intervall getaktet – daher folgt wait_ms nun dem Statusintervall (gedeckelt bei 60000, sodass ein Intervall über 60 Sekunden weiterhin alle 60 Sekunden einen Heartbeat sendet), um zu verhindern, dass ein Heartbeat den Cursor, über den er berichtet, überholt. wait_ms bleibt eine Obergrenze für Leerlauf-Warten und niemals eine Untergrenze für den Poll-Abstand: Ein Statusaufruf kehrt sofort zurück, sobald der Cursor bereits hinter dem Kopf liegt, sodass ein Poller, der zurückgefallen ist, durch ein Erhöhen nicht verlangsamt werden kann – ein aufgeholter jedoch schon, weshalb ein Senken von wait_ms Züge ohne Gegenleistung kostet.

Nur intermediate Fortschrittsupdates werden getaktet; Lebenszyklus-Übergänge – das erste running, eine Stornierung und jeder Endzustand – bewegen den Cursor und wecken jeden Wartenden direkt, unter Umgehung des Intervalls, sodass ein Erhöhen den Abschluss nie verzögert. Die Stillstandserkennung ist ebenso unberührt – lastActivitySeconds wird aus rohen Codex-Ereignissen gestempelt, nicht aus Status-Ticks – und codex-commentary behält weiterhin die vollständige Erzählung. 0 stellt einen Cursor-Fortschritt bei jeder Änderung wieder her; Werte über 60 überlassen die Heartbeat-Obergrenze die Kontrolle und lassen nur den Statustext veralten. Fortschritts-Benachrichtigungen behalten ihren eigenen, viel feineren Takt und kosten den Aufrufer keinen Kontext – aber beachten Sie, dass sie nur für einen blockierenden Aufruf ausgegeben werden: Eine Hintergrundjob-Anfrage trägt kein Fortschrittstoken, sodass die einzige Sichtbarkeit eines Jobs codex-status / codex-commentary ist.

Wenn commentaryEndOffset voranschreitet, rufen Sie codex-commentary mit dem letzten nextOffset auf. Commentary enthält nur Codex-Nachrichten, die explizit mit der commentary-Phase markiert sind. Verborgenes Denken, Prompts, Entwürfe der endgültigen Antwort, Befehlszeichenfolgen und -ausgaben, Tool-Argumente, Pfade, Suchanfragen und rohe Antwortelemente sind ausgeschlossen. Unsichere Terminalsteuerungen werden entfernt, aber der verbleibende Text ist modellverfasst und muss weiterhin als nicht vertrauenswürdig behandelt werden. Offsets zählen Unicode-Codepunkte. Jeder Lesevorgang gibt höchstens 32.768 Codepunkte zurück; die Brücke behält einen Ein-MiB-UTF-8-Schwanz und meldet absolute Abschneidegrenzen, wenn ältere Kommentare aus dem Puffer gefallen sind.

Sobald der Status terminal ist, verwenden Sie codex-result und fahren Sie ab nextOffset fort, bis done wahr ist. Jede Seite liefert ihre Nutzlast sowohl als gewöhnlichen MCP-Textinhalt als auch als structuredContent.text für Clients, die strukturierte Ergebnisse priorisieren. Ergebnnisseiten sind ebenfalls auf 32.768 Codepunkte begrenzt. Ein nativer Ergebnisrahmen, der größer als das 10-MiB-Erfassungslimit der Brücke ist, schlägt den Job atomar fehl, anstatt seine private Antwort auf den MCP-Transport zu leaken.

Jobs sind bewusst verbindungs-lokal: Ein Neustart oder eine erneute Verbindung des MCP-Servers verliert sie. Höchstens acht Jobs dürfen aktiv sein und 32 Datensätze werden aufbewahrt; terminale Datensätze verfallen nach einer Stunde. Die Stornierung hat dieselbe begrenzte Abwicklungs-Semantik wie ein blockierender Aufruf, also überprüfen Sie den Arbeitsbaum, bevor Sie einen stornierten, schreibfähigen Job erneut versuchen. Die Job-API ist ein Opt-in auf Aufrufebene und erfordert keine MCP-Tasks-Unterstützung vom Client.

Diese Hinweise halten das Leerlauffenster eines fortschrittsbewussten Clients bewusst am Leben und überlassen die Lebendigkeits-Autorität den Leerlauf- und harten Fristen des Wrappers. Sie aktualisieren --codex_idle_timeout nicht, verlängern die harte Frist des Wrappers nicht und verlängern auch nicht die separate harte Wanduhr-Timeout des Clients. Ein generierter Fortschrittsrahmen wird nur an einer nativen Zeilenumbruchgrenze eingefügt; wenn Codex mitten in einem Rahmen ins Stocken gerät, wartet der neueste Hinweis auf eine sichere Grenze, und der echte Leerlauf-Watchdog beendet einen dauerhaften Stillstand weiterhin. Konfigurieren Sie das Client-Timeout so, dass es die längste erwartete Codex-Ausführung plus Antwort-Headroom überschreitet; wenn es abläuft, storniert der Client den Aufruf, und der begrenzte Stornierungspfad unten übernimmt.

Wiederherstellung des terminalen Ergebnisses. Codex kündigt die Thread-ID in einem frühen, anfragekorrelierten Sitzungsereignis an, sodass der Wrapper sie behält, bevor der Build abgeschlossen ist. Wenn Codex später sein terminales Abschlussereignis und die endgültige Agentennachricht ausgibt, aber die native tools/call-Antwort nicht innerhalb der kurzen terminalen Antwort-Gnadenfrist eintrifft, gibt der Wrapper ein gleichwertiges erfolgreiches Ergebnis zurück, das sowohl content als auch structuredContent.threadId enthält. Eine passende späte native Antwort wird verworfen, wodurch die Exactly-Once-JSON-RPC-Antwortsemantik erhalten bleibt. Dies deckt den Fehlermodus ab, in dem Arbeit im Baum gelandet ist, der Aufrufer aber weder das Ergebnis noch die Thread-ID erhalten hat.

Stornierung und Wiederverbindung. Die Stornierung durch den Client startet eine kurze, nicht zurücksetzbare Gnadenfrist, die durch --codex_cancel_grace begrenzt ist (die Mid-Frame-Eskalation unten armiert eine zweite, sodass dieser Pfad etwa doppelt so lange dauern kann). Wenn Codex sich nicht innerhalb dieser Frist beruhigt, wickelt der Wrapper diese Anforderungs-ID lokal ab, unterdrückt die späte Antwort von Codex und lässt die Brücke und alle Geschwisteraufrufe weiterlaufen – ein einzelner blockierter Aufruf darf niemals die gesamte Brücke zu Fall bringen. Zwei begrenzte Ausnahmen: ein Stream, der mitten im Rahmen verklemmt ist und die Stornierung ebenfalls ignoriert (ohne sichere Grenze, an der ein Fehler injiziert werden kann, versucht der Wrapper es einmal erneut und eskaliert dann zu einem vollständigen Brückenabbau), und die aggregierte Obergrenze – sobald unterdrückte Antworten MAX_SUPPRESSED_CODEX_RESPONSES erreichen, finalisiert die Brücke, anstatt sie unbegrenzt zu verfolgen. Nach beiden verbindet sich der Client erneut mit einer frischen Brücke. Eine native Antwort, die innerhalb der Gnadenfrist eintrifft, wird verworfen, wenn sie abgefangen werden kann, ohne einen teilweise weitergeleiteten Rahmen zu beschädigen. Der stornierte, potenziell schreibfähige Aufruf wird nie automatisch wiederholt. Stornierung ist Best-Effort und beweist nicht, dass Codex gestoppt hat – eine nicht bestätigte Runde wird als abgebrochen, nicht als beendet aufgezeichnet und kann weiterlaufen und den Arbeitsbereich beschreiben. Überprüfen Sie daher den Arbeitsbaum, bevor Sie ihn manuell erneut versuchen.

Diese Legacy-Brücke startet nicht codex mcp-server innerhalb der bestehenden stdio-Verbindung neu und spielt Threads auch nicht transparent erneut ab. codex-reply-Zustand gehört zum alten Codex-Prozess, sodass eine Thread-ID aus einem abgerissenen Kindprozess nach einer Wiederverbindung nicht fortgesetzt werden kann. Eine dauerhafte Wiederherstellung in derselben Verbindung erfordert eine separate Migration vom transparenten Legacy-Pass-through zu einem MCP-Adapter über codex app-server (thread/start, turn/start, turn/interrupt und thread/resume).

Integration mit Claude Code

Fügen Sie Einträge zur .mcp.json Ihres Projekts hinzu, indem Sie eine global installierte mcp-agents-Binärdatei verwenden:

{
  "mcpServers": {
    "codex": {
      "command": "mcp-agents",
      "args": ["--provider", "codex"],
      "timeout": 7500000
    },
    "gemini": {
      "command": "mcp-agents",
      "args": ["--provider", "gemini"]
    }
  }
}

npm (globale Installation) vs. npx – bevorzugen Sie eine global installierte Binärdatei. Die command: "mcp-agents"-Form oben startet eine lokal installierte Binärdatei direkt; die npx-Alternative unten führt npx -y mcp-agents bei jedem Prozessstart aus. Das ist wichtig für die Zuverlässigkeit, nicht nur für die Kaltstart-Geschwindigkeit: Claude Code startet den stdio-Server neu, wenn es (erneut) eine Verbindung herstellt – auch nach einer Wiederverbindung mitten in der Sitzung – und npx führt bei jedem Start eine Paket-Registrierungsauflösung ohne Offline-Fallback durch. Wenn diese Auflösung langsam ist (VPN, Captive Portal, Registrierungs-Hänger), auf eine Version veraltet ist, die nicht mehr existiert (npm error code ETARGET), oder anderweitig fehlschlägt, schlägt der Start fehl, der Transport schließt sich, und die Tools sind für die Sitzung verschwunden. Eine global installierte Binärdatei (oder ein absoluter Pfad zu node server.js) entfernt die Netzwerkabhängigkeit und eine Prozessebene aus dem Signal-/Teardown-Pfad. Installieren Sie einmal mit npm install -g mcp-agents (oder npm link aus einem Quell-Checkout) und zeigen Sie dann die Konfiguration darauf.

Für einen From-Source-Checkout, der als Ihre persönliche Codex-Brücke verwendet wird, kann ein Benutzereintrag auf ~/.claude.json-Ebene den Baum direkt starten und die Leerlauf-Obergrenze pro Anfrage deaktivieren (sodass eine lange, legitimerweise stille Überprüfung nur durch das eigene Wall-clock-Timeout des Clients begrenzt wird, anstatt vorzeitig abgebrochen zu werden):

{
  "mcpServers": {
    "codex": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-agents/server.js", "--provider", "codex", "--codex_idle_timeout", "0"],
      "env": {},
      "timeout": 3600000
    }
  }
}

Bare node wird gegen den PATH des MCP-Clients aufgelöst; wenn node von einem Versionsmanager (nvm/fnm/asdf) verwaltet wird, der in dieser Umgebung nicht initialisiert ist, verwenden Sie stattdessen einen absoluten Node-Pfad (which node, z. B. /opt/homebrew/bin/node).

Überschreiben Sie Codex-Standardwerte beim Serverstart:

{
  "mcpServers": {
    "codex": {
      "command": "mcp-agents",
      "args": ["--provider", "codex", "--model", "gpt-5.6-sol", "--model_reasoning_effort", "xhigh", "--codex-workspace-network=false"],
      "timeout": 7500000
    }
  }
}

Jeder anfängliche codex-Aufruf kann gpt-5.6-sol oder gpt-5.6-terra und medium, high, xhigh oder max auswählen; weggelassene Selektoren verwenden die Server-Standardwerte, und Antworten erben beide Auswahlmöglichkeiten. Andere Modelle, rohe config und Argumente für die Genehmigungsrichtlinie pro Aufruf werden abgelehnt, bevor Codex ausgeführt wird. Fügen Sie "--goal", "<text>" zu args hinzu, um ein Standardziel bereitzustellen (siehe Ziel-Injektion oben).

Claude interpretiert das serverseitige timeout in Millisekunden als harte Wall-clock-Obergrenze; Fortschritt verlängert es nicht. Halten Sie es über dem --timeout des Wrappers (standardmäßig 7.200 Sekunden), einschließlich Antwort-Headroom. Ein Projekt-.mcp.json-Eintrag kann einen Benutzereintrag mit demselben Namen überschreiben. Setzen Sie das Timeout also auf den Projekteintrag, anstatt sich auf die Benutzerkopie zu verlassen.

Mit Ausnahme des oben beschriebenen expliziten Fast-Mode-Paars erbt die Brücke keine Einstellungen von Ihrer normalen ~/.codex/config.toml. Insbesondere bleiben geerbte MCP-Server innerhalb von überbrückten Codex-Sitzungen absichtlich nicht verfügbar.

{
  "mcpServers": {
    "codex": {
      "command": "npx",
      "args": ["-y", "mcp-agents", "--provider", "codex"],
      "timeout": 7500000
    }
  }
}

npx betrifft nur den Prozessstart – sobald die Verbindung hergestellt ist, ist die Tool-Aufruf-Latenz in beiden Fällen derselbe Servercode. Aber jeder Start (einschließlich jeder Wiederverbindung) löst das Paket gegen die npm-Registrierung ohne Offline-Fallback auf, sodass eine langsame, offline oder veraltete Cache-Auflösung den Start fehlschlagen und die Tools mitten in der Sitzung fallen lassen kann (siehe npm vs. npx oben). Das Festlegen von mcp-agents@x.y.z vermeidet, dass ein @latest mitten in der Sitzung eine frisch veröffentlichte Version aufnimmt, entfernt aber nicht die Netzwerkabhängigkeit pro Start. Verwenden Sie npx nur, wenn Null-Installation wichtiger ist als Startzuverlässigkeit.

Integration mit OpenAI Codex

Fügen Sie zwei Einträge zu ~/.codex/config.toml hinzu – einen pro Anbieter, den Sie verfügbar machen möchten. Das 960-Sekunden-Timeout des Claude-Clients bewahrt die Kompatibilität mit dem blockierenden 900-Sekunden-claude_code-Tool. Hintergrundüberprüfungen halten keine MCP-Anfrage offen: claude-start kehrt sofort zurück, und jeder claude-status-Poll dauert höchstens 60 Sekunden.

[mcp_servers.claude-code]
command = "mcp-agents"
args = ["--provider", "claude"]
tool_timeout_sec = 960

[mcp_servers.claude-code.tools.claude-start]
approval_mode = "approve"

[mcp_servers.claude-code.tools.claude-status]
approval_mode = "approve"

[mcp_servers.claude-code.tools.claude-result]
approval_mode = "approve"

[mcp_servers.claude-code.tools.claude-cancel]
approval_mode = "approve"

[mcp_servers.gemini]
command = "mcp-agents"
args = ["--provider", "gemini"]
tool_timeout_sec = 360

Bitten Sie in einer Codex-Sitzung um eine zweite Meinung oder Überprüfung von Claude und verwenden Sie claude-start → claude-status → claude-result. Behalten Sie claude_code für kleine blockierende Prompts; gemini bleibt ein blockierendes Tool.

Entwicklung

npm install
npm link          # symlinks mcp-agents to your local server.js

Nach npm link werden Änderungen an server.js sofort wirksam – keine Neuinstallation erforderlich.

Benchmarken Sie die Startpfade über echte /tmp-Projekt-.mcp.json-Dateien:

npm run bench:mcp-startup

Dies misst den MCP-Start bis initialize und tools/list; es ruft das Provider-Modell/Tool nicht auf.

Für eine manuelle Claude-Hintergrundprüfung rufen Sie claude-start mit einem kurzen Überprüfungsprompt und diesem Repository als cwd auf, pollen Sie claude-status mit jedem zurückgegebenen Cursor und lesen Sie das Urteil mit claude-result. Für die umgekehrte Richtung lassen Sie Claude Code codex-start aufrufen, codex-status pollen und codex-result lesen. Diese Smoke-Checks verwenden echte Modellaufrufe und bleiben getrennt von der deterministischen Testsuite-Gate.

So funktioniert es

1. Ein MCP-Client verbindet sich über stdio

2. Der Server liest --provider <name> aus seinen argv (Standard: codex)

3. Gemini registriert ein blockierendes CLI-Tool; Claude registriert sein Legacy-Blockier-Tool plus die One-Shot-Review-Job-Tools; Codex leitet seine nativen Tools weiter und fügt seine Hintergrund-Job-Tools hinzu

4. Der Client ruft tools/call mit dem Tool-Namen und einem prompt auf

5. Der Server führt die CLI als getrennten Kindprozess aus; Claude-Review-Jobs parsen Stream-JSON in sichere Status- und aufbewahrte Ergebnnisseiten, während blockierende Tools normalisierte Anbieterausgabe zurückgeben

Der Server unterhält einen kleinen Keepalive-Timer, damit Node.js nicht vorzeitig beendet wird, wenn stdin EOF erreicht, bevor ein asynchroner Subprozess einen aktiven Handle registriert. Im Claude- und Gemini-Provider-Modus wird dieser Keepalive beim Herunterfahren gelöscht. Wenn die MCP-stdio-Verbindung geschlossen wird, erhalten aktive Claude-Aufträge einen Interrupt und einen begrenzten TERM/KILL-Fallback; alle verbleibenden überwachten abgetrennten Provider-Prozessgruppen werden eingesammelt, bevor der Server beendet wird.

Lizenz

MIT