Codex Supervisor MCP

Eine lokale Model Context Protocol (MCP)-Brücke, die es einem kompatiblen Host ermöglicht, Codex-App-Server-Arbeit zu starten, zu überwachen, zu steuern, zu unterbrechen, fortzusetzen und zu genehmigen.

Es kapselt codex app-server; es automatisiert keine Terminal-Benutzeroberfläche und extrahiert keine Daten aus einer IDE.

Funktionen

Der Server stellt diese MCP-Tools bereit:

Related MCP server: Codex Bridge MCP

Anforderungen

• Node.js 22 oder neuer.

• Eine aktuelle Codex-CLI, verfügbar als codex.

• Codex-CLI-Authentifizierung bereits konfiguriert.

• Ein oder mehrere explizite lokale Repository-Roots.

Dieses Projekt hat keine npm-Laufzeitabhängigkeiten.

Paket verifizieren

npm test

Die Testsuite verwendet einen protokollkompatiblen Mock-App-Server. Sie stellt keine Modellanfragen und erfordert keine Codex-Authentifizierung.

Installation mit der Codex-CLI

Verwenden Sie den MCP-Servernamen codex-supervisor. Der Name muss CODEX_SUPERVISOR_MCP_NAME entsprechen; die Brücke verwendet ihn, um zu verhindern, dass der untergeordnete App-Server diesen MCP-Server rekursiv lädt.

macOS oder Linux

codex mcp add codex-supervisor \
  --env CODEX_ALLOWED_ROOTS="/Users/you/code:/Users/you/work" \
  --env CODEX_SUPERVISOR_MCP_NAME="codex-supervisor" \
  -- node "/absolute/path/to/codex-supervisor-mcp/src/index.mjs"

Verwenden Sie das Pfadlisten-Trennzeichen der Plattform zwischen den Roots. Auf macOS und Linux ist es ein Doppelpunkt (:).

Windows PowerShell

codex mcp add codex-supervisor `
  --env CODEX_ALLOWED_ROOTS="C:\src;D:\work" `
  --env CODEX_SUPERVISOR_MCP_NAME="codex-supervisor" `
  -- node "C:\absolute\path\to\codex-supervisor-mcp\src\index.mjs"

Unter Windows ist das Pfadlisten-Trennzeichen ein Semikolon (;).

Bestätigen Sie die Registrierung:

codex mcp list

Geben Sie in Codex /mcp ein, um den verbundenen Server zu überprüfen.

Installation mit config.toml

Kopieren und passen Sie examples/config.toml an, und legen Sie den Inhalt in ~/.codex/config.toml oder im .codex/config.toml eines vertrauenswürdigen Projekts ab.

Verwenden Sie absolute Pfade. Lassen Sie die Server-ID und CODEX_SUPERVISOR_MCP_NAME identisch.

ChatGPT-Desktop oder die Codex-IDE-Erweiterung

1. Öffnen Sie Einstellungen → MCP-Server → Server hinzufügen.

2. Setzen Sie den Namen auf codex-supervisor.

3. Wählen Sie STDIO.

4. Setzen Sie den Befehl auf node.

5. Fügen Sie den absoluten Pfad zu src/index.mjs als einziges Argument hinzu.

6. Fügen Sie CODEX_ALLOWED_ROOTS und CODEX_SUPERVISOR_MCP_NAME=codex-supervisor hinzu.

7. Speichern Sie und starten Sie den Host neu.

8. Geben Sie /mcp ein, um die Tools zu überprüfen.

Lokale STDIO-MCP-Server werden von normalen ChatGPT-Web-Chats nicht geladen. Die Nutzung dieser Brücke über das Web erfordert einen separat bereitgestellten, authentifizierten Remote-MCP-Dienst oder ein gehostetes Plugin.

Typischer Arbeitsablauf

Bitten Sie den MCP-Host:

Use codex_start in /absolute/path/to/repository to implement the requested
change. Use workspaceWrite, keep network access disabled, wait for progress,
show me every approval request before resolving it, and report the final diff
and test result.

Der Host sollte dieser Reihenfolge folgen:

codex_start -> codex_wait
  approval request -> inspect -> codex_resolve_approval -> codex_wait
  active correction -> codex_steer -> codex_wait
  completed -> codex_status
  later follow-up -> codex_send -> codex_wait

Jeder Start-/Sende-/Steuer-/Unterbrechungsaufruf gibt einen eventCursor zurück. Übergeben Sie ihn als afterSequence an codex_wait oder codex_status, um die Wiedergabe älterer Ereignisse zu vermeiden.

approvalPolicy akzeptiert die aktuellen App-Server-Drahtwerte on-request (Standard) und untrusted. Die Legacy-Werte onRequest und unlessTrusted werden von der Brücke akzeptiert und vor der App-Server-Anfrage normalisiert.

Die öffentliche Genehmigungs-API akzeptiert decline, selbst wenn eine Codex-App-Server-Version für die Anfrage nur cancel angibt. In diesem Fall verwendet die Brücke die sichere App-Server-Stornierungsantwort und meldet sowohl die angeforderte als auch die tatsächlich wirksame Entscheidung.

Konfiguration

Die Standard-App-Server-Argumente entsprechen:

-c mcp_servers.<CODEX_SUPERVISOR_MCP_NAME>.enabled=false app-server

Das Überschreiben von CODEX_APP_SERVER_ARGS entfernt diesen Rekursionsschutz. Fügen Sie selbst einen entsprechenden Deaktivierungs-Override hinzu.

Sicherheitsmodell

• CODEX_ALLOWED_ROOTS ist obligatorisch.

• Pfade werden mit realpath kanonisiert; Symlink-Ausbrüche werden abgelehnt.

• Codex erhält eingeschränkten Lesezugriff auf das ausgewählte Repository und die Plattformstandards.

• workspaceWrite begrenzt beschreibbare Roots auf das ausgewählte Repository.

• dangerFullAccess wird nicht verfügbar gemacht.

• Netzwerkzugriff erfordert sowohl CODEX_ALLOW_NETWORK=1 als auch networkAccess: true bei einer Aufgabe.

• Die Brücke hat kein generisches, nicht-sandboxed Shell-Tool.

• Genehmigungen für Befehlsausführung und Dateiänderungen müssen explizit aufgelöst werden.

• Threads außerhalb der erlaubten Roots werden abgelehnt oder gefiltert.

• Ereignisnutzlasten werden vor der Speicherung in ihrer Größe begrenzt.

• Gespeicherte Thread-Pfade werden bei der Verwendung erneut kanonisiert; gelöschte oder ersetzte Repository-Pfade schließen sicher fehl (fail closed).

• Mutationen innerhalb desselben Threads, Genehmigungsantworten und wiederholte Remote-Aufrufe werden serialisiert oder dedupliziert, anstatt zweimal ausgeführt zu werden.

• Transportfehler werden rekursiv geschwärzt und in der Größe begrenzt, bevor sie STDIO- oder HTTP-Grenzen überschreiten.

• Relay- und Remote-Server-Anmeldedaten (BIOTELE_* und CODEX_REMOTE_*) werden aus der untergeordneten Codex-Umgebung entfernt.

• Remote-Ergebniseinreichungen werden HMAC-authentifiziert, base64url-kodiert, in begrenzte Blöcke aufgeteilt und vor der Verwendung anhand von Länge und SHA-256 verifiziert. Die Kodierung schützt den Transport vor Inhaltsfiltern; sie ist keine Verschlüsselung.

Der untergeordnete App-Server erbt weiterhin Nicht-Relay-Prozesseinstellungen und Ihre umfassendere Codex-Konfiguration. Prüfen Sie andere Umgebungsgeheimnisse, Apps, Skills, Hooks und konfigurierte MCP-Server, bevor Sie ihn mit nicht vertrauenswürdigem Code verwenden. Das Entfernen von Umgebungsvariablen ist keine Sicherheitsgrenze des Betriebssystems: Ein untergeordneter Prozess, der als derselbe Windows-Benutzer läuft, kann gezielt benutzerspezifische Einstellungen abfragen. Verwenden Sie ein dediziertes Windows-Konto, wenn diese Bedrohung relevant ist.

Unterstützte Genehmigungsanfragen

Diese Version bearbeitet:

• item/commandExecution/requestApproval

• item/fileChange/requestApproval

Andere App-Server-Anfragen bleiben über codex_status und codex_list_approvals sichtbar, aber die Brücke weigert sich, sie zu beantworten. Dies verhindert, dass ein generischer Antwort-Endpunkt stillschweigend Berechtigungen erteilt oder sensible Benutzereingaben liefert.

Persistenz und Überwachung

Codex besitzt den persistierten Thread-Verlauf. Die Brücke hält gestreamte Ereignispuffer, letzte Deltas und den Zustand ausstehender Anfragen im Speicher. Ein Neustart des MCP-Servers löscht diesen transienten Zustand, aber codex_list_threads und codex_read_thread können autorisierte persistierte Threads wiederherstellen.

Entwicklung

npm test
node --check src/index.mjs

Projektstruktur:

src/app-server-client.mjs  Codex app-server JSONL client
src/approval-policy.mjs    Approval-policy validation and legacy normalization
src/event-store.mjs        Bounded event, turn, and approval state
src/security.mjs           Repository-root policy
src/supervisor-service.mjs Codex lifecycle orchestration
src/tool-registry.mjs      MCP tool schemas and validation
src/mcp-server.mjs         Dual-era MCP STDIO transport
src/index.mjs              Entrypoint
test/                      Unit and integration tests

Lizenz

MIT

Kompatibilität mit dem Codex App Server

Version 1.0.3 entfernt die veralteten Felder readOnly.access und workspaceWrite.readOnlyAccess aus turn/start. Aktuelle Codex-App- Server-Versionen verwenden Berechtigungsprofile, wenn ein Client benutzerdefinierte eingeschränkte Lesebereiche benötigt. Der Supervisor schränkt beschreibbare Roots weiterhin auf das ausgewählte Repository ein und validiert jedes Aufgabenverzeichnis gegen CODEX_ALLOWED_ROOTS.

Hostinger-Remote-Relay

Version 1.2.5 bietet ein Hostinger-kompatibles Relay für den Remote-MCP-Zugriff von ChatGPT:

ChatGPT -> OAuth bearer JWT -> Hostinger /mcp -> namespace-routed queue
  codex_*  -> outbound Windows local-agent -> Codex app-server
  reeves_* -> outbound Reeves Android agent -> accessibility service

Der öffentliche /mcp-Endpunkt validiert RS256-OAuth-Zugriffstokens von einem externen Identitätsanbieter. Die Windows- und Reeves-Agenten verwenden unabhängige HMAC- Anmeldedaten nur für ausgehendes Polling, Status, Leasing-Erwerb und Ergebniseinreichung. Das Hostinger-Relay startet Codex nie und liest niemals lokale Repositorys.

Das gehostete Relay behält alle vorhandenen codex_*-Tools und stellt zusätzlich reeves_status, reeves_tap, reeves_swipe, reeves_type, reeves_back, reeves_home, reeves_recents, reeves_sequence und reeves_screenshot bereit. Die lokale STDIO-Codex- Registrierung bleibt Codex-only. Agentenansprüche werden nach authentifizierter Schlüssel-ID gefiltert; vom Client gelieferte Routing-Felder werden ignoriert.

reeves_screenshot gibt Android-Pixel als standardmäßigen MCP-image-Inhaltsblock zurück (image/png mit Base64-Daten) zusammen mit Breite, Höhe, Aufnahmezeitstempel, Agenten-ID und Byte-Längen-Metadaten. Der Android-Agent verwendet das vom Relay angekündigte Chunk-Ergebnisprotokoll, sodass kein unbrauchbarer Android-lokaler Pfad offengelegt wird und jede signierte HTTP-Anfrage innerhalb des Relay-Body-Limits bleibt.

reeves_sequence sendet 1 bis 50 geordnete Geräteaktionen in einem gerouteten Auftrag. Android führt Tipp-, Wisch-, Eingabe-, Zurück-, Home-, Recents-, Warte- und Screenshot-Aktionen lokal aus, stoppt standardmäßig beim ersten Fehler und gibt standardmäßig ein abschließendes MCP- Bild zurück. Die Ergebnisse enthalten indizierte Aktionsergebnisse und additive, geheimnisfreie Relay/Android-Phasenzeitmessungen. Die bestehende 25-Sekunden-Agentenanfrage ist ein Wake-on-Enqueue-Long-Poll und keine Abholverzögerung; Android startet nach jeder erfolgreichen Ergebniseinreichung sofort einen weiteren Claim und nutzt denselben OkHttp- Verbindungspool erneut.

Diese Version verhandelt außerdem eine unterstützte MCP-Protokollversion, stellt eine begrenzte, an den OAuth-Betreff gebundene Sitzung aus und verlangt diese Sitzung bei Folgeanfragen. Wiederholte Tool-Aufrufe sind an den OAuth-Betreff, die MCP-Sitzung, die typisierte JSON-RPC- ID und den Anforderungshash gebunden; das Beenden einer Sitzung macht ihre zwischengespeicherten oder ausstehenden Arbeiten ungültig. Die Version bereinigt außerdem abgebrochene Relay-Arbeiten und abgestürzte App-Server- Zustände, validiert autorisierte Pfade neu, isoliert Ereignisse pro Thread und schwärzt begrenzte verschachtelte Fehlerdaten an jedem öffentlichen Transport.

Version 1.2.5 gleicht außerdem codex_status.latestAgentMessage mit dem autorisierten persistierten Transkript ab. Vollständig persistierte externe Codex-Vervollständigungen, einschließlich synthetisierter rollout-*-Turns, ersetzen nun veraltete, von der Brücke beobachtete Nachrichten, während unvollständige oder unterbrochene Transkript-Enden ausgeschlossen bleiben.

Stellen Sie das aktualisierte Relay bereit, bevor Sie den Windows-Agenten aktualisieren. Das neue Relay akzeptiert weiterhin Legacy-Einmalergebnisse, während der neue Agent das Chunk-Format nur verwendet, nachdem das Relay Unterstützung angekündigt hat.

Siehe docs/REMOTE_DEPLOYMENT.md für Hostinger-hPanel-Schritte, DNS für mcp.biotele.mx, Auth0-Einrichtung, Microsoft-Entra-ID-Einrichtung, Einrichtung und Wiederherstellung des ChatGPT-Web-Connectors, Umgebungsvariablen, lokale Agenteninstallation und das Bedrohungsmodell.