codex-mcp-bridge

영어 버전

Claude Desktop용 MCP 서버로, 공유 Codex 앱 서버를 통해 기존 Codex 스레드에 프롬프트를 직접 전송합니다. macOS, Windows, Linux에서 실행됩니다.

codex exec가 아닙니다(매번 새 세션을 만듭니다). Bridge는 실제 Codex 앱 서버와 JSON-RPC로 통신하므로 스레드는 기록, cwd, 모델 및 롤아웃 파일을 유지합니다.

아키텍처

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)

• 앱 서버는 포트별 싱글턴입니다. Bridge는 http://127.0.0.1:8791/readyz를 프로브하고, 아직 살아있지 않으면 분리된 프로세스로 자동 생성합니다(codex app-server --listen ws://127.0.0.1:8791). 이 앱 서버는 bridge가 종료된 후에도 독립적으로 계속 실행됩니다.

• 동일한 URL을 가리키는 모든 클라이언트는 하나의 앱 서버를 사용합니다. 따라서 threadId로 thread/resume을 호출하면 새 세션을 여는 대신 실행 중인 스레드에 다시 연결됩니다.

• Bridge는 정확히 하나의 WebSocket을 유지하고, initialize를 한 번 수행하며, threadId별로 알림을 라우팅하므로 여러 스레드가 병렬로 실행되어도 서로 섞이지 않습니다.

Related MCP server: webgpt MCP

도구

send_to_codex_thread는 timeoutSec(기본 240), cwd, model, effort, openInApp(macOS — 전송 전에 앱에서 스레드를 열어 라이브로 보기)를 추가로 받습니다. 시간 초과는 턴을 취소하지 않습니다 — bridge는 turnId와 함께 지금까지 수집된 내용을 반환하며, read_codex_thread로 계속 읽거나 interrupt_codex_turn으로 중지할 수 있습니다.

Claude Desktop에 설치

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

스크립트는 플랫폼을 자동으로 감지하고, config 파일이 없으면 생성하며, 이전 버전을 백업하고(*.bak-<날짜>-codexbridge), 기존 키는 모두 그대로 유지합니다.

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

설치한 후 Claude Desktop을 다시 시작하세요.

codex 바이너리 확인: Claude Desktop(및 launchd)은 PATH가 축소된 상태로 MCP 서버를 실행하므로 codex가 PATH에 없는 경우가 많습니다. Bridge는 다음 순서대로 탐색합니다 — CODEX_BIN → 플랫폼의 일반적인 설치 위치 → PATH:

macOS/Linux에서 codex는 shebang #!/usr/bin/env node가 있는 Node 스크립트이므로, bridge는 하위 프로세스에 PATH(현재 node 디렉터리 + /opt/homebrew/bin + /usr/local/bin + 시스템 디렉터리)를 다시 주입합니다. 이 단계가 없으면 app-server가 shebang에서 바로 죽습니다.

macOS

launchd로 앱 서버를 백그라운드로 실행

node scripts/install-launch-agent.mjs

~/Library/LaunchAgents/com.codex-mcp-bridge.app-server.plist를 생성하고(RunAtLoad + 충돌 시 KeepAlive, ThrottleInterval 10초), launchctl bootstrap gui/$UID를 실행합니다. 앱 서버는 로그인 시점부터 이미 실행 중이므로 bridge가 직접 생성할 필요가 없고, 스레드는 항상 live 상태입니다.

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

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

Codex 데스크톱 앱에서 스레드를 직접 보기

macOS에서 Codex 데스크톱 앱은 /Applications/ChatGPT.app이며 codex:// 스킴을 등록합니다. Bridge는 codex://threads/<threadId>를 사용하여 정확한 스레드를 엽니다:

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

이렇게 하면 작업을 지시한 사람이 작업이 끝난 후 ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl 롤아웃을 다시 읽는 대신 Codex가 작업하는 모습을 직접 볼 수 있습니다.

macOS 제한 사항

• Codex 데스크톱 앱은 stdio(ChatGPT.app/Contents/Resources/codex … app-server)를 통해 자체 앱 서버를 실행하며 외부 엔드포인트를 받지 않습니다. 앱에서 연 스레드는 여전히 bridge를 통해 보낼 수 있지만, 라이브 연결이 아니라 .jsonl 롤아웃에서 resume하는 방식입니다. 데스크톱 앱에서 턴이 실행 중인 스레드에는 보내지 마십시오 — 두 앱 서버가 동일한 롤아웃에 동시에 쓰면 기록이 손상될 수 있습니다. 먼저 list_codex_threads로 status를 확인하고 idle/notLoaded일 때만 보내십시오.

• 이중 부팅 머신의 NTFS 파티션(/Volumes/...)에 있는 리포지토리는 macOS에서 읽기 전용입니다 — macOS는 NTFS를 읽기 전용으로 마운트합니다. 실행 및 수정을 위해 APFS 볼륨(예: ~/code/codex-mcp-bridge)에 별도 체크아웃을 유지하세요.

• codex app-server daemon start는 컨트롤 소켓 ~/.codex/app-server-control/app-server-control.sock과 함께 unix:// 전송을 사용합니다. Bridge는 이 경로를 사용하지 않습니다(프레임 프로토콜이 WebSocket과 다르고 공개 API가 아직 없음) — 항상 ws://로 통신합니다.

환경 변수

승인에 관하여: approval_policy가 never가 아니면 Codex는 명령/패치 승인을 요청합니다. Claude Desktop 앞에서 아무도 클릭하지 않으므로 bridge가 CODEX_BRIDGE_APPROVAL에 따라 자동으로 응답하고 stderr에 로그를 남깁니다. 기본 approve는 ~/.codex/config.toml의 approval_policy = "never" + sandbox_mode = "danger-full-access" 설정과 일치합니다. 샌드박스를 강화했다면 deny로 변경하는 것을 고려하세요.

대화형 Codex 세션과 앱 서버 공유

TUI에서 동일한 엔드포인트를 가리켜 TUI의 스레드와 bridge의 스레드가 하나로 보이게 하세요:

codex --remote ws://127.0.0.1:8791

앱 서버를 수동으로 실행합니다(bridge 자동 시작에 의존하지 않음):

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

테스트

npm run check

빠른 확인: bridge 시작, 필요한 경우 앱 서버 자동 시작, 스레드 나열.

npm run smoke

새 스레드를 만들고 연속으로 2턴을 보낸 다음 Codex가 이전 턴의 코드워드를 기억하는지 확인하는 스모크 테스트 — 즉 스레드가 실제로 연속적이며 매번 새 세션이 아니라는 뜻입니다.

Claude 내에서 환경 확인: codex_bridge_status 도구를 호출하세요.