codex-async-mcp

codex CLI를 비동기적으로 래핑하는 로컬 MCP 서버입니다. 차단하는 대신 job_id를 즉시 반환하여 Claude가 MCP 프로토콜 타임아웃(-32001)에 걸리지 않도록 합니다.

요구 사항

Python 3.11+
codex CLI가 설치되어 있고 $PATH에 있어야 함 (v0.125.0+)
Claude Code CLI

설치

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

확인:

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

Claude에 등록

전역 (모든 프로젝트)

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

프로젝트 전용

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

확인

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

도구 권한 추가 (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"
    ]
  }
}

도구

도구	설명
`codex_start(prompt, cwd, approval_policy?)`	백그라운드에서 codex 시작 → `job_id` 즉시 반환
`codex_poll(job_id, tail_lines?)`	상태 확인 + 출력 끝부분 확인
`codex_list(limit?)`	최근 작업 나열 (최신순)
`codex_cancel(job_id)`	실행 중인 작업 종료

approval_policy 값

값	Codex 플래그	동작
`suggest`	`-s read-only`	읽기 전용 샌드박스, 쓰기 불가
`auto-edit`	`--full-auto`	편집 자동 적용
`full-auto`	`--dangerously-bypass-approvals-and-sandbox`	프롬프트 없음, 샌드박스 없음

Claude 자동화의 경우 항상 full-auto를 사용하세요. — suggest 모드는 서브프로세스 내부에서 절대 도착하지 않을 대화형 입력을 기다립니다.

사용 예시

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

작업 상태

작업은 ~/.codex-async/jobs/{job_id}/에 저장됩니다:

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

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
}

문제 해결

`claude mcp list`에서 `codex-async: ... - ✗ Failed` 발생

Python을 찾을 수 없거나 패키지가 올바른 환경에 설치되지 않았습니다.

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

`codex_start` 직후 `status: "error"` 발생

Codex 시작에 실패했습니다. 원시 출력을 확인하세요:

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

일반적인 원인:

출력 메시지	해결 방법
`command not found: codex`	`codex`가 PATH에 없음 — 셸 프로필에 추가하거나 `config.py`에서 `CODEX_BIN` 설정
`unknown flag: --dangerously-bypass-approvals-and-sandbox`	Codex 버전 < 0.125.0 — `npm install -g @openai/codex`를 실행하여 업그레이드
`permission denied`	`cwd`가 존재하지 않거나 Claude에 접근 권한이 없음

`status: "running"` 상태에서 멈추고 완료되지 않음

서브프로세스가 중단되었습니다(입력을 기다리거나 루프에 빠짐).

# 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>")

가장 흔한 원인: 대화형 승인을 기다리는 approval_policy="suggest"를 사용 중인 경우입니다. 대신 "full-auto"를 사용하세요.

서버 재시작 후 작업이 `status: "running"`으로 표시됨

MCP 서버가 재시작 시 메모리 내 Popen 레지스트리를 잃어버렸습니다. 다음 codex_poll 호출 시 PID가 죽은 것을 감지하고 상태를 자동으로 업데이트합니다.

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

오래된 작업이 디스크를 채움

# 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 {} +

프로젝트 구조

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

테스트 실행

pytest tests/ -v

codex-async-mcp

codex-async-mcp

요구 사항

설치

Claude에 등록

전역 (모든 프로젝트)

프로젝트 전용

확인

도구 권한 추가 (settings.local.json)

도구

approval_policy 값

사용 예시

작업 상태

문제 해결

`claude mcp list`에서 `codex-async: ... - ✗ Failed` 발생

`codex_start` 직후 `status: "error"` 발생

`status: "running"` 상태에서 멈추고 완료되지 않음

서버 재시작 후 작업이 `status: "running"`으로 표시됨

오래된 작업이 디스크를 채움

프로젝트 구조

테스트 실행

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API

codex-async-mcp

요구 사항

설치

Claude에 등록

전역 (모든 프로젝트)

프로젝트 전용

확인

도구 권한 추가 (settings.local.json)

도구

approval_policy 값

사용 예시

작업 상태

문제 해결

claude mcp list에서 codex-async: ... - ✗ Failed 발생

codex_start 직후 status: "error" 발생

status: "running" 상태에서 멈추고 완료되지 않음

서버 재시작 후 작업이 status: "running"으로 표시됨

오래된 작업이 디스크를 채움

프로젝트 구조

테스트 실행

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API

`claude mcp list`에서 `codex-async: ... - ✗ Failed` 발생

`codex_start` 직후 `status: "error"` 발생

`status: "running"` 상태에서 멈추고 완료되지 않음

서버 재시작 후 작업이 `status: "running"`으로 표시됨