Codex Supervisor MCP

Un puente local del Model Context Protocol (MCP) que permite a un host compatible iniciar, supervisar, guiar, interrumpir, reanudar y aprobar el trabajo del app-server de Codex.

Envuelve a codex app-server; no automatiza una interfaz de terminal ni extrae contenido de un IDE.

Capacidades

El servidor expone estas herramientas MCP:

Related MCP server: Codex Bridge MCP

Requisitos

• Node.js 22 o más reciente.

• Una CLI de Codex actual disponible como codex.

• Autenticación de la CLI de Codex ya configurada.

• Una o más raíces de repositorio locales explícitas.

Este proyecto no tiene dependencias de ejecución npm.

Verificación del paquete

npm test

El conjunto de pruebas utiliza un app-server simulado compatible con el protocolo. No realiza solicitudes de modelo ni requiere autenticación de Codex.

Instalación con la CLI de Codex

Utiliza el nombre de servidor MCP codex-supervisor. El nombre debe coincidir con CODEX_SUPERVISOR_MCP_NAME; el puente lo usa para evitar que el app-server hijo cargue este mismo servidor MCP de forma recursiva.

macOS o 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"

Usa el delimitador de lista de rutas de la plataforma entre raíces. En macOS y Linux es un signo de dos puntos (:).

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"

En Windows el delimitador de lista de rutas es un punto y coma (;).

Confirma el registro:

codex mcp list

En Codex, escribe /mcp para inspeccionar el servidor conectado.

Instalación con config.toml

Copia y adapta examples/config.toml y luego coloca su contenido en ~/.codex/config.toml o en el .codex/config.toml de un proyecto de confianza.

Usa rutas absolutas. Mantén el id del servidor y CODEX_SUPERVISOR_MCP_NAME idénticos.

ChatGPT desktop o la extensión del IDE de Codex

1. Abre Configuración → Servidores MCP → Añadir servidor.

2. Establece el nombre como codex-supervisor.

3. Selecciona STDIO.

4. Establece el comando como node.

5. Añade la ruta absoluta a src/index.mjs como único argumento.

6. Añade CODEX_ALLOWED_ROOTS y CODEX_SUPERVISOR_MCP_NAME=codex-supervisor.

7. Guarda y reinicia el host.

8. Escribe /mcp para verificar las herramientas.

Los servidores MCP STDIO locales no se cargan en los chats web normales de ChatGPT. Usar este puente desde la web requiere un servicio MCP remoto autenticado desplegado por separado o un plugin alojado.

Flujo de trabajo típico

Pide al host MCP que:

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.

El host debe seguir esta secuencia:

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

Cada llamada start/send/steer/interrupt devuelve un eventCursor. Pásalo como afterSequence a codex_wait o codex_status para evitar reproducir eventos antiguos.

approvalPolicy acepta los valores de cable actuales del app-server on-request (por defecto) y untrusted. Los valores heredados onRequest y unlessTrusted son aceptados por el puente y normalizados antes de la solicitud al app-server.

La API pública de aprobación acepta decline incluso cuando una versión del app-server de Codex anuncia solo cancel para la solicitud. En ese caso, el puente usa la respuesta de cancelación segura del app-server e informa tanto la decisión solicitada como la efectiva.

Configuración

Los argumentos por defecto del app-server son equivalentes a:

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

Sobrescribir CODEX_APP_SERVER_ARGS elimina esa protección contra la recursión. Incluye tú mismo una anulación de deshabilitación equivalente.

Modelo de seguridad

• CODEX_ALLOWED_ROOTS es obligatoria.

• Las rutas se canonizan con realpath; se rechazan los escapes de enlaces simbólicos.

• Codex recibe acceso de lectura restringido al repositorio seleccionado y a los valores predeterminados de la plataforma.

• workspaceWrite limita las raíces escribibles al repositorio seleccionado.

• dangerFullAccess no está expuesto.

• El acceso a la red requiere tanto CODEX_ALLOW_NETWORK=1 como networkAccess: true en una tarea.

• El puente no tiene una herramienta de shell genérica y sin sandbox.

• Las aprobaciones de comandos y cambios de archivos deben resolverse explícitamente.

• Los hilos fuera de las raíces permitidas se deniegan o filtran.

• Las cargas útiles de eventos tienen un tamaño limitado antes de almacenarse.

• Las rutas de hilos almacenadas se vuelven a canonizar en el momento de uso; las rutas de repositorio eliminadas o reemplazadas fallan en modo cerrado (fail closed).

• Las mutaciones del mismo hilo, las respuestas de aprobación y las llamadas remotas reintentadas se serializan o deduplican en lugar de ejecutarse dos veces.

• Los errores de transporte se redactan recursivamente y se limita su tamaño antes de cruzar los límites de STDIO o HTTP.

• Las credenciales de relay y del servidor remoto (BIOTELE_* y CODEX_REMOTE_*) se eliminan del entorno de Codex hijo.

• Los envíos de resultados remotos se autentican con HMAC, se codifican en base64url, se dividen en fragmentos limitados y se verifican por longitud y SHA-256 antes de su uso. La codificación protege el transporte de los filtros de contenido; no es cifrado.

El app-server hijo todavía hereda la configuración de procesos que no son de relay y tu configuración general de Codex. Audita otros secretos del entorno, aplicaciones, skills, hooks y servidores MCP configurados antes de usarlo con código no confiable. La eliminación de variables de entorno no es un límite de seguridad del sistema operativo: un hijo que se ejecuta como el mismo usuario de Windows puede consultar deliberadamente ajustes con ámbito de usuario. Usa una cuenta de Windows dedicada si esa amenaza está dentro del alcance.

Solicitudes de aprobación compatibles

Esta versión resuelve:

• item/commandExecution/requestApproval

• item/fileChange/requestApproval

Otras solicitudes del app-server permanecen visibles a través de codex_status y codex_list_approvals, pero el puente se niega a responderlas. Esto evita que un endpoint de respuesta genérico conceda permisos silenciosamente o proporcione información sensible del usuario.

Persistencia y supervisión

Codex posee el historial persistido de los hilos. El puente mantiene en memoria los búferes de eventos transmitidos, los últimos deltas y el estado de solicitudes pendientes. Reiniciar el servidor MCP borra ese estado transitorio, pero codex_list_threads y codex_read_thread pueden recuperar hilos persistidos autorizados.

Desarrollo

npm test
node --check src/index.mjs

Estructura del proyecto:

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

Licencia

MIT

Compatibilidad de Codex App Server

La versión 1.0.3 elimina los campos obsoletos readOnly.access y workspaceWrite.readOnlyAccess de turn/start. Las versiones actuales de Codex App Server usan perfiles de permisos cuando un cliente necesita ámbitos de lectura restringidos personalizados. El supervisor continúa restringiendo las raíces escribibles al repositorio seleccionado y valida cada directorio de tarea contra CODEX_ALLOWED_ROOTS.

Relay remoto de Hostinger

La versión 1.2.5 proporciona un relay compatible con Hostinger para el acceso MCP remoto de 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

El endpoint público /mcp valida tokens de acceso OAuth RS256 de un proveedor de identidad externo. Los agentes de Windows y Reeves usan credenciales HMAC independientes solo para el sondeo saliente, el estado, la adquisición de arrendamiento y el envío de resultados. El relay de Hostinger nunca inicia Codex ni lee repositorios locales.

El relay alojado mantiene todas las herramientas codex_* existentes y además expone reeves_status, reeves_tap, reeves_swipe, reeves_type, reeves_back, reeves_home, reeves_recents, reeves_sequence y reeves_screenshot. El registro local de Codex STDIO sigue siendo exclusivo de Codex. Las afirmaciones de los agentes se filtran por ID de clave autenticado; los campos de enrutamiento proporcionados por el cliente se ignoran.

reeves_screenshot devuelve píxeles de Android como un bloque de contenido image estándar de MCP (image/png con datos base64) junto con el ancho, la altura, la marca de tiempo de captura, el id del agente y los metadatos de longitud en bytes. El agente de Android usa el protocolo de resultados fragmentados anunciado por el relay, por lo que no se expone ninguna ruta local de Android inutilizable y cada solicitud HTTP firmada permanece dentro del límite del cuerpo del relay.

reeves_sequence envía de 1 a 50 acciones de dispositivo ordenadas en un solo trabajo enrutado. Android ejecuta localmente las acciones tap, swipe, type, Back, Home, Recents, wait y screenshot, se detiene ante el primer error de forma predeterminada y devuelve una única imagen MCP final por defecto. Los resultados incluyen resultados de acciones indexadas y tiempos de fase aditivos y sin secretos del relay/Android. La solicitud de agente existente de 25 segundos es un long-poll de activación al encolar, no un retraso de recogida; Android inicia inmediatamente otra reclamación después de cada envío de resultado exitoso y reutiliza un mismo grupo de conexiones OkHttp.

Esta versión también negocia una versión compatible del protocolo MCP, emite una sesión limitada vinculada al sujeto OAuth y exige esa sesión en solicitudes posteriores. Las llamadas a herramientas reintentadas se vinculan al sujeto OAuth, la sesión MCP, el id JSON-RPC tipado y el hash de la solicitud; finalizar una sesión invalida su trabajo en caché o pendiente. La versión también limpia el trabajo de relay cancelado y el estado del app-server bloqueado, revalida las rutas autorizadas, aísla los eventos por hilo y redacta datos de error anidados limitados en cada transporte público.

La versión 1.2.5 también concilia codex_status.latestAgentMessage con la transcripción persistida autorizada. Las completaciones externas de Codex totalmente persistidas, incluidos los turnos rollout-* sintetizados, ahora reemplazan los mensajes obsoletos observados por el puente, mientras que las colas de transcripción incompletas o interrumpidas permanecen excluidas.

Despliega el relay actualizado antes de actualizar el agente de Windows. El nuevo relay todavía acepta resultados únicos heredados, mientras que el nuevo agente usa el formato fragmentado solo después de que el relay anuncie soporte.

Consulta docs/REMOTE_DEPLOYMENT.md para los pasos de hPanel de Hostinger, DNS para mcp.biotele.mx, configuración de Auth0, configuración de Microsoft Entra ID, configuración y recuperación del conector web de ChatGPT, variables de entorno, instalación del agente local y el modelo de amenazas.