Skip to main content
Glama
deenesjakoruzh
benzkittisak

codex-async-mcp

by benzkittisak
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

codex-async-mcp

Servidor MCP local que envuelve la CLI de codex de forma asíncrona: devuelve un job_id inmediatamente en lugar de bloquear, para que Claude nunca alcance el tiempo de espera del protocolo MCP (-32001).

Requisitos

  • Python 3.11+

  • CLI de codex instalada y en el $PATH (v0.125.0+)

  • CLI de Claude Code

Instalación

cd ~/payroll-mcp   # or wherever this repo lives
pip install -e ".[dev]"

Verificar:

python -c "from codex_async_mcp.server import mcp; print(mcp.name)"
# → codex-async-mcp

Registrar en Claude

Global (todos los proyectos)

claude mcp add codex-async -s user -- python -m codex_async_mcp.server

Solo para el proyecto

cd ~/payrollservice-thailand   # or any project
claude mcp add codex-async -- python -m codex_async_mcp.server

Verificar

claude mcp list
# codex-async: python -m codex_async_mcp.server - ✓ Connected

Añadir permisos de herramientas (settings.local.json)

{
  "permissions": {
    "allow": [
      "mcp__codex-async__codex_start",
      "mcp__codex-async__codex_poll",
      "mcp__codex-async__codex_list",
      "mcp__codex-async__codex_cancel"
    ]
  }
}

Herramientas

Herramienta

Descripción

codex_start(prompt, cwd, approval_policy?)

Inicia codex en segundo plano → devuelve job_id al instante

codex_poll(job_id, tail_lines?)

Comprueba el estado + final de la salida

codex_list(limit?)

Lista los trabajos recientes (los más nuevos primero)

codex_cancel(job_id)

Mata un trabajo en ejecución

Valores de approval_policy

Valor

Flag de Codex

Comportamiento

suggest

-s read-only

Sandbox de solo lectura, sin escrituras

auto-edit

--full-auto

Aplica ediciones automáticamente

full-auto

--dangerously-bypass-approvals-and-sandbox

Sin avisos, sin sandbox

Para la automatización de Claude, utiliza siempre full-auto — el modo suggest espera una entrada interactiva que nunca llegará dentro de un subproceso.

Ejemplo de uso

codex_start(
  prompt="In app/services/prorate_calculation_service.rb line 96, change format(...) to number_to_currency(...)",
  cwd="/Users/bbgummybear/payrollservice-thailand",
  approval_policy="full-auto"
)
# → { job_id: "f3a9b2", status: "running", pid: 12345 }

codex_poll(job_id="f3a9b2")
# → { status: "running", output: "Reading file..." }

codex_poll(job_id="f3a9b2")
# → { status: "done", exit_code: 0, output: "Applied changes to prorate_calculation_service.rb" }

Estado del trabajo

Los trabajos se almacenan en ~/.codex-async/jobs/{job_id}/:

~/.codex-async/jobs/f3a9b2/
  meta.json     ← status, pid, timestamps, exit_code
  output.txt    ← stdout + stderr from codex

Estructura de meta.json:

{
  "job_id": "f3a9b2",
  "status": "running | done | error | cancelled",
  "prompt": "...",
  "cwd": "/path/to/repo",
  "approval_policy": "full-auto",
  "pid": 12345,
  "started_at": "2026-04-29T10:00:00+00:00",
  "finished_at": null,
  "exit_code": null
}

Solución de problemas

codex-async: ... - ✗ Failed en claude mcp list

No se puede encontrar Python o el paquete no está instalado en el entorno correcto.

# Check which python Claude is using
which python

# If using conda, register with the full path
claude mcp add codex-async -s user -- /Users/bbgummybear/miniconda3/bin/python -m codex_async_mcp.server

# Verify the package is installed in that environment
/Users/bbgummybear/miniconda3/bin/python -c "import codex_async_mcp; print('ok')"

status: "error" inmediatamente después de codex_start

Codex no pudo iniciarse. Comprueba la salida sin procesar:

cat ~/.codex-async/jobs/<job_id>/output.txt

Causas comunes:

Mensaje de salida

Solución

command not found: codex

codex no está en el PATH — añádelo al perfil de shell o configura CODEX_BIN en config.py

unknown flag: --dangerously-bypass-approvals-and-sandbox

Versión de Codex < 0.125.0 — ejecuta npm install -g @openai/codex para actualizar

permission denied

cwd no existe o Claude no tiene acceso

status: "running" para siempre, nunca termina

El subproceso está bloqueado (esperando entrada o atrapado en un bucle).

# Check if the process is still alive
ps aux | grep codex

# Check live output
tail -f ~/.codex-async/jobs/<job_id>/output.txt

# Cancel the job
codex_cancel(job_id="<job_id>")

Causa más común: usar approval_policy="suggest" que se pausa para la aprobación interactiva. Usa "full-auto" en su lugar.

El trabajo muestra status: "running" después de reiniciar el servidor

El servidor MCP perdió el registro Popen en memoria al reiniciar. La siguiente llamada a codex_poll detectará que el PID está muerto y actualizará el estado automáticamente.

codex_poll(job_id="<job_id>")
# → { status: "done", ... }   ← auto-resolved on first poll

Los trabajos antiguos llenan el disco

# View all jobs sorted by date
ls -lt ~/.codex-async/jobs/

# Delete jobs older than 7 days
find ~/.codex-async/jobs -maxdepth 1 -type d -mtime +7 -exec rm -rf {} +

Estructura del proyecto

codex-async-mcp/
├── README.md
├── pyproject.toml
├── src/
│   └── codex_async_mcp/
│       ├── __init__.py
│       ├── server.py        # MCP entry point, tool definitions
│       ├── job_manager.py   # spawn / poll / cancel / list
│       └── config.py        # JOBS_DIR, CODEX_BIN, defaults
└── tests/
    └── test_job_manager.py

Ejecutar pruebas

pytest tests/ -v
Install Server
F
license - not found
A
quality
C
maintenance

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/benzkittisak/claude-codex-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server