codex-mcp-bridge

Versión en inglés

Servidor MCP para Claude Desktop que envía prompts directamente a un hilo de Codex existente, a través de un app-server de Codex compartido. Se ejecuta en macOS, Windows y Linux.

No es codex exec (que crea una sesión nueva cada vez). El bridge habla JSON-RPC con el app-server real de Codex, por lo que el hilo conserva el historial, el cwd, el modelo y el archivo de rollout.

Arquitectura

Claude Desktop ──stdio──> codex-mcp-bridge ──WebSocket──> codex app-server (ws://127.0.0.1:8791)
                                                                  │
Codex TUI  ──codex --remote ws://127.0.0.1:8791───────────────────┘   (cùng app-server, cùng thread live)

• El app-server es un singleton por puerto. El bridge comprueba http://127.0.0.1:8791/readyz; si no está vivo, lo lanza como proceso independiente (codex app-server --listen ws://127.0.0.1:8791) y ese app-server sigue ejecutándose de forma independiente después de que el bridge salga.

• Todos los clientes que apuntan a la misma URL usan el mismo app-server → thread/resume con el threadId se reincorporará al hilo correcto en ejecución en lugar de abrir una sesión nueva.

• El bridge mantiene un único WebSocket, hace initialize una sola vez y enruta las notificaciones según el threadId, de modo que varios hilos ejecutándose en paralelo no se mezclan.

Related MCP server: webgpt MCP

Herramientas

send_to_codex_thread acepta además timeoutSec (por defecto 240), cwd, model, effort y openInApp (macOS: abre el hilo en la aplicación antes de enviar para verlo en vivo). Cuando se agota el tiempo de espera no se cancela el turno; el bridge devuelve lo que haya recopilado junto con el turnId; puedes seguir leyendo con read_codex_thread o detenerlo con interrupt_codex_turn.

Instalación en Claude Desktop

npm install
node scripts/install-claude-desktop.mjs

El script detecta automáticamente la plataforma, crea el archivo de configuración si no existe, respalda el anterior (*.bak-<ngày>-codexbridge) y conserva todas las claves existentes:

Resultado en macOS:

{
  "mcpServers": {
    "codex-bridge": {
      "command": "/Users/<user>/.local/node/v24.18.0/bin/node",
      "args": ["/Users/<user>/code/codex-mcp-bridge/src/index.mjs"],
      "env": {
        "CODEX_BIN": "/Users/<user>/.local/bin/codex",
        "CODEX_APP_SERVER_URL": "ws://127.0.0.1:8791"
      }
    }
  }
}

Reinicia Claude Desktop después de la instalación.

Resolución del binario codex: Claude Desktop (y launchd) inician el servidor MCP con un PATH reducido, por lo que codex normalmente no está en el PATH. El bridge busca en este orden — CODEX_BIN → ubicaciones de instalación habituales de la plataforma → PATH:

En macOS/Linux, codex es un script de Node con shebang #!/usr/bin/env node, así que el bridge también inyecta de nuevo el PATH (directorio actual de node + /opt/homebrew/bin + /usr/local/bin + directorios del sistema) a los procesos hijo; sin este paso, el app-server generado muere justo en el shebang.

macOS

App-server en segundo plano con launchd

node scripts/install-launch-agent.mjs

Crea ~/Library/LaunchAgents/com.codex-mcp-bridge.app-server.plist (RunAtLoad + KeepAlive al fallar, ThrottleInterval 10s) y luego launchctl bootstrap gui/$UID. El app-server ya está vivo desde el inicio de sesión, por lo que el bridge no tiene que generarlo, y el hilo siempre está en estado en vivo.

launchctl print gui/$UID/com.codex-mcp-bridge.app-server | head -20   # trạng thái
node scripts/install-launch-agent.mjs --uninstall                     # gỡ

Registro: ~/Library/Logs/codex-mcp-bridge/app-server.{out,err}.log.

Ver el hilo directamente en la aplicación de escritorio de Codex

La aplicación de escritorio de Codex en macOS es /Applications/ChatGPT.app y registra el esquema codex://. El bridge usa codex://threads/<threadId> para abrir el hilo correcto:

open_codex_thread { threadId: "01a0…", background: true }
send_to_codex_thread { threadId: "01a0…", prompt: "…", openInApp: true }

Así es como quien asigna la tarea puede ver lo que Codex está haciendo en lugar de tener que releer el rollout ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl al terminar.

Limitaciones en macOS

• La aplicación de escritorio de Codex ejecuta su propio app-server a través de stdio (ChatGPT.app/Contents/Resources/codex … app-server) y no acepta endpoints externos. Los hilos abiertos en la aplicación sí se pueden enviar a través del bridge, pero mediante el mecanismo de reanudación desde el rollout .jsonl, no como adjunto en vivo. No envíes a un hilo que esté ejecutando un turno en la aplicación de escritorio: dos app-server escribiendo en el mismo rollout pueden dañar el historial. Comprueba el status con list_codex_threads antes y envía solo cuando esté idle/notLoaded.

• Un repositorio en una partición NTFS de un equipo de doble arranque (/Volumes/...) es solo de lectura en macOS: macOS monta NTFS en modo de solo lectura. Mantén un checkout propio en un disco APFS (p. ej. ~/code/codex-mcp-bridge) para ejecutarlo y modificarlo.

• codex app-server daemon start usa el transporte unix:// con un socket de control ~/.codex/app-server-control/app-server-control.sock. El bridge no usa esta vía (protocolo de trama distinto al de WebSocket, sin API pública todavía): siempre se comunica a través de ws://.

Variables de entorno

Sobre la aprobación: Codex pedirá aprobación para comandos/parches si approval_policy no es never. Como no hay nadie delante de Claude Desktop para hacer clic, el bridge responde automáticamente según CODEX_BRIDGE_APPROVAL y lo registra en stderr. El valor por defecto approve coincide con la configuración approval_policy = "never" + sandbox_mode = "danger-full-access" en ~/.codex/config.toml; si restringes el sandbox, considera cambiarlo a deny.

Compartir el app-server con una sesión interactiva de Codex

Abre la TUI apuntando al mismo endpoint para que el hilo de la TUI y el hilo del bridge se vean como uno solo:

codex --remote ws://127.0.0.1:8791

Ejecuta el app-server manualmente (sin depender del autostart del bridge):

codex app-server --listen ws://127.0.0.1:8791

Pruebas

npm run check

Comprobación rápida: el bridge arranca, inicia el app-server automáticamente si es necesario y lista los hilos.

npm run smoke

Smoke test: crea un hilo nuevo, envía 2 turnos consecutivos y comprueba que Codex recuerda la palabra clave del turno anterior; es decir, el hilo es realmente continuo y no una sesión nueva cada vez.

Para comprobar el entorno desde Claude: llama a la herramienta codex_bridge_status.