Codex Supervisor MCP

A local Model Context Protocol (MCP) bridge that lets a compatible host start, monitor, steer, interrupt, resume, and approve Codex app-server work.

It wraps codex app-server; it does not automate a terminal UI or scrape an IDE.

기능

The server exposes these MCP tools:

Related MCP server: Codex Bridge MCP

요구 사항

• Node.js 22 이상.

• codex로 사용 가능한 최신 Codex CLI.

• Codex CLI 인증이 이미 구성되어 있어야 합니다.

• 명시적인 로컬 저장소 루트가 하나 이상 있어야 합니다.

이 프로젝트에는 npm 런타임 종속성이 없습니다.

패키지 검증

npm test

테스트 스위트는 프로토콜 호환 목 앱 서버를 사용합니다. 모델 요청을 하지 않으며 Codex 인증이 필요하지 않습니다.

Codex CLI로 설치

MCP 서버 이름 codex-supervisor를 사용하세요. 이름은 CODEX_SUPERVISOR_MCP_NAME과 일치해야 합니다. 브리지는 이 이름을 사용하여 자식 앱 서버가 이 동일한 MCP 서버를 재귀적으로 로드하지 못하게 합니다.

macOS 또는 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"

루트 사이에 플랫폼 경로 목록 구분 기호를 사용하세요. macOS 및 Linux에서는 콜론(:)입니다.

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"

Windows에서 경로 목록 구분 기호는 세미콜론(;)입니다.

등록을 확인하세요:

codex mcp list

Codex에서 /mcp를 입력하여 연결된 서버를 검사하세요.

config.toml로 설치

examples/config.toml을 복사하여 수정한 후 그 내용을 ~/.codex/config.toml 또는 신뢰할 수 있는 프로젝트의 .codex/config.toml에 넣으세요.

절대 경로를 사용하세요. 서버 ID와 CODEX_SUPERVISOR_MCP_NAME을 동일하게 유지하세요.

ChatGPT 데스크톱 또는 Codex IDE 확장 프로그램

1. 설정 → MCP 서버 → 서버 추가를 엽니다.

2. 이름을 codex-supervisor로 설정합니다.

3. STDIO를 선택합니다.

4. 명령을 node로 설정합니다.

5. 유일한 인수로 src/index.mjs의 절대 경로를 추가합니다.

6. CODEX_ALLOWED_ROOTS와 CODEX_SUPERVISOR_MCP_NAME=codex-supervisor를 추가합니다.

7. 저장하고 호스트를 다시 시작합니다.

8. 도구를 확인하려면 /mcp를 입력합니다.

로컬 STDIO MCP 서버는 일반 ChatGPT 웹 채팅에서 로드되지 않습니다. 웹에서 이 브리지를 사용하려면 별도로 배포된 인증된 원격 MCP 서비스 또는 호스팅 플러그인이 필요합니다.

일반적인 워크플로우

MCP 호스트에게 요청하세요:

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.

호스트는 다음 순서를 따라야 합니다:

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

모든 start/send/steer/interrupt 호출은 eventCursor를 반환합니다. 이를 afterSequence로 codex_wait 또는 codex_status에 전달하여 이전 이벤트가 재생되지 않도록 하세요.

approvalPolicy는 현재 앱 서버 와이어 값 on-request(기본값)와 untrusted를 수락합니다. 레거시 값 onRequest와 unlessTrusted는 브리지에서 수락되어 앱 서버 요청 전에 정규화됩니다.

공개 승인 API는 Codex 앱 서버 릴리스가 요청에 대해 cancel만 광고하는 경우에도 decline을 수락합니다. 이 경우 브리지는 안전한 앱 서버 취소 응답을 사용하고 요청된 결정과 실제 결정을 모두 보고합니다.

구성

기본 앱 서버 인수는 다음과 동일합니다:

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

CODEX_APP_SERVER_ARGS를 재정의하면 해당 재귀 보호 장치가 제거됩니다. 직접 동등한 비활성화 재정의를 포함하세요.

보안 모델

• CODEX_ALLOWED_ROOTS는 필수입니다.

• 경로는 realpath로 정규화됩니다. 심볼릭 링크 탈출은 거부됩니다.

• Codex는 선택한 저장소 및 플랫폼 기본값에 대한 제한된 읽기 액세스 권한을 받습니다.

• workspaceWrite는 쓰기 가능한 루트를 선택한 저장소로 제한합니다.

• dangerFullAccess는 노출되지 않습니다.

• 네트워크 액세스는 작업에 CODEX_ALLOW_NETWORK=1과 networkAccess: true가 모두 필요합니다.

• 브리지에는 일반적이고 샌드박스가 없는 셸 도구가 없습니다.

• 명령 및 파일 변경 승인은 명시적으로 해결되어야 합니다.

• 허용된 루트 밖의 스레드는 거부되거나 필터링됩니다.

• 이벤트 페이로드는 저장 전에 크기가 제한됩니다.

• 저장된 스레드 경로는 사용 시 재정규화됩니다. 삭제되거나 교체된 저장소 경로는 기본적으로 거부됩니다.

• 동일 스레드 변경, 승인 응답 및 재시도된 원격 호출은 두 번 실행되지 않고 직렬화되거나 중복 제거됩니다.

• 전송 오류는 STDIO 또는 HTTP 경계를 넘기 전에 재귀적으로 편집되고 크기가 제한됩니다.

• 릴레이 및 원격 서버 자격 증명(BIOTELE_* 및 CODEX_REMOTE_*)은 자식 Codex 환경에서 제거됩니다.

• 원격 결과 제출은 HMAC 인증을 거치고 base64url로 인코딩되며 크기가 제한된 청크로 분할되고 사용 전에 길이와 SHA-256으로 검증됩니다. 인코딩은 전송을 콘텐츠 필터로부터 보호합니다. 암호화는 아닙니다.

자식 앱 서버는 여전히 비 릴레이 프로세스 설정과 더 넓은 Codex 구성을 상속받습니다. 신뢰할 수 없는 코드와 함께 사용하기 전에 다른 환경 비밀값, 앱, 스킬, 훅 및 구성된 MCP 서버를 감사하세요. 환경 제거는 운영 체제 보안 경계가 아닙니다. 동일한 Windows 사용자로 실행되는 자식 프로세스는 의도적으로 사용자 범위 설정을 조회할 수 있습니다. 해당 위협이 범위 내에 있다면 전용 Windows 계정을 사용하세요.

지원되는 승인 요청

이 릴리스는 다음을 해결합니다:

• item/commandExecution/requestApproval

• item/fileChange/requestApproval

다른 앱 서버 요청은 codex_status와 codex_list_approvals를 통해 계속 볼 수 있지만 브리지는 응답을 거부합니다. 이는 일반 응답 엔드포인트가 조용히 권한을 부여하거나 민감한 사용자 입력을 제공하는 것을 방지합니다.

영속성 및 모니터링

Codex는 영구 저장된 스레드 기록을 소유합니다. 브리지는 스트리밍된 이벤트 버퍼, 최신 델타 및 대기 중인 요청 상태를 메모리에 유지합니다. MCP 서버를 다시 시작하면 해당 일시적 상태가 지워지지만 codex_list_threads와 codex_read_thread는 승인된 영구 저장 스레드를 복구할 수 있습니다.

개발

npm test
node --check src/index.mjs

프로젝트 구조:

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

라이선스

MIT

Codex App Server 호환성

버전 1.0.3은 turn/start에서 더 이상 사용되지 않는 readOnly.access 및 workspaceWrite.readOnlyAccess 필드를 제거합니다. 현재 Codex App Server 릴리스는 클라이언트가 사용자 지정 제한 읽기 범위를 필요로 할 때 권한 프로필을 사용합니다. 슈퍼바이저는 쓰기 가능한 루트를 선택한 저장소로 계속 제한하고 모든 작업 디렉터리를 CODEX_ALLOWED_ROOTS에 대해 검증합니다.

Hostinger 원격 릴레이

버전 1.2.5는 ChatGPT 원격 MCP 액세스를 위한 Hostinger 호환 릴레이를 제공합니다:

ChatGPT -> OAuth bearer JWT -> Hostinger /mcp -> namespace-routed queue
  codex_*  -> outbound Windows local-agent -> Codex app-server
  reeves_* -> outbound Reeves Android agent -> accessibility service

공개 /mcp 엔드포인트는 외부 ID 제공자의 RS256 OAuth 액세스 토큰을 검증합니다. Windows 및 Reeves 에이전트는 아웃바운드 폴링, 상태, 임대 획득 및 결과 제출에만 독립적인 HMAC 자격 증명을 사용합니다. Hostinger 릴레이는 Codex를 시작하지 않으며 로컬 저장소를 읽지 않습니다.

호스팅 릴레이는 기존의 모든 codex_* 도구를 유지하고 추가로 reeves_status, reeves_tap, reeves_swipe, reeves_type, reeves_back, reeves_home, reeves_recents, reeves_sequence, reeves_screenshot을 노출합니다. 로컬 STDIO Codex 레지스트리는 Codex 전용으로 유지됩니다. 에이전트 클레임은 인증된 키 ID로 필터링됩니다. 클라이언트가 제공한 라우팅 필드는 무시됩니다.

reeves_screenshot은 표준 MCP image 콘텐츠 블록(image/png + base64 데이터)으로 Android 픽셀을 너비, 높이, 캡처 타임스탬프, 에이전트 ID 및 바이트 길이 메타데이터와 함께 반환합니다. Android 에이전트는 릴레이가 광고하는 청크 결과 프로토콜을 사용하므로 사용할 수 없는 Android 로컬 경로가 노출되지 않으며 각 서명된 HTTP 요청은 릴레이 본문 한도 내에 유지됩니다.

reeves_sequence는 하나의 라우팅된 작업에서 1~50개의 정렬된 장치 동작을 보냅니다. Android는 탭, 스와이프, 입력, 뒤로, 홈, 최근 앱, 대기 및 스크린샷 동작을 로컬에서 실행하고 기본적으로 첫 번째 오류에서 중지하며 기본적으로 최종 MCP 이미지 하나를 반환합니다. 결과에는 인덱스된 동작 결과와 추가적인 비밀 없는 릴레이/Android 단계 타이밍이 포함됩니다. 기존 25초 에이전트 요청은 큐에 넣을 때 깨우는 롱폴링이지 픽업 지연이 아닙니다. Android는 각 성공적인 결과 제출 후 즉시 다른 클레임을 시작하고 하나의 OkHttp 연결 풀을 재사용합니다.

이 릴리스는 또한 지원되는 MCP 프로토콜 버전을 협상하고 제한된 OAuth 주체 바인딩 세션을 발급하며 후속 요청에서 해당 세션을 요구합니다. 재시도된 도구 호출은 OAuth 주체, MCP 세션, 타입이 지정된 JSON-RPC ID 및 요청 해시에 바인딩됩니다. 세션을 종료하면 캐시되거나 대기 중인 작업이 무효화됩니다. 이 릴리스는 또한 취소된 릴레이 작업과 충돌한 앱 서버 상태를 정리하고 승인된 경로를 다시 검증하며 스레드별 이벤트를 격리하고 모든 공개 전송에서 크기가 제한된 중첩 오류 데이터를 편집합니다.

버전 1.2.5는 또한 codex_status.latestAgentMessage를 승인된 영구 저장 대화 기록과 조정합니다. 합성된 rollout-* 턴을 포함하여 완전히 영구 저장된 외부 Codex 완료 응답은 이제 오래된 브리지 관찰 메시지를 대체하며 불완전하거나 중단된 대화 기록의 꼬리는 계속 제외됩니다.

Windows 에이전트를 업데이트하기 전에 업데이트된 릴레이를 배포하세요. 새 릴레이는 여전히 레거시 원샷 결과를 수용하고 새 에이전트는 릴레이가 지원을 광고한 후에만 청크 형식을 사용합니다.

Hostinger hPanel 단계, mcp.biotele.mx용 DNS, Auth0 설정, Microsoft Entra ID 설정, ChatGPT 웹 커넥터 설정 및 복구, 환경 변수, 로컬 에이전트 설치 및 위협 모델에 대해서는 docs/REMOTE_DEPLOYMENT.md를 참조하세요.