mcp-agents

Servidor MCP que envuelve herramientas CLI de IA — Claude Code, Antigravity CLI (agy) y Codex CLI — y puede actuar como proxy de Chrome DevTools MCP hacia un navegador alquilado de forma remota.

Requisitos previos

• Node.js >= 26

• Al menos una de las siguientes CLI instalada y en tu $PATH:

Solo la CLI que selecciones con --provider necesita estar presente.

Related MCP server: claudecode-mcp

Instalación

npm install -g mcp-agents

La instalación global es la vía de inicio más rápida y fiable. npx -y mcp-agents es funcionalmente equivalente una vez que el servidor MCP está en ejecución, pero el arranque depende de la resolución/estado de caché del paquete npm antes de que el cliente MCP pueda conectarse.

Consejo: Si el .mcp.json de tu proyecto hace referencia a mcp-agents, añade npm install -g mcp-agents a tu script de configuración (p. ej. bin/setup) para que los nuevos desarrolladores lo obtengan automáticamente.

Prueba rápida

# 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"]'

El servidor habla JSON-RPC sobre stdio. Imprime [mcp-agents] listo (proveedor: <nombre>) en stderr cuando está escuchando.

Proveedores y herramientas

Cada indicador --provider selecciona un backend CLI:

Reseñas de Claude

Para opiniones sustanciales y revisiones de código, utiliza las herramientas en segundo plano:

1. Llama a claude-start con el prompt de revisión completo y un cwd absoluto.

2. Llama a claude-status con el jobId y cursor devueltos. Repite con cada nuevo cursor hasta que el estado sea terminal.

3. Cuando el estado sea completed, llama a claude-result. Continúa desde nextOffset hasta que done sea true.

4. Llama a claude-cancel si el veredicto ya no es necesario.

claude-status realiza sondeos largos durante 10 segundos por defecto y acepta wait_ms hasta 60 segundos. Cancelar un sondeo de estado no cancela su trabajo. Los trabajos son únicos y locales a la conexión MCP actual: no hay sesiones de respuesta, y una desconexión cancela el trabajo activo. El servidor permite 8 trabajos activos y 32 retenidos, conserva los trabajos terminales durante una hora, pagina los resultados en 32 768 puntos de código Unicode y rechaza un resultado final superior a 10 MiB.

Las revisiones en segundo plano tienen un plazo de dos horas de propiedad del puente. Los operadores pueden reemplazarlo con --timeout <segundos> al iniciar el servidor; los llamadores no pueden acortar un trabajo con timeout_ms. Claude está fijado a claude-opus-4-8 con esfuerzo xhigh y se ejecuta como revisor hoja: conserva las instrucciones del proyecto y el contexto del repositorio, pero deshabilita hooks, subagentes, habilidades, comandos de barra, servidores MCP externos y herramientas de mutación. Solo están disponibles Read, Glob, Grep e inspección Bash de solo lectura; la instrucción hoja también prohíbe la ejecución de pruebas, instalaciones, delegación y efectos secundarios. La salida intermedia del modelo, los resultados de las herramientas, las rutas y el razonamiento no se reenvían a través de MCP; solo se exponen el estado de fase saneado y el veredicto final.

Utiliza la herramienta bloqueante claude_code solo para prompts pequeños donde una única llamada MCP pueda completarse cómodamente dentro del tiempo de espera del cliente.

Parámetros de claude_code

Cualquier argumento adicional de tools/call se ignora (por ejemplo, model, effort o config).

Claude está fijado a claude-opus-4-8 con esfuerzo xhigh; los llamadores no pueden cambiar el modelo ni el esfuerzo por llamada. Las llamadas se ejecutan con --output-format json; el servidor analiza la carga útil JSON y devuelve el texto del resultado del asistente (o un error MCP si is_error=true). El valor predeterminado más largo permite revisiones profundas de Opus; los llamadores pueden establecer un timeout_ms menor, y los operadores pueden anular el valor predeterminado con --timeout <segundos>.

Parámetros de gemini

Cualquier argumento adicional de tools/call se ignora (por ejemplo, model o model_reasoning_effort).

agy siempre se ejecuta con --sandbox (restricciones de terminal activadas); no hay conmutador de sandbox por llamada.

browser (pass-through de Chrome remoto)

El proveedor de navegador inicia un servidor local chrome-devtools-mcp inmediatamente y luego adquiere de forma diferida una concesión de Chrome remoto en la primera llamada de herramienta de navegador anunciada. El servidor MCP y todos los archivos que escribe permanecen locales; solo el CDP cruza el túnel de retorno proporcionado por el operador. Las llamadas que llegan durante la adquisición comparten un único intento de aprovisionamiento y permanecen en orden FIFO. No hay herramientas propias de adquisición, estado, liberación, trabajo o cancelación.

Configuración rápida con crabbox

Ideal para crabbox: cajas efímeras de un solo inquilino que mueren por sí solas al alcanzar sus límites: la vida útil que una concesión de navegador necesita, sin necesidad de desmontaje manual.

Tu helper de acquire hace cuatro cosas: alquila una caja; inicia Chromium en ella con --remote-debugging-port=<remoto>; abre ssh -L 127.0.0.1:<puerto-cdp-local>:127.0.0.1:<remoto> (añade un -R coincidente para --app-port cuando la página bajo prueba se sirve desde tu máquina); y entonces, cuando /json/version responda en el puerto local, imprime:

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 vuelve a comprobar esa concesión, release la derriba, y cualquier código de salida 69 mantiene el carril con cierre ante fallos.

El proveedor no tiene conocimiento de la nube ni de SSH. Un comando inyectado es el dueño de la concesión y recibe estas formas de argv:

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

La salida exitosa de acquire son datos inertes UTF-8 clave=valor que contienen un registro listo de versión 1, la generación, el puerto CDP local seleccionado y la URL de navegador coincidente. El código de salida 69 es de cierre ante fallos: la llamada devuelve "GUI no verificada — no hay caja de navegador disponible" y nunca inicia un navegador local. Un error de preflight del servidor de desarrollo local informado por el helper se conserva textualmente. El código de salida 75 informa de una carrera de bind en el bucle de retorno; mcp-agents elige un puerto nuevo, reinicia el proceso descendente, reproduce las capacidades originales de initialize de MCP (incluidas roots) y la notificación initialized, y reintenta como máximo tres veces sin exponer un resultado de initialize duplicado.

chrome-devtools-mcp está deliberadamente sin fijar: el respaldo flota a la última versión. Nada aquí depende del comportamiento de reconexión de una versión particular: cada resultado de herramienta de navegador se verifica contra la generación de concesión bajo la que se emitió, informe o no el proceso descendente de una reconexión, de modo que una versión más reciente no pueda debilitar silenciosamente el contrato de cierre ante fallos. La resolución es determinista en este orden:

1. --browser_command o MCP_AGENTS_BROWSER_COMMAND (cadena de comando o argv JSON).

2. Un chrome-devtools-mcp resoluble a nivel de paquete, y luego node_modules/.bin/chrome-devtools-mcp.

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

La tercera vía puede hacer que el primer initialize espere a la resolución de npm. Para un arranque más rápido, instala chrome-devtools-mcp junto a mcp-agents, o instálalo en otro lugar y apunta --browser_command a su ejecutable. Fíjalo allí si necesitas una versión concreta para un despliegue particular. El proceso descendente del navegador requiere las versiones de Node compatibles con la versión de chrome-devtools-mcp a la que resuelve; el mínimo >=26 de este paquete se mantiene en o por encima de eso mientras la dependencia sin fijar sigue a lo último.

chrome-devtools-mcp es intencionadamente una dependencia de desarrollo, no una dependencia de ejecución. Por tanto, un checkout de desarrollador ejercita la vía local del paquete, mientras que los consumidores del paquete publicado usan el respaldo de npx a menos que instalen el paquete junto a mcp-agents o proporcionen un comando explícito.

La ventana gráfica se pasa al helper de concesión para que pueda establecer el tamaño de ventana del Chromium remoto; el --viewport de Chrome DevTools MCP se omite intencionadamente porque es inerte al conectarse mediante --browserUrl.

Cada trama JSON-RPC completa del proceso descendente restablece el temporizador de inactividad de generación; stderr y la salida parcial no lo hacen. La liberación por inactividad tiene un límite de limpieza de 60 segundos para que Chromium remoto, los túneles SSH y la caja puedan detenerse realmente. La liberación por apagado usa un límite separado de 15 segundos y permanece registrada y recolectada. Ambos son optimizaciones de coste de mejor esfuerzo. Si Chrome desaparece, el error de conexión nativa interrumpida no se reproduce. Un estado de helper de 69 lo enriquece con browser_lease_replaced, advirtiendo explícitamente de que el navegador fue reemplazado, se perdió el estado, se desconoce el resultado interrumpido y los llamadores deben inspeccionar el estado en lugar de reproducir a ciegas. El estado 0 conserva el error nativo; el estado 70 permanece desconocido en lugar de ser mal informado como concesión perdida. La siguiente llamada de navegador readquiere y usa la vía de reconexión de Chrome DevTools MCP.

El cliente inicializa el frame y las solicitudes/respuestas posteriores de roots/list se reenvían sin reescritura de ID ni de URI. Tras un reinicio del proceso downstream, las respuestas debidas al proceso terminado se descartan y sus correlaciones de solicitud se retiran antes de que el reemplazo pueda reutilizar un ID. Esto preserva la allowlist local de escritura de archivos de Chrome DevTools MCP, por lo que --allowUnrestrictedPaths nunca se pasa intencionadamente. Los fallos de preflight de App y MinIO se notifican por separado y de forma literal. Las descripciones de rendimiento trace y Lighthouse advierten de que una medición de enlace remoto no es gate, y upload_file advierte de que una ruta local no puede entregarse directamente al Chromium remoto.

Las restricciones de URL son opt-in porque un valor por defecto solo-loopback rompería OAuth y los assets de terceros. Un despliegue reforzado solo-loopback puede repetir, por ejemplo:

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

Utiliza los patrones más estrechos compatibles con la aplicación de destino. El proveedor no habilita el ruteo experimental por ID de página: un proceso es propietario de un arrendamiento, un perfil y un puerto.

codex (pass-through)

El proveedor de codex pasa directamente al servidor MCP nativo de Codex (codex mcp-server) dentro de un CODEX_HOME aislado. El bridge crea cada home bajo el árbol privado tmp/codex-homes/ del directorio de arranque del servidor, copia auth.json, escribe un config.toml mínimo y no si en el directorio de arranque. Eso evita que Codex inicie recursivamente otras herramientas de agente como Claude o Gemini durante las llamadas del bridge. El directorio principal y los generados se crean con el HOME que se crea y estilo 0700; losObjetos de credenciales copiadas y los archivos de tiempo de ejecución generados usan 0600.

El home aislado es un snapshot de autenticación: no puede ver un codex login posterior hasta que el bridge se reconecte. Si Codex reporta su evento terminal de unauthorized tipado, el wrapper suprime el evento duplicado y devuelve un solo error de herramienta MCP con structuredContent.code nset establecer a codex_auth_invalidated y action igual a reauthenticate_and_restart. Los nuevos turnos de Codex se rechazan localmente mientras que estado, resultado, cancelación, peek, ping y otras operaciones Tiempo de ejecución de MCP siguen disponibles. Detén el bridge, ejecuta codex logout y codex login como el mismo usuario del sistema operativo, verifica con codex exec y reconecta. En la limpieza, la autenticación rotada se escribe de nuevo solo cuando la copia aislada cambió y la autenticación canónica sigue coincidiendo con la golden del arranque; un bridge obsoleto, por tanto, no puede sobrescribir un login manual más reciente o la rotación de tokens de otro bridge.

La única preferencia de usuario en la allowlist es el modo Acelerado. Al arrancar, el bridge lee el $CODEX_HOME/config.toml de origen y habilita el modo Acelerado en el home aislado solo cuando encuentra tanto service_tier = "fast" a nivel superior como [features].fast_mode = true. Las configuraciones parciales, deshabilitadas, faltantes o ilegibles mantienen el modo Standard; el resto de la configuración de usuario permanece aislada. Rehabilitate después de cambiar cualquiera de los dos ajustes. El modo Acelerado usa un mayor consumo de créditos de ChatGPT o una facturación Arborrante de API Priority.

Otros ajustes de arranque: sandbox_mode=workspace-write, approval_policy=never (configurable para todo el servidor con --sandbox_mode / --approval_policy), web_search=cached, check_for_update_on_startup=false, allow_login_shell=false y history.persistence=none. Los valores predefinidos de las características fijas del bridge son features.multi_agent=false, features.apps=false, features.plugins=false, features.hooks=false y features.skill_mcp_dependency_install=false; las apps/plugins permanecen deshabilitadas para mantener las skills de las apps/plugins de ChatGPT — Figma, Gmail, Presentaticiones, Presentiations , etc. — fuera del contexto de la sesión del bridge. Los subagentes nativos además se deshabilitan con [agents] enabled = false, porque en Codex >= 0.145.0 la feature flag estabilizada multi_agent ya no elimina por sí sola las herramientas de colaboración; las sessions se registran por llamada con allow_subagents (ver más abajo). Este [agents] es el que se usa en la línea de versión: el bridge sondea codex --version una vez al arrancar y lo omite en Codex < 0.145.0, donde un booleano bajo [agents] es un error fatal de análisis de configuración (0.102–0.144) y la feature flag todavía controla las herramientas de colaboración por sí misma. Una versión no analizable asume Codex moderno.

Las sesiones workspace-write tienen el acceso a red habilitado por defecto para que los comandos sandboxed puedan alcanzar servicios locales como DynamoDB, Redis, OpenSearch y MinIO. Establece --codex-workspace-network=false o MCP_AGENTS_CODEX_WORKSPACE_NETWORK_ACCESS=false para deshabilitarlo en todo el servidor; la CLI flag tiene prioridad sobre la variable de entorno. Esta es una configuración de sandbox propiedad del servidor y está intencionadamente ausente de los esquemas de herramientas por llamada.

Codex no ofrece un alcance solo-loopback para este ajuste. Habilitarlo permite acceso de red saliente general a los comandos en sesiones workspace-write. Las escrituras en el sistema de archivos permanecen restringidas al workspace y otras raíces de escritura configuradas; las sesiones de solo lectura y las de accesso total-dangerous no usan el ajuste sandbox_workspace_write.

El bridge reemplaza el amplio esquema nativo configurado por Codex con un contrato deliberadamente pequeño:

Ambos esquemas establecen additionalProperties: false. Los argumentos no admitidos, faltantes o inválidos se rechazan localmente con JSON-RPC -32602 antes de que se ejecute Codex. Esto incluye escapes nativos como config, approval-policy, developer-instructions, base-instructions y compact-prompt; las ampliaciones de esquema upstream futuras permanecen ocultas hasta que mcp-agents las adopte intencionalmente. Los valores de modelos fuera de las dos opciones seleccionadas se rechazan de la misma manera.

Subagentes nativos. allow_subagents: true en codex o codex-start permite a esa sesión usar las herramientas multi-agente integradas de Codex (spawn_agent, wait_agent, …). Se aplica a nivel de sesióníctamente igual que sandbox: las respuestas lo heredan y no pueden cambiarlo, y está por defecto desactivado. Internamente, la flag solo activa los gates multi-agente nativos (agents.enabled y features.multi_agent, siguiendo el mismo gate de d automatividad), ... ; todo lo demás sobre el home aislado no cambia. En particular, el sarmiento [mcp_servers] sigue en el arranque, spo que los subagentes generados son trabajadores en proceso exclusivamente de Codex: no pueden volver a entrar en este bridge ni alcanzar a Claude, gemini ni en otras herramientas MCP externas, y los roles de agentes personalizados de tu $CODEX_HOME/agents/ real no se copian. El caveŋat residual es la concurrenciencia, no el alcance: los subagentes heredan el sandbox_mode y el approval_policy de la sesión, e bajo workspace-write con approval_policy=never, varios agentes pueden escribir simultáneamente en el mismo workspace. Codex los coordina, pero gira el alcance de la comisión en consecuencia.

approval_policy=never es intencional para un puente MCP: una llamada de herramienta desatendida no puede llevar a cabo una conversación de aprobación interactiva de forma fiable. Los operadores pueden elegir untrusted o on-request para todo el servidor con --approval_policy, pero los llamadores llamadores no pueden debilitar ni cambiar esa política por solicitud. Cada nueva sesión debe todavía declarar explícitamente su sandbox, por lo que la autoridad de escritura es visible en el lugar de la llamada.

Las flags de arranque (--model, --model_reasoning_effort) configuran los valores predeterminados del servidor nativo de Codex aislado en general de dos modelos y cuatro esfuerzos de razonamiento permitidos:

Los selectores se aplican nautomatización solo al crear una sesión. La omisión de cualquiera de los dos usa su predeterminado configurado en el servidor. Cada codex-reply hereda ambas elecciones y no puede cambiarlas usármelo. Otros modelos y niveles de esfuerzo se encuentran deliberadamente deshabilitados mediante el contrato de wrapper cerrado.

Por ejemplo, una revisión de solo lectura también podría comenzar con:

{
  "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"
}

Inyección de objetivos. Define un objetivo predeterminado al arrancar el servidor con --goal "<text>", o pasa goal en una de las llamadas. mcp-agents convierte el objetivo inicial en developer-instructions nativos de Codex internamente:

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

Un mensaje de desarrollador una clave para el hilo, por lo que las "" (las respuestas "» ) lo heredan. Un goal por llamada en el codex-reply se convierte en un recordatorio de solicitud conciso, porque la herramienta nativa de respuesta no tiene un campo developer-instructions No se expone directa: goal es la interfaz estrecha y auditable de objetivo persistente. Un objetivo por permanece La llamada puede anula el valor predeterminado del servidor; "" suprime ese predeterminado para una sola "*".

El bridge reescribe las respuestas tools/list para anunciar estos esquemas seleccionados. Los marcos nativos normales permanecen de una sola forma "byte a byte" excepto el fallo de autenticación tipado descrito anteriormente; los errores de validación y autenticación generados localmente usan la misma disciplina de cola/límite segura que los mensajes de progreso y recuperación.

Precedencia dentro de un hilo. El objetivo establecido en la llamada inicial a codex es un mensaje con rol de desarrollador y persiste durante todo el hilo, por lo que tiene precedencia: un goal diferente suministrado más tarde en un codex-reply es solo un recordatorio a nivel de prompt y no anulará de forma fiable el objetivo vigente (verificado en vivo: un objetivo de respuesta que entre en conflicto con el inicial se ignora en favor del vigente). El recordatorio de respuesta funciona cuando no se opone a un objetivo vigente conflictivo. Para cambiar realmente el objetivo a mitad de camino, inicie una nueva llamada a codex en lugar de cambiarlo en un codex-reply.

Nota: esto no es el /goal nativo de Codex. El comando de barra /goal de Codex (estado de objetivo duradero, con ámbito de hilo, con finalización basada en ciclo de vida/presupuesto/evidencia) es una característica solo de TUI: se analiza en la interfaz de terminal de Codex y no es accesible a través de codex mcp-server. Anteponer /goal … a un prompt de MCP no lo activa; el texto simplemente se pasa como mensaje de usuario. Por lo tanto, este envoltorio dirige a Codex con developer-instructions (el vehículo nativo de MCP para un objetivo vigente), que es un condicionamiento de prompt/rol, no el subsistema nativo de ciclo de vida de objetivos.

Viveza por llamada. El paso a través de Codex rastrea cada tools/call abierto de forma independiente. --codex_idle_timeout <seconds> (por defecto 600, 0 lo desactiva) limita cuánto tiempo puede transcurrir una llamada sin actividad correlacionada de Codex. Solo un evento de Codex que lleve el _meta.requestId de esa llamada (o su respuesta correspondiente o intercambio interactivo) renueva su plazo de inactividad. El stderr de Codex, los pings del cliente, las solicitudes no relacionadas y los eventos que pertenecen a otra llamada no pueden mantener viva una llamada estancada. Si una llamada alcanza su plazo de inactividad, el envoltorio falla solo esa llamada con un error JSON-RPC (-32001), envía a Codex un notifications/cancelled para esa solicitud (con el mejor esfuerzo, por lo que pide a Codex que se detenga en lugar de obligarlo; consulte Cancelación más abajo), suprime la respuesta nativa tardía de la llamada estancada y mantiene la conexión abierta: las llamadas hermanas y el transporte stdio no se ven afectados. Esto es importante porque un cierre del transporte stdio hace que los clientes MCP como Claude Code marquen el servidor como failed y anulen permanentemente el registro de todas las herramientas mcp__codex__* durante el resto de la sesión (los servidores stdio no se reconectan automáticamente), por lo que una única revisión estancada nunca debe derribar todo el puente. El grupo de procesos de Codex aún se recolecta en un cierre real (desconexión del cliente, señal o EPIPE en stdout). La única excepción: si Codex está atascado a mitad de la escritura de un marco de respuesta (sin límite seguro para inyectar el error) y además ignora la cancelación, el envoltorio reintenta una vez y luego escala a un cierre acotado de todo el puente; no hay forma de emitir un marco limpio en uno parcial, por lo que el cliente debe reconectarse a un puente nuevo.

Cancelación. Una cancelación del cliente (notifications/cancelled — cada ESC, turno abortado o desmontaje de subagente) se trata de la misma manera: cuesta exactamente una solicitud. --codex_cancel_grace <seconds> (por defecto 30) limita cuánto tiempo puede tardar Codex en reconocerla; al expirar, el envoltorio resuelve ese id de solicitud localmente, suprime la respuesta tardía de Codex y deja el puente y todas las llamadas hermanas en ejecución. Resolver la solicitud no es prueba de que Codex se detuvo: un turno no reconocido se registra como abandonado y puede seguir ejecutándose y escribiendo. La escalada a mitad de marco descrita anteriormente arma una segunda gracia completa, por lo que esa ruta tarda aproximadamente el doble antes de que el puente finalice. La gracia es generosa a propósito: un Codex a mitad de turno está ejecutando comandos en sandbox y no atiende la cancelación de MCP rápidamente, por lo que una gracia corta haría que la ruta de escalada fuera la ruta predeterminada. Esto importa más que el caso de tiempo de espera porque el CODEX_HOME aislado contiene el directorio sessions/ de Codex: un cierre de todo el puente hace que cada threadId en ese proceso sea permanentemente irrecuperable, y el siguiente codex-reply falla con Session not found.

[!WARNING] Abandonar una solicitud no detiene a Codex. El envoltorio le pide que se detenga, pero un turno que ignora la cancelación sigue ejecutándose — y sigue escribiendo en el espacio de trabajo — mucho después de que el cliente se haya rendido. Cada abandono se registra en stderr con su thread_id y job_id, y se registra de nuevo si el turno termina más tarde, de modo que un árbol modificado inesperadamente pueda explicarse en lugar de adivinarse. Los trabajos en segundo plano son el filo aquí: un trabajo codex-start vive en la tabla de trabajos de este envoltorio, no en el registro de tareas del cliente MCP, por lo que una "detener tarea" del lado del cliente no puede alcanzarlo; solo codex-cancel con su jobId puede hacerlo. Debido a que un trabajo se sondea a través de este proceso, nunca puede sobrevivir a una reconexión, por lo que una desconexión del cliente cancela todo trabajo no terminal y toda solicitud abierta, y un cierre acotado recolecta el grupo de procesos de Codex si sigue trabajando de todos modos.

--timeout <seconds> también se aplica a las llamadas de Codex (por defecto 7200) como un plazo duro inmutable. La actividad correlacionada puede extender la ventana de inactividad, pero nunca este plazo duro. Establezca el plazo del envoltorio por debajo del tiempo de espera de herramienta de reloj de pared del propio cliente MCP cuando el cliente deba recibir siempre el error explícito del envoltorio antes de rendirse.

Cuando la solicitud entrante suministra _meta.progressToken, el envoltorio envía actualizaciones estándar de MCP notifications/progress usando ese token exacto. Nunca inventa un token de progreso. El primer estado útil es inmediato; las actualizaciones posteriores se combinan a lo sumo una por segundo, ganando el estado más reciente. Durante trabajo que de otro modo sería silencioso, se envía un aviso Codex: still running cada 10 segundos e incluye la antigüedad del último evento de Codex correlacionado con la solicitud.

El texto de estado es de cierre ante fallos. El puente expone comentarios atribuidos explícitamente, el paso de plan activo y resúmenes genéricos de ciclo de vida para comandos, parches, herramientas MCP, trabajo web/imagen y subagentes. No expone texto de respuesta final, razonamiento, prompts, cadenas de comandos o su salida, argumentos de herramientas, consultas de búsqueda, rutas de archivos ni telemetría de tokens. Los mensajes se normalizan en espacios en blanco y se limitan a 200 puntos de código Unicode. Los marcos nativos codex/event permanecen sin cambios byte a byte, excepto que un evento de error unauthorized tipado se reemplaza por el único fallo de autenticación estructurado anterior; el progreso es un canal MCP paralelo y normalmente es estado de interfaz en lugar de contexto adicional de resultado de herramienta/modelo.

Trabajos en segundo plano opcionales. Las llamadas existentes a codex y codex-reply siguen siendo bloqueantes y conservan su comportamiento actual. Los clientes que necesiten actualizaciones visibles en la transcripción pueden usar en su lugar las seis herramientas de trabajo propiedad del envoltorio que anuncia el puente de Codex:

Prefiera la llamada bloqueante codex, incluso para construcciones largas. Cuesta una llamada de herramienta en lugar de un turno del llamador por cada cambio de estado, sigue transmitiendo notifications/progress a una interfaz consciente del progreso y se cancela abortando el turno. Recurra a un trabajo solo cuando el trabajo deba sobrevivir al llamador: debe seguir ejecutándose después de que usted deje de esperar, u otro agente debe poder cancelarlo más tarde mediante jobId.

codex-peek — ¿ese turno sigue trabajando?

Una llamada bloqueante es opaca hasta que regresa, lo que hace que "atascado" y "ocupado" parezcan idénticos desde fuera. codex-peek responde eso sin cancelar nada para averiguarlo: enumera cada turno de Codex en vuelo, tanto bloqueante como en segundo plano, de solo lectura e inmediato, y acepta filtros opcionales cwd / threadId / requestId.

No busque un proceso por turno en su lugar: codex mcp-server es de larga duración y multiplexa cada solicitud, por lo que no hay un codex exec que encontrar y una verificación de la tabla de procesos no informa nada mientras se ejecuta una construcción.

Tres respuestas que significan menos de lo que parecen. Una lista vacía no es evidencia de que un turno haya terminado: un turno abandonado sigue ejecutándose dentro de Codex sin nada en vuelo que informar, y su cuenta regresa como abandonedTurnsProcessWide — llamado así por su alcance, porque un turno abandonado no retiene espacio de trabajo y por lo tanto nunca se reduce con un filtro. Un elapsedSeconds grande no es un estancamiento: es solo reloj de pared — y un lastActivitySeconds grande tampoco lo es: una sola llamada de herramienta puede legítimamente permanecer en silencio durante muchos minutos, por lo que el silencio es no probado, nunca terminado. Cancelar para averiguarlo es lo único que no se puede deshacer. Y un filtro cwd nunca oculta un turno cuyo espacio de trabajo es desconocido: lo informa con cwdUnknown, porque "no puedo decirlo" no debe convertirse silenciosamente en "no hay nada ejecutándose allí".

El resultado de inicio regresa inmediatamente con un jobId opaco, un cursor de estado y la siguiente llamada sugerida. Las llamadas repetidas a codex-status producen resultados de herramienta MCP ordinarios, por lo que un agente externo o subagente puede retransmitir lo que Codex está haciendo incluso cuando su interfaz no renderiza notifications/progress — la única visibilidad que ofrece un trabajo y que una llamada bloqueante no ofrece. En el cursor actual, una llamada de estado espera un cambio y luego devuelve un latido; wait_ms puede establecerse de 0 a 60000, y cuando se omite, se establece por defecto al intervalo de estado siguiente (10000 cuando ese ritmo está desactivado).

Dos cosas terminan una espera de estado, y ambas importan para el coste de la consulta. Un avance de cursor se marca al ritmo del servidor mediante --codex_status_interval <seconds> (por defecto 30), que combina el progreso intermedio en lugar de mover el cursor en cada mensaje. El latido wait_ms es la otra, y no está marcado por ese intervalo — así que wait_ms ahora sigue el intervalo de estado (limitado a 60000, de modo que un intervalo superior a 60 segundos sigue latiendo cada 60) para evitar que un latido supere al cursor sobre el que informa. wait_ms sigue siendo un techo para la espera inactiva y nunca un suelo para el espaciado de consultas: una llamada de estado regresa inmediatamente siempre que el cursor ya esté por detrás de la cabeza, de modo que un poller que se ha quedado atrás no puede ser ralentizado subiéndolo — pero uno que está al día sí puede, razón por la cual bajar wait_ms cuesta turnos para nada.

Solo las actualizaciones de progreso intermedias están marcadas; las transiciones de ciclo de vida — el primer running, una cancelación y cualquier estado terminal — mueven el cursor y despiertan a cada esperador directamente, omitiendo el intervalo, de modo que subirlo nunca retrasa la finalización. La detección de bloqueos tampoco se ve afectada — lastActivitySeconds se sella a partir de eventos Codex en bruto, no de ticks de estado — y codex-commentary conserva la narrativa completa. 0 restaura un avance de cursor en cada cambio; valores superiores a 60 dejan que el techo del latido tome el control y solo permiten que el texto de estado quede obsoleto. Las notificaciones de progreso mantienen su propia cadencia, mucho más fina, y no cuestan contexto al llamador — pero nótese que se emiten solo para una llamada bloqueante: la solicitud de un trabajo en segundo plano no lleva token de progreso, de modo que la única visibilidad de un trabajo es codex-status / codex-commentary.

Cuando commentaryEndOffset avanza, llama a codex-commentary con el último nextOffset. El comentario contiene solo mensajes de Codex marcados explícitamente con la fase commentary. El razonamiento oculto, las indicaciones, los borradores de respuesta final, las cadenas de comandos y su salida, los argumentos de herramientas, las rutas, las consultas de búsqueda y los elementos de respuesta en bruto quedan excluidos. Los controles de terminal inseguros se eliminan, pero el texto restante está redactado por el modelo y debe tratarse igualmente como no confiable. Los offsets cuentan puntos de código Unicode. Cada lectura devuelve como máximo 32 768 puntos de código; el puente conserva una cola UTF-8 de un MiB e informa límites de truncamiento absolutos cuando el comentario más antiguo ha quedado fuera del búfer.

Una vez que el estado es terminal, usa codex-result y continúa desde nextOffset hasta que done sea verdadero. Cada página devuelve su carga útil tanto como contenido de texto MCP ordinario como structuredContent.text para clientes que priorizan resultados estructurados. Las páginas de resultados también están limitadas a 32 768 puntos de código. Un marco de resultado nativo mayor que el límite de captura de 10 MiB del puente hace fallar el trabajo de forma atómica en lugar de filtrar su respuesta privada al transporte MCP.

Los trabajos son deliberadamente locales a la conexión: reiniciar o reconectar el servidor MCP los pierde. Como máximo ocho trabajos pueden estar activos y se conservan 32 registros; los registros terminales caducan después de una hora. La cancelación tiene la misma semántica de liquidación acotada que una llamada bloqueante, así que inspecciona el árbol de trabajo antes de reintentar un trabajo cancelado con capacidad de escritura. La API de trabajos es una opción de inclusión a nivel de llamada y no requiere soporte de tareas MCP por parte del cliente.

Estos avisos mantienen deliberadamente viva la ventana de inactividad de un cliente consciente del progreso, dejando la autoridad de actividad en los plazos de inactividad y duros del envoltorio. No refrescan --codex_idle_timeout, no extienden el plazo duro del envoltorio ni extienden un tiempo de espera de herramienta de reloj de pared duro separado del cliente. Un marco de progreso generado se inserta solo en un límite de nueva línea nativo; si Codex se detiene a mitad de un marco, el último aviso espera un límite seguro y el watchdog de inactividad real aún termina una detención permanente. Configura el tiempo de espera del cliente para que supere la ejecución de Codex más larga esperada más margen de respuesta; cuando caduque, el cliente cancela la llamada y la ruta de cancelación acotada de abajo toma el control.

Recuperación de resultado terminal. Codex anuncia el ID de hilo en un evento de sesión temprano correlacionado con la solicitud, de modo que el envoltorio lo conserva antes de que la compilación termine. Si Codex luego emite su evento de finalización terminal y el mensaje final del agente, pero su respuesta nativa tools/call no llega dentro del breve período de gracia de respuesta terminal, el envoltorio devuelve un resultado exitoso equivalente que contiene tanto content como structuredContent.threadId. Una respuesta nativa tardía coincidente se descarta, preservando la semántica de respuesta JSON-RPC de exactamente una vez. Esto cubre el modo de fallo en el que el trabajo aterrizó en el árbol pero el llamador no recibió ni el resultado ni el ID de hilo.

Cancelación y reconexión. La cancelación del cliente inicia un período de gracia corto y no reiniciable acotado por --codex_cancel_grace (la escalada a mitad de marco de abajo arma un segundo, de modo que esa ruta puede tardar aproximadamente el doble). Si Codex no se liquida dentro de él, el envoltorio liquida ese id de solicitud localmente, suprime la respuesta tardía de Codex y deja el puente y cada llamada hermana en ejecución — una única llamada bloqueada nunca debe derribar todo el puente. Dos excepciones acotadas: un flujo atascado a mitad de marco que además ignora la cancelación (sin un límite seguro en el que inyectar un error, el envoltorio reintenta una vez y luego escala a un desmontaje de todo el puente), y el límite agregado — una vez que las respuestas suprimidas alcanzan MAX_SUPPRESSED_CODEX_RESPONSES, el puente finaliza en lugar de rastrearlas indefinidamente. Después de cualquiera de los dos, el cliente se reconecta a un puente nuevo. Una respuesta nativa que llega dentro del período de gracia se descarta siempre que pueda ser interceptada sin corromper un marco parcialmente reenviado. La llamada cancelada, potencialmente con capacidad de escritura, nunca se reproduce automáticamente. La cancelación es de mejor esfuerzo y no demuestra que Codex se haya detenido — un turno no reconocido se registra como abandonado, no terminado, y puede seguir ejecutándose y escribiendo en el espacio de trabajo, así que inspecciona el árbol de trabajo antes de reintentarlo manualmente.

Este puente heredado deliberadamente no reengendra codex mcp-server dentro de la conexión stdio existente ni reproduce hilos de forma transparente. El estado de codex-reply pertenece al proceso Codex antiguo, de modo que un ID de hilo de un hijo derribado no puede reanudarse después de la reconexión. La recuperación duradera en la misma conexión requiere una migración separada del paso transparente heredado a un adaptador MCP sobre codex app-server (thread/start, turn/start, turn/interrupt y thread/resume).

Integración con Claude Code

Añade entradas al .mcp.json de tu proyecto usando un binario mcp-agents instalado globalmente:

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

npm (instalación global) vs npx — prefiere un binario instalado globalmente. La forma command: "mcp-agents" de arriba lanza un binario instalado localmente directamente; la alternativa npx de abajo ejecuta npx -y mcp-agents en cada inicio de proceso. Eso importa para la fiabilidad, no solo para la velocidad de arranque en frío: Claude Code relanza el servidor stdio cada vez que se (re)conecta — incluyendo después de una reconexión a mitad de sesión — y npx realiza una resolución del registro de paquetes en cada lanzamiento sin respaldo sin conexión. Si esa resolución es lenta (VPN, portal c cautivo, problema del registro), está en caché obsoleta a una versión que ya no existe (npm error code ETARGET), o falla de otro modo, el lanzamiento falla, el transporte se cierra y las herramientas desaparecen para la sesión. Un binario instalado globalmente (o una ruta absoluta a node server.js) elimina la dependencia de red y un nivel de proceso de la ruta de señal/desmontaje. Instala una vez con npm install -g mcp-agents (o npm link desde un checkout de la fuente), y luego apunta la configuración a él.

Para un checkout desde la fuente usado como tu puente Codex personal, una entrada a nivel de usuario en ~/.claude.json puede lanzar el árbol directamente y deshabilitar el límite de inactividad por solicitud (de modo que una revisión larga y legítimamente silenciosa esté acotada solo por el propio tiempo de espera de reloj de pared del cliente en lugar de abortarse antes de tiempo):

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

node desnudo se resuelve contra el PATH del cliente MCP; si node está gestionado por un gestor de versiones (nvm/fnm/asdf) que no está inicializado en ese entorno, usa una ruta absoluta de node en su lugar (which node, p. ej. /opt/homebrew/bin/node).

Anula los valores por defecto de codex al iniciar el servidor:

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

Cada llamada inicial a codex puede seleccionar gpt-5.6-sol o gpt-5.6-terra y medium, high, xhigh o max; los selectores omitidos usan los valores por defecto del servidor, y las respuestas heredan ambas elecciones. Otros modelos, config en bruto y argumentos de política de aprobación por llamada se rechazan antes de que Codex se ejecute. Añade "--goal", "<text>" a args para proporcionar un objetivo por defecto (consulta Inyección de objetivo arriba).

Claude interpreta el timeout por servidor en milisegundos como un límite duro de reloj de pared; el progreso no lo extiende. Mantenlo por encima del --timeout del envoltorio (7200 segundos por defecto), incluido el margen de respuesta. Una entrada de .mcp.json de proyecto puede anular una entrada MCP a nivel de usuario con el mismo nombre, así que pon el tiempo de espera en la entrada del proyecto en lugar de depender de la copia a nivel de usuario.

Excepto por el par explícito de modo rápido descrito arriba, el puente no hereda configuraciones de tu ~/.codex/config.toml normal. En particular, los servidores MCP heredados permanecen intencionalmente no disponibles dentro de las sesiones Codex con puente.

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

npx solo afecta al lanzamiento del proceso — una vez conectado, la latencia de las llamadas a herramientas es el mismo código de servidor de cualquier manera. Pero cada lanzamiento (incluida cada reconexión) resuelve el paquete contra el registro npm sin respaldo sin conexión, de modo que una resolución lenta, sin conexión o con caché obsoleta puede hacer fallar el lanzamiento y eliminar las herramientas a mitad de sesión (consulta npm vs npx arriba). Fijar mcp-agents@x.y.z evita que un @latest a mitad de sesión recoja una versión recién publicada, pero no elimina la dependencia de red por lanzamiento. Usa npx solo cuando la instalación cero importe más que la fiabilidad del lanzamiento.

Integración con OpenAI Codex

Añade dos entradas a ~/.codex/config.toml — una por cada proveedor que quieras disponible. El tiempo de espera de cliente de 960 segundos de Claude preserva la compatibilidad con la herramienta bloqueante claude_code de 900 segundos. Las revisiones en segundo plano no mantienen una solicitud MCP abierta: claude-start regresa inmediatamente y cada consulta de claude-status dura como máximo 60 segundos.

[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

En una sesión de Codex, pide una segunda opinión o revisión a Claude y usa claude-start → claude-status → claude-result. Mantén claude_code para indicaciones bloqueantes pequeñas; gemini sigue siendo una herramienta bloqueante.

Desarrollo

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

Después de npm link, cualquier edición en server.js surte efecto inmediatamente — no se necesita reinstalación.

Compara las rutas de arranque mediante archivos .mcp.json reales de proyectos en /tmp:

npm run bench:mcp-startup

Esto mide el lanzamiento de MCP desde initialize hasta tools/list; no llama al modelo/herramienta del proveedor.

Para una comprobación manual en segundo plano de Claude, llama a claude-start con una indicación de revisión corta y este repositorio como cwd, consulta claude-status con cada cursor devuelto y lee el veredicto con claude-result. Para la dirección inversa, haz que Claude Code llame a codex-start, consulta codex-status y lee codex-result. Estas comprobaciones rápidas usan llamadas a modelos reales y permanecen separadas de la puerta de la suite de pruebas determinista.

Cómo funciona

1. Un cliente MCP se conecta a través de stdio

2. El servidor lee --provider <name> de su argv (por defecto codex)

3. Gemini registra una herramienta CLI bloqueante; Claude registra su herramienta bloqueante heredada más las herramientas de trabajos de revisión de una sola vez; Codex reenvía sus herramientas nativas y añade sus herramientas de trabajos en segundo plano

4. El cliente llama a tools/call con el nombre de la herramienta y un prompt

5. El servidor ejecuta la CLI como un proceso hijo separado; los trabajos de revisión de Claude analizan stream-json en estado seguro y páginas de resultados retenidas, mientras que las herramientas bloqueantes devuelven la salida normalizada del proveedor

El servidor mantiene un pequeño temporizador de keepalive para que Node.js no salga prematuramente cuando stdin alcanza EOF antes de que un subproceso asíncrono registre un handle activo. Para el modo de proveedor de Claude y Gemini, ese keepalive se limpia durante el apagado. Cuando la conexión MCP stdio se cierra, los trabajos activos de Claude reciben una interrupción y un respaldo acotado de TERM/KILL; cualquier grupo de procesos de proveedor separados y rastreados restante se recolecta antes de que el servidor salga.

Licencia

MIT