mcp-agents

AI CLI 도구 — Claude Code, Antigravity CLI(agy), Codex CLI — 를 래핑하고, 원격으로 임대된 브라우저에 Chrome DevTools MCP를 프록시할 수 있는 MCP 서버입니다.

전제 조건

• Node.js >= 26

• 다음 CLI 중 최소 하나가 설치되어 있고 $PATH에 있어야 합니다.

--provider로 선택한 CLI만 있으면 됩니다.

Related MCP server: claudecode-mcp

설치

npm install -g mcp-agents

전역 설치가 가장 빠르고 확실한 시작 방법입니다. MCP 서버가 실행된 후에는 npx -y mcp-agents도 기능적으로 동일하지만, 시작 시 MCP 클라이언트가 연결되기 전에 npm 패키지 해석/캐시 상태에 따라 시간이 걸릴 수 있습니다.

팁: 프로젝트의 .mcp.json이 mcp-agents를 참조하는 경우, 새 개발자가 자동으로 설치할 수 있도록 설정 스크립트(예: bin/setup)에 npm install -g mcp-agents를 추가하세요.

빠른 테스트

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

서버는 stdio를 통한 JSON-RPC로 통신합니다. 대기 중일 때 stderr에 [mcp-agents] ready (provider: <name>)를 출력합니다.

프로바이더 및 도구

각 --provider 플래그는 하나의 CLI 백엔드를 선택합니다.

Claude 리뷰

폭넓은 조언과 코드 리뷰가 필요하면 백그라운드에서 진행되는 다음 도구를 사용하세요.

1. 전체 리뷰 프롬프트와 절대 경로 cwd를 사용해 claude-start를 호출합니다.

2. 반환된 jobId와 cursor로 claude-status를 호출합니다. 종료 상태가 될 때까지 각각의 새 cursor로 반복합니다.

3. 상태가 completed가 되면 claude-result를 호출합니다. done 이 true가 될 때까지 nextOffset으로 계속 진행합니다.

4. 더 이상 검토 결과가 필요 없으면 claude-cancel을 호출합니다.

claude-status는 기본적으로 10초 동안 롱 폴링하며, wait_ms로 최대 60초까지 허용합니다. 상태 폴링을 취소해도 해당 작업까지 취소되지는 않습니다. 작업은 일회용이며 현재 MCP 연결에만 존재합니다. reply 세션은 없고, 연결이 끊기면 실행 중인 작업도 취소됩니다. 서버는 활성 작업 8개와 유지 작업 32개를 허용하며, 종료된 작업은 1시간 동안 보관하고, 결과는 32,768개의 유니코드 코드 포인트 단위로 페이지네이션하며, 10MiB를 초과하는 최종 결과는 거부합니다.

백그라운드 리뷰에는 브리지가 보유한 2시간의 제한 시간이 적용됩니다. 운영자는 서버 시작 시 --timeout <seconds>로 이 값을 대체할 수 있습니다. 호출자가 timeout_ms를 사용해 작업 시간을 줄일 수는 없습니다. Claude는 effort xhigh에서 claude-opus-4-8로 고정되며 말단(leaf) 리뷰어로 실행됩니다. 즉, 프로젝트 지시와 저장소 컨텍스트는 유지하되 훅, 서브에이전트, 스킬, 슬래시 명령, 외부 MCP 서버, 그리고 상태 변경 도구는 비활성화합니다. Read, Glob, Grep 및 plan 모드의 읽기 전용 Bash 검사만 사용할 수 있습니다. 또한 leaf 지시는 테스트 실행, 설치, 위임, 외부 부작용을 금지합니다. 중간 모델 출력, 도구 입력/결과, 경로, 추론은 MCP를 통해 노출되지 않으며, 정제된 단계 상태와 최종 판정만 공개됩니다.

큰 결과가 클라이언트 타임아웃 안에 완료될 수 있는 작은 프롬프트에만 claude_code 차단 도구를 사용하세요.

claude_code 매개변수

추가적인 tools/call 인자는 무시됩니다(예: model, effort 또는 config).

Claude는 effort xhigh에서 claude-opus-4-8로 고정됩니다. 호출자가 모델이나 effort를 변경할 수 없습니다. --output-format json로 실행되며, 서버가 JSON 페이로드를 파싱하고 어시스턴트의 result 텍스트를 반환합니다 (is_error=true인 경우 MCP 오류). 긴 기본 시간은 심층 Opus 리뷰를 위해 마련된 것이며, 이 기본값은 호출자가 timeout_ms로 줄이거나, 서버 운영자가 --timeout <seconds>로 바꿀 수 있습니다.

gemini 매개변수

추가적인 tools/call 인자는 무시됩니다(예: model 또는 model_reasoning_effort).

agy는 항상 --sandbox(터미널 제한 활성화)로 실행됩니다. 호출별 샌드박스 토글은 없습니다.

browser(원격 Chrome 패스스루)

browser 프로바이더는 시작할 때 로컬 chrome-devtools-mcp 서버를 즉시 띄우고, 첫 번째 광고된 브라우저 도구 호출이 발생할 때만 원격 Chrome 임대를 지연(lazily) 획득합니다. MCP 서버와 서버가 쓰는 모든 파일은 로컬에 남으며, 운영자가 제공한 루프백 터널을 통해 CDP만 전달됩니다. 획득 중에 도착한 호출은 하나의 프로비저닝 시도로 공유하고 FIFO 순서로 남습니다. 래퍼가 소유한 acquire·status·release·job·cancel 도구는 없습니다.

crabbox와 함께하는 빠른 설정

crabbox와 가장 잘 어울립니다: 임시적이고 단일 테넌트인 박스로, 직접 올바르게 정리할 필요 없이 브라우저 lease가 원하는 생명주기대로 자체 한도에서 소멸합니다.

acquire 헬퍼는 네 가지 작업을 합니다. 박스를 임대하고, --remote-debugging-port=<remote>로 크로미움을 시작하며, ssh -L 127.0.0.1:<local-cdp-port>:127.0.0.1:<remote>를 엽니다(테스트 중인 페이지가 내 머신에서 서빙될 때는 --app-port에 해당하는 -R도 추가). 그런 다음 로컬 포트에서 /json/version이 응답하면 다음 형식을 인쇄합니다.

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는 해당 임대를 다시 확인하고, release는 정리하며, exit 69가 되면 lane은 fail-closed를 유지합니다.

프로바이더는 클라우드나 SSH 지식이 없습니다. 주입된 명령이 임대를 소유하며, 다음 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

성공적인 acquire 출력은 쓸모없는 UTF-8 key=value 데이터로, 버전 1 레디 레코드, 세대, 선택된 로컬 CDP 포트, 그리고 일치하는 브라우저 URL을 포함합니다. 종료 69는 fail-closed입니다: 호출은 “GUI not verified — no browser box available”를 반환하며 로컬 브라우저를 자체 실행하지 않습니다. 헬퍼가 보고한 로컬 dev-server 사전 점검 오류는 그대로(verbatim) 보존됩니다. 종료 75는 루프백 바인딩 경합을 보고합니다. mcp-agents는 새 포트를 선택하고, 다운스트림 서버를 재시작하며, 원래 MCP initialize 기능(roots 포함)과 initialized 알림을 재생하고, 중복 initialize 결과를 노출하지 않으면서 최대 세 번 재시도합니다.

chrome-devtools-mcp는 의도적으로 고정(pin)하지 않습니다 — 폴백은 최신 릴리스로 따라갑니다. 여기서 특정 버전의 재연결 동작에 의존하는 것은 없습니다. 모든 브라우저 도구 결과는 다운스트림이 재연결을 보고했는가와 관계없이 발급된 임대 세대 하에서 검증됩니다. 따라서 최신 릴리스가 fail-closed 계약을 조용히 약화시킬 수 없습니다. 해석 순서는 결정적으로 다음과 같습니다.

1. --browser_command 또는 MCP_AGENTS_BROWSER_COMMAND(명령 문자열 또는 JSON argv).

2. 패키지 로컬로 해석 가능한 chrome-devtools-mcp, 그 다음 node_modules/.bin/chrome-devtools-mcp.

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

세 번째 경로는 첫 initialize가 npm 해석을 기다리게 할 수 있습니다. 빠른 시작이 필요하다면 mcp-agents와 함께 chrome-devtools-mcp를 설치하거나, 다른 위치에 설치한 다음 --browser_command로 실행 파일을 지정하세요. 특정 배포에 고정 버전이 필요하면 그곳에서 핀을 유지하세요. 브라우저 다운스트림은 자체가 해석한 chrome-devtools-mcp 릴리스가 지원하는 Node 버전을 요구합니다. 이 패키지의 >=26 하한은 고정되지 않은 의존성이 최신을 따라가는 한 그 이상으로 유지됩니다.

chrome-devtools-mcp는 의도적으로 런타임 의존성이 아닌 개발 의존성입니다. 따라서 개발자 체크아웃은 패키지 로컬 경로를 사용하고, 배포된 패키지의 사용자는 패키지를 mcp-agents와 함께 설치하거나 명시적 명령을 제공하지 않는 한 npx 폴백을 사용합니다.

viewport는 원격 크로미움의 창 크기를 설정하도록 임대 헬퍼에 전달됩니다. Chrome DevTools MCP의 --viewport는 --browserUrl로 연결할 때 쓸모가 없기 때문에 의도적으로 전달하지 않습니다.

완료된 다운스트림 JSON-RPC 프레임이 있을 때마다 세대 유휴 타이머가 리셋됩니다. stderr와 부분 출력은 리셋하지 않습니다. 유휴 timeout 해제는 60초의 정리 상한을 가지므로 원격 크로미움, SSH 터널, 박스가 실제로 종료될 수 있습니다. 종료 시 해제는 별도의 15초 상한이 있으며, 계속 추적되어 회수됩니다. 둘 다 best-effort 비용 최적화입니다. Chrome이 사라지면 중단된 네이티브 연결 오류를 재생하지는 않습니다. 헬퍼 상태 69는 오류에 browser_lease_replaced을 추가해 브라우저가 교체되었고, 상태가 손실되었으며, 중단된 결과를 알 수 없고, 호출자가 무작정 재생성 대신 상태를 점검해야 함을 명시적으로 경고합니다. 상태 0은 네이티브 오류를 그대로 유지하고, 상태 70은 임대 손실로 잘못 해석되지 않고 알 수 없는 것으로 남습니다. 다음 브라우저 호출은 다시 획득하며 Chrome DevTools MCP의 reconnect 경로를 사용합니다.

클라이언트 초기화 프레임과 다운스트림 roots/list 요청/응답은 ID나 URI 재작성 없이 전달됩니다. 다운스트림 재시작 시, 종료된 프로세스에 반환해야 할 응답은 폐기되고 해당 요청 상관관계는 교체 프로세스가 ID를 재사용하기 전에 정리됩니다. 이는 Chrome DevTools MCP의 로컬 파일 쓰기 허용 목록을 보존하므로 --allowUnrestrictedPaths는 의도적으로 절대 전달되지 않습니다. App 및 MinIO 사전 점검 실패는 별도로 원문 그대로 표시됩니다. Performance trace 및 Lighthouse 설명은 원격 링크 측정이 게이트가 아니라고 경고하며, upload_file은 로컬 경로를 원격 Chromium에 직접 넘길 수 없다고 경고합니다.

URL 제한은 옵트인 방식입니다. 루프백 전용 기본값은 OAuth와 타사 자산을 깨뜨리기 때문입니다. 강화된 루프백 전용 배포는 예를 들어 다음을 반복할 수 있습니다:

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

대상 애플리케이션과 호환되는 가장 좁은 패턴을 사용하세요. 제공자는 실험적인 페이지 ID 라우팅을 활성화하지 않습니다. 하나의 프로세스가 하나의 임대, 프로필, 포트를 소유합니다.

codex (통과)

codex 제공자는 격리된 CODEX_HOME 안에서 Codex의 네이티브 MCP 서버(codex mcp-server)로 통과합니다. 브리지는 서버 시작 디렉터리의 전용 tmp/codex-homes/ 트리 아래에 각 홈을 만들고, auth.json을 복사하고, 최소한의 config.toml을 작성하며, 일반적인 외부 MCP 서버 목록은 상속하지 않습니다. 이렇게 하면 브리지 호출 중에 Codex가 Claude나 Gemini 같은 다른 에이전트 도구를 재귀적으로 시작하지 않습니다. 상위 및 생성된 홈 디렉터리는 모드 0700을 사용하고, 복사된 자격 증명과 생성된 런타임 파일은 모드 0600을 사용합니다.

격리된 홈은 인증 스냅샷입니다. 브리지가 다시 연결되기 전에는 이후의 codex login을 볼 수 없습니다. Codex가 유형화된 unauthorized 터미널 이벤트를 보고하면, 래퍼는 중복 이벤트를 억제하고 structuredContent.code를 codex_auth_invalidated로, action을 reauthenticate_and_restart로 설정하여 MCP 도구 오류 하나를 반환합니다. status, result, cancel, peek, ping 및 기타 MCP 작업이 계속 사용 가능한 동안 새로운 Codex 턴은 로컬에서 거부됩니다. 브리지를 중지하고, 동일한 OS 사용자로 codex logout 및 codex login을 실행하고, codex exec로 확인한 다음 다시 연결하세요. 정리 시, 순환된 인증은 격리된 복사본이 변경되었고 표준 인증이 여전히 시작 스냅샷과 일치하는 경우에만 다시 기록됩니다. 따라서 오래된 브리지는 최신 수동 로그인이나 다른 브리지의 토큰 순환을 덮어쓸 수 없습니다.

허용 목록에 있는 유일한 사용자 기본 설정은 Fast 모드입니다. 시작 시 브리지는 원본 $CODEX_HOME/config.toml을 읽고 최상위 service_tier = "fast"와 [features].fast_mode = true를 모두 찾은 경우에만 격리된 홈에서 Fast 모드를 활성화합니다. 부분적이거나 비활성화되었거나 누락되었거나 읽을 수 없는 설정은 Standard 모드를 유지합니다. 다른 모든 사용자 구성은 격리된 상태로 유지됩니다. 두 설정 중 하나를 변경한 후 MCP 서버를 다시 시작하세요. Fast 모드는 더 높은 ChatGPT 크레딧 소비 또는 API Priority 과금을 사용합니다.

기타 시작 기본값: sandbox_mode=workspace-write, approval_policy=never(--sandbox_mode / --approval_policy로 서버 전체에 대해 구성 가능), web_search=cached, check_for_update_on_startup=false, allow_login_shell=false, history.persistence=none. 고정된 브리지 기능 기본값은 features.multi_agent=false, features.apps=false, features.plugins=false, features.hooks=false, features.skill_mcp_dependency_install=false입니다. 앱/플러그인은 ChatGPT 앱/플러그인 스킬(예: Figma, Gmail, Presentations 등)이 브리지된 세션 컨텍스트에 들어오지 않도록 비활성화된 상태를 유지합니다. 네이티브 서브에이전트는 추가로 [agents] enabled = false로 비활성화됩니다. Codex >= 0.145.0에서는 안정화된 multi_agent 기능 플래그만으로는 더 이상 협업 도구가 제거되지 않기 때문입니다. 세션은 allow_subagents(아래 참조)로 호출별로 다시 옵트인합니다. 해당 [agents] 줄은 버전을 인식합니다. 브리지는 시작 시 codex --version을 한 번 프로브하고 Codex < 0.145.0에서는 이를 생략합니다. 그 버전에서는 [agents] 아래의 부울이 치명적인 구성 구문 분석 오류(0.102–0.144)이고 기능 플래그가 여전히 협업 도구를 자체적으로 게이트하기 때문입니다. 구문 분석할 수 없는 버전은 최신 Codex로 간주합니다.

Workspace-write 세션은 기본적으로 네트워크 액세스가 활성화되어 샌드박스 명령이 DynamoDB, Redis, OpenSearch, MinIO 같은 로컬 서비스에 도달할 수 있습니다. 서버 전체에서 비활성화하려면 --codex-workspace-network=false 또는 MCP_AGENTS_CODEX_WORKSPACE_NETWORK_ACCESS=false를 설정하세요. CLI 플래그가 환경 변수보다 우선합니다. 이는 서버 소유 샌드박스 설정이며 호출별 도구 스키마에는 의도적으로 포함되지 않습니다.

Codex는 이 설정에 대해 localhost 전용 범위 지정을 제공하지 않습니다. 이를 활성화하면 workspace-write 세션의 명령에서 일반적인 아웃바운드 네트워크 액세스가 허용됩니다. 파일 시스템 쓰기는 작업 공간 및 기타 구성된 쓰기 가능 루트로 제한된 상태로 유지됩니다. read-only 및 danger-full-access 세션은 sandbox_workspace_write 설정을 사용하지 않습니다.

브리지는 Codex의 광범위한 구성 형태의 네이티브 스키마를 의도적으로 작은 계약으로 대체합니다:

두 스키마 모두 additionalProperties: false를 설정합니다. 지원되지 않거나 누락되었거나 유효하지 않은 인수는 Codex가 실행되기 전에 JSON-RPC -32602로 로컬에서 거부됩니다. 여기에는 config, approval-policy, developer-instructions, base-instructions, compact-prompt 같은 네이티브 탈출구가 포함됩니다. 향후 업스트림 스키마 추가는 mcp-agents가 의도적으로 채택할 때까지 숨겨진 상태로 유지됩니다. 두 선택지 밖의 모델 값도 같은 방식으로 거부됩니다.

네이티브 서브에이전트. codex 또는 codex-start에서 allow_subagents: true를 설정하면 해당 세션이 Codex의 기본 제공 멀티 에이전트 도구(spawn_agent, wait_agent, …)를 사용할 수 있습니다. 이는 sandbox와 정확히 동일하게 세션 범위로 적용됩니다. 회신은 이를 상속하며 변경할 수 없고, 기본값은 꺼짐입니다. 내부적으로 이 플래그는 호출별 구성 재정의를 통해 네이티브 멀티 에이전트 게이트(agents.enabled 및 features.multi_agent, 위와 동일한 버전 게이트에 해당)만 전환합니다. 격리된 홈의 다른 모든 것은 변경되지 않습니다. 특히 [mcp_servers] 제거는 계속 적용되므로 생성된 서브에이전트는 Codex 전용 인프로세스 워커입니다. 이들은 이 브리지에 다시 들어오거나 Claude, Gemini 또는 다른 외부 MCP 도구에 도달할 수 없으며, 실제 $CODEX_HOME/agents/의 사용자 지정 에이전트 역할은 복사되지 않습니다. 남은 주의 사항은 도달 범위가 아니라 동시성입니다. 서브에이전트는 세션의 sandbox_mode와 approval_policy를 상속하므로 approval_policy=never인 workspace-write에서는 여러 에이전트가 동시에 같은 작업 공간에 쓸 수 있습니다. Codex가 이를 조정하지만, 그에 맞춰 작업을 범위 지정하세요.

approval_policy=never는 MCP 브리지에 의도적입니다. 분리된 도구 호출은 대화형 승인 대화를 안정적으로 수행할 수 없기 때문입니다. 운영자는 --approval_policy로 서버 전체에 대해 untrusted 또는 on-request를 선택할 수 있지만, 호출자는 요청별로 해당 정책을 약화시키거나 변경할 수 없습니다. 각 새 세션은 여전히 샌드박스를 명시적으로 명시해야 하므로 쓰기 권한이 호출 지점에서 보입니다.

시작 플래그(--model, --model_reasoning_effort)는 격리된 네이티브 Codex 서버 기본값(gpt-5.6-sol 및 xhigh, 재정의되지 않은 경우)을 구성합니다. 각 초기 codex 호출은 두 모델 중 하나와 허용된 네 가지 추론 노력 중 하나를 선택할 수 있습니다:

선택자는 세션을 만들 때만 적용됩니다. 둘 중 하나를 생략하면 서버 구성 기본값을 사용합니다. 모든 codex-reply는 두 선택을 모두 상속하며 변경할 수 없습니다. 다른 모델과 노력 수준은 폐쇄된 래퍼 계약을 통해 의도적으로 사용할 수 없습니다.

예를 들어, 읽기 전용 검토는 다음과 같이 시작합니다:

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

목표 주입. 서버 시작 시 --goal "<text>"로 기본 목표를 설정하거나 호출에서 goal을 전달하세요. mcp-agents는 초기 목표를 내부적으로 Codex의 네이티브 developer-instructions로 변환합니다:

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

개발자 메시지는 스레드에 유지되므로 회신이 이를 상속합니다. codex-reply의 호출별 goal은 간결한 프롬프트 알림이 됩니다. 네이티브 회신 도구에는 developer-instructions 필드가 없기 때문입니다. 직접적인 개발자 지시는 노출되지 않습니다. goal은 좁고 감사 가능한 지속 목표 인터페이스입니다. 호출별 목표는 서버 기본값을 재정의하며, ""은 한 호출 동안 해당 기본값을 억제합니다.

브리지는 tools/list 응답을 다시 작성하여 이러한 선별된 스키마를 광고합니다. 일반 네이티브 프레임은 위에서 설명한 유형화된 인증 실패를 제외하고 바이트 단위 그대로 통과합니다. 로컬에서 생성된 검증 및 인증 오류는 진행 및 복구 메시지와 동일한 프레임 안전 대기열/경계 규율을 사용합니다.

스레드 내 우선순위. 최초 codex 호출에서 설정된 목표는 개발자 역할 메시지이며 전체 스레드에 걸쳐 유지되므로 우선순위를 가집니다: 이후 codex-reply에서 제공된 다른 goal은 프롬프트 수준의 알림일 뿐이며 기존 목표를 확실하게 덮어쓰지 않습니다(실제로 검증됨 — 초기 목표와 충돌하는 reply 목표는 기존 목표를 우선하여 무시됩니다). reply 알림은 충돌하는 기존 목표와 맞서지 않을 때 작동합니다. 흐름 중간에 목표를 진짜로 변경하려면 codex-reply에서 변경하는 대신 새 codex 호출을 시작하세요.

참고 — 이것은 Codex의 기본 /goal이 아닙니다. Codex의 /goal 슬래시 명령어(수명 주기/예산/증거 기반 완료를 갖춘 영구적이고 스레드 범위의 목표 상태)는 TUI 전용 기능입니다 — Codex 터미널 UI에서 구문 분석되며 codex mcp-server를 통해서는 도달할 수 없습니다. MCP 프롬프트에 /goal … 접두사를 붙여도 활성화되지 않습니다. 텍스트는 사용자 메시지로 그대로 전달될 뿐입니다. 따라서 이 래퍼는 developer-instructions(지속적인 목표를 위한 MCP 기본 수단)로 Codex를 제어하며, 이는 프롬프트/역할 조건화이지 기본 목표 수명 주기 하위 시스템이 아닙니다.

호출별 활성 상태. codex 통과(pass-through)는 열려 있는 모든 tools/call을 독립적으로 추적합니다. --codex_idle_timeout <seconds>(기본값 600, 0이면 비활성화)는 하나의 호출이 관련 Codex 활동 없이 지속될 수 있는 시간을 제한합니다. 해당 호출의 _meta.requestId(또는 일치하는 응답 또는 대화형 교환)를 담은 Codex 이벤트만 유휴 마감 시한을 갱신합니다. Codex stderr, 클라이언트 핑, 관련 없는 요청, 다른 호출에 속한 이벤트는 정체된 호출을 살려 둘 수 없습니다. 호출이 유휴 마감 시한에 도달하면 래퍼는 JSON-RPC 오류(-32001)로 그 호출만 실패시키고, 해당 요청에 대해 Codex에 notifications/cancelled를 보냅니다 — 이는 최선의 노력(best-effort)으로, Codex를 강제로 멈추게 하는 것이 아니라 멈추도록 요청합니다(아래 취소(Cancellation) 참조) — 정체된 호출의 늦은 기본 응답을 억제하고 연결을 유지합니다 — 형제 호출과 stdio 전송은 영향을 받지 않습니다. 이는 중요한데, stdio 전송이 닫히면 Claude Code와 같은 MCP 클라이언트가 서버를 failed로 표시하고 세션의 나머지 기간 동안 모든 mcp__codex__* 도구를 영구적으로 등록 해제하기 때문입니다(stdio 서버는 자동으로 다시 연결되지 않음). 따라서 단일 정체된 리뷰가 전체 브리지를 절대 중단시켜서는 안 됩니다. Codex 프로세스 그룹은 실제 종료(클라이언트 연결 끊김, 신호, 또는 stdout EPIPE) 시 여전히 정리됩니다. 한 가지 예외: Codex가 응답 프레임을 쓰는 중간에 멈춰 있고(오류를 주입할 안전한 경계가 없음) 취소도 무시하는 경우, 래퍼는 한 번 재시도한 다음 제한된 전체 브리지 종료로 확대합니다 — 부분적인 프레임에 깨끗한 프레임을 내보낼 방법이 없으므로 클라이언트는 새 브리지에 다시 연결해야 합니다.

취소(Cancellation). 클라이언트 취소(notifications/cancelled — 모든 ESC, 중단된 턴, 또는 서브에이전트 종료)도 동일하게 처리됩니다: 정확히 하나의 요청을 소모합니다. --codex_cancel_grace <seconds>(기본값 30)는 Codex가 이를 확인하는 데 걸릴 수 있는 시간을 제한합니다. 만료되면 래퍼는 해당 요청 id를 로컬에서 정산하고, Codex의 늦은 응답을 억제하며, 브리지와 모든 형제 호출을 계속 실행되도록 둡니다. 요청을 정산하는 것은 Codex가 멈췄다는 증거가 아닙니다 — 확인되지 않은 턴은 중단된(abandoned) 것으로 기록되며 계속 실행되고 쓰기를 할 수 있습니다. 위에서 설명한 중간 프레임 확대는 두 번째 전체 유예를 준비하므로, 그 경로는 브리지가 종료되기까지 약 두 배가 걸립니다. 유예 기간은 의도적으로 넉넉합니다 — Codex는 턴 중간에 샌드박스 명령을 실행 중이며 MCP 취소를 신속히 처리하지 않으므로, 짧은 유예는 확대 경로를 기본 경로로 만들 것입니다. 이는 제한 시간 경우보다 더 중요한데, 격리된 CODEX_HOME이 Codex의 sessions/ 디렉터리를 보유하기 때문입니다: 전체 브리지 종료는 해당 프로세스의 모든 threadId를 영구히 재개 불가능하게 만들고, 다음 codex-reply는 Session not found로 실패합니다.

[!WARNING] 요청을 중단한다고 Codex가 멈추지는 않습니다. 래퍼가 멈추도록 요청하지만, 취소를 무시하는 턴은 클라이언트가 포기한 후에도 계속 실행되고 — 작업 공간에 계속 쓰기를 합니다. 모든 중단은 해당 thread_id 및 job_id와 함께 stderr에 기록되며, 턴이 나중에 완료되면 다시 기록됩니다. 따라서 예상치 못하게 수정된 트리를 추측 대신 설명할 수 있습니다. 백그라운드 작업이 여기서 가장 예리한 지점입니다: codex-start 작업은 이 래퍼의 작업 테이블에 존재하며, MCP 클라이언트의 작업 레지스트리에는 있지 않습니다. 따라서 클라이언트 측의 "stop task"는 그 작업에 도달할 수 없습니다 — 오직 jobId를 사용한 codex-cancel만 가능합니다. 작업은 이 프로세스를 통해 폴링되므로 재연결 후에도 결코 생존할 수 없습니다. 따라서 클라이언트 연결이 끊기면 모든 비종결 작업과 열린 요청이 취소되고, 제한된 정리(wind-down)가 Codex 프로세스 그룹을 계속 실행 중이면 정리합니다.

--timeout <seconds>는 Codex 호출에도 변경할 수 없는 하드 마감 시한(기본값 7200)으로 적용됩니다. 관련 활동은 유휴 창을 연장할 수 있지만 이 하드 마감 시한은 절대 연장할 수 없습니다. 클라이언트가 포기하기 전에 항상 래퍼의 명시적 오류를 받아야 하는 경우, 래퍼 마감 시한을 MCP 클라이언트 자체의 벽시계 도구 제한 시간보다 낮게 설정하세요.

들어오는 요청이 _meta.progressToken을 제공하면, 래퍼는 해당 정확한 토큰을 사용하여 표준 MCP notifications/progress 업데이트를 보냅니다. 진행 토큰을 임의로 만들지 않습니다. 첫 번째 유용한 상태는 즉시 전송됩니다. 이후 업데이트는 초당 최대 한 번으로 통합되며, 가장 최신 상태가 우선합니다. 조용한 작업 중에는 Codex: still running 알림이 10초마다 전송되며 마지막 요청-관련 Codex 이벤트의 경과 시간을 포함합니다.

상태 텍스트는 실패 시 폐쇄(fail-closed) 방식입니다. 브리지는 명시적으로 귀속된 해설, 활성 계획 단계, 그리고 명령, 패치, MCP 도구, 웹/이미지 작업, 서브에이전트에 대한 일반적인 수명 주기 요약을 노출합니다. 최종 답변 텍스트, 추론, 프롬프트, 명령 문자열 또는 출력, 도구 인수, 검색 쿼리, 파일 경로, 토큰 원격 측정은 노출하지 않습니다. 메시지는 공백이 정규화되고 200개의 유니코드 코드 포인트로 제한됩니다. 기본 codex/event 프레임은 바이트 단위로 변경되지 않은 채 유지되지만, 유형화된 unauthorized 오류 이벤트는 위의 단일 구조화된 인증 실패로 대체됩니다. 진행 상황은 병렬 MCP 채널이며 일반적으로 추가 도구 결과/모델 컨텍스트가 아니라 UI 상태입니다.

선택적 백그라운드 작업. 기존 codex 및 codex-reply 호출은 계속 차단(blocking)되며 현재 동작을 유지합니다. 대화 내용에 표시되는 업데이트가 필요한 클라이언트는 대신 Codex 브리지가 알리는 6개의 래퍼 소유 작업 도구를 사용할 수 있습니다:

긴 빌드를 포함하여 차단 codex 호출을 선호하세요. 상태 변경마다 호출자 턴 하나 대신 도구 호출 하나만 소모하며, 진행 상황을 인식하는 UI에 notifications/progress를 계속 스트리밍하고, 턴을 중단하여 취소할 수 있습니다. 작업이 호출자보다 더 오래 유지되어야 할 때만 작업을 사용하세요 — 기다리기를 중단한 후에도 계속 실행되어야 하거나, 다른 에이전트가 나중에 jobId로 취소할 수 있어야 하는 경우입니다.

codex-peek — 그 턴이 아직 작동 중인가요?

차단 호출은 반환될 때까지 불투명해서, 외부에서는 "멈춤(wedged)"과 "바쁨(busy)"이 동일해 보입니다. codex-peek은 어떤 것도 취소하지 않고 이 질문에 답합니다: 진행 중인 모든 Codex 턴(차단 및 백그라운드 모두)을 읽기 전용으로 즉시 나열하며, 선택적으로 cwd / threadId / requestId 필터를 받습니다.

대신 턴별 프로세스를 찾지 마세요: codex mcp-server는 오래 지속되며 모든 요청을 다중화하므로 찾을 수 있는 codex exec가 없고, 빌드가 실행되는 동안 프로세스 테이블 확인은 아무것도 보고하지 않습니다.

보기보다 의미가 적은 세 가지 답변이 있습니다. 빈 목록은 턴이 완료되었다는 증거가 아닙니다 — 중단된 턴은 보고할 진행 중인 항목 없이 Codex 내부에서 계속 실행되며, 그 수는 abandonedTurnsProcessWide로 반환됩니다 — 그 범위에 따라 이름이 붙은 이유는 중단된 턴은 작업 공간을 유지하지 않으므로 필터로 좁혀지지 않기 때문입니다. 큰 elapsedSeconds는 멈춤이 아닙니다 — 단지 벽시계 시간일 뿐입니다. 큰 lastActivitySeconds도 마찬가지입니다. 단일 도구 호출은 정당하게 수분 동안 조용히 실행될 수 있으므로, 조용함은 완료가 아니라 입증되지 않음입니다. 알아내려고 취소하는 것은 되돌릴 수 없는 유일한 일입니다. 그리고 cwd 필터는 작업 공간을 알 수 없는 턴을 숨기지 않습니다 — cwdUnknown으로 보고합니다. "알 수 없음"이 조용히 "거기 아무것도 실행 중이 아님"이 되어서는 안 되기 때문입니다.

시작 결과는 불투명한 jobId, 상태 cursor, 그리고 다음 권장 호출과 함께 즉시 반환됩니다. 반복적인 codex-status 호출은 일반 MCP 도구 결과를 생성하므로, 외부 에이전트나 서브에이전트는 UI가 notifications/progress를 렌더링하지 않더라도 Codex가 무엇을 하는지 중계할 수 있습니다 — 이는 작업이 차단 호출과 달리 제공하는 유일한 가시성입니다. 현재 커서에서 상태 호출은 변경을 기다린 후 하트비트를 반환합니다. wait_ms는 0에서 60000 사이로 설정할 수 있으며, 생략하면 아래의 상태 간격(해당 페이싱이 비활성화된 경우 10000)으로 기본 설정됩니다.

상태 대기를 끝내는 것은 두 가지이며, 둘 다 폴링 비용과 관련이 있습니다. 커서 전진은 서버 측에서 --codex_status_interval <seconds>(기본값 30)에 의해 조절되며, 모든 메시지에서 커서를 증가시키는 대신 중간 진행 상황을 병합합니다. 다른 하나는 wait_ms 하트비트이며, 이는 해당 간격으로 조절되지 않습니다. 따라서 wait_ms는 이제 상태 간격을 추적합니다(60000으로 제한되므로 60초를 초과하는 간격에서도 여전히 60초마다 하트비트를 보냅니다). 이렇게 해서 하트비트가 자신이 보고하는 커서보다 앞서 나가지 않도록 합니다. wait_ms는 유휴(idle) 대기의 상한선으로 남으며 폴링 간격의 하한선이 아닙니다. 커서가 이미 헤드보다 뒤처져 있으면 상태 호출은 즉시 반환되므로, 뒤처진 폴러는 이를 올려도 느려지지 않지만, 따라잡은 폴러는 느려질 수 있습니다. 이것이 wait_ms를 낮추면 아무 이득 없이 턴만 소모되는 이유입니다.

조절되는 것은 중간 진행 업데이트뿐입니다. 수명주기 전환(첫 번째 running, 취소, 그리고 모든 종료 상태)은 커서를 증가시키고 대기 중인 모든 호출자를 직접 깨우며 간격을 우회하므로, 값을 올려도 완료가 지연되지 않습니다. 정지 감지 역시 영향을 받지 않습니다. lastActivitySeconds는 상태 틱이 아닌 원시 Codex 이벤트에서 스탬프되며, codex-commentary는 전체 내러티브를 계속 보존합니다. 0은 모든 변경 시 커서 전진을 복원하고, 60 초과 값은 하트비트 상한이 제어하도록 두고 상태 텍스트만 오래되게 만듭니다. 진행 *알림(notification)*은 훨씬 더 세밀한 자체 주기를 유지하며 호출자의 컨텍스트를 소모하지 않지만, 차단(blocking) 호출에서만 발송됩니다. 백그라운드 작업의 요청에는 진행 토큰이 없으므로 작업의 유일한 가시성은 codex-status / codex-commentary입니다.

commentaryEndOffset이 전진하면 마지막 nextOffset으로 codex-commentary를 호출하세요. Commentary에는 명시적으로 commentary 단계로 표시된 Codex 메시지만 포함됩니다. 숨겨진 추론, 프롬프트, 최종 답변 초안, 명령 문자열과 출력, 도구 인자, 경로, 검색 쿼리, 원시 응답 항목은 제외됩니다. 안전하지 않은 터미널 제어 코드는 제거되지만, 나머지 텍스트는 모델이 작성한 것이므로 여전히 신뢰할 수 없는 것으로 취급해야 합니다. 오프셋은 유니코드 코드 포인트를 셉니다. 각 읽기는 최대 32,768코드 포인트를 반환하며, 브리지는 1MiB UTF-8 테일을 유지하고 오래된 코멘터리가 버퍼에서 벗어나면 절대 잘림 경계를 보고합니다.

상태가 종료 상태가 되면 codex-result를 사용하고 done이 true가 될 때까지 nextOffset에서 계속 읽으세요. 각 페이지는 페이로드를 일반 MCP 텍스트 콘텐츠와 구조화된 결과를 우선시하는 클라이언트용 structuredContent.text로 동시에 반환합니다. 결과 페이지 역시 32,768코드 포인트로 제한됩니다. 브리지의 10 MiB 캡처 한도를 초과하는 네이티브 결과 프레임은 개인 응답을 MCP 전송으로 유출하는 대신 작업을 원자적으로 실패시킵니다.

작업은 의도적으로 연결-로컬(connection-local)입니다. MCP 서버를 재시작하거나 다시 연결하면 작업이 손실됩니다. 최대 8개의 작업이 활성 상태일 수 있고 32개의 레코드가 보존되며, 종료 레코드는 1시간 후 만료됩니다. 취소는 차단 호출과 동일한 제한된 마무리 의미론을 가지므로, 취소된 쓰기 가능 작업을 재시도하기 전에 작업 트리를 검사하세요. 작업 API는 호출 수준의 옵트인(opt-in)이며 클라이언트의 MCP Tasks 지원을 요구하지 않습니다.

이러한 알림은 의도적으로 진행 상황을 인식하는 클라이언트의 유휴 창을 활성 상태로 유지하며, 생존성 판단 권한은 래퍼의 유휴 및 하드 마감에 남겨 둡니다. 이 알림은 --codex_idle_timeout을 갱신하지 않으며, 래퍼의 하드 마감을 연장하지 않고, 클라이언트의 별도 하드 벽시계 도구 타임아웃도 연장하지 않습니다. 생성된 진행 프레임은 네이티브 줄바꿈 경계에서만 삽입됩니다. Codex가 프레임 중간에 멈추면 최신 알림은 안전한 경계를 기다리며, 실제 유휴 감시자는 영구적인 정지를 계속 종료합니다. 클라이언트 타임아웃을 예상되는 가장 긴 Codex 실행 시간에 응답 여유를 더한 값보다 크게 구성하세요. 타임아웃이 만료되면 클라이언트가 호출을 취소하고 아래의 제한된 취소 경로가 이어받습니다.

종료 결과 복구(Terminal-result recovery). Codex는 요청과 상관관계가 있는 초기 세션 이벤트에서 스레드 ID를 알리므로, 래퍼는 빌드가 끝나기 전에 이를 보관합니다. 이후 Codex가 종료 완료 이벤트와 최종 에이전트 메시지를 내보냈지만 네이티브 tools/call 응답이 짧은 종료 응답 유예 기간 내에 도착하지 않으면, 래퍼는 content와 structuredContent.threadId를 모두 포함하는 동등한 성공 결과를 반환합니다. 일치하는 늦은 네이티브 응답은 폐기되어 정확히 한 번(exactly-once) JSON-RPC 응답 의미론을 보존합니다. 이는 작업이 트리에 반영되었지만 호출자가 결과도 스레드 ID도 받지 못하는 장애 모드를 다룹니다.

취소 및 재연결. 클라이언트 취소는 --codex_cancel_grace로 제한되는 짧고 재설정할 수 없는 유예 기간을 시작합니다(아래의 중간 프레임 에스컬레이션은 두 번째 유예 기간을 가동시키므로 해당 경로는 약 두 배 더 걸릴 수 있습니다). Codex가 그 안에서 마무리되지 않으면 래퍼는 해당 요청 ID를 로컬에서 마무리하고 Codex의 늦은 응답을 억제하며 브리지와 모든 형제 호출을 계속 실행 상태로 둡니다. 단일 지연 호출이 전체 브리지를 중단시켜서는 안 됩니다. 제한된 예외는 두 가지입니다. 프레임 중간에 고착되어 취소까지 무시하는 스트림(오류를 주입할 안전한 경계가 없으므로 래퍼는 한 번 재시도한 다음 전체 브리지 해체로 에스컬레이션함)과 총량 상한입니다. 억제된 응답이 MAX_SUPPRESSED_CODEX_RESPONSES에 도달하면 브리지는 무기한 추적하는 대신 종료합니다. 두 경우 중 하나가 발생한 후 클라이언트는 새 브리지에 다시 연결합니다. 부분적으로 전달된 프레임을 손상시키지 않고 가로챌 수 있을 때마다 유예 기간 내에 도착한 네이티브 응답은 폐기됩니다. 취소된, 잠재적으로 쓰기 가능한 호출은 자동으로 재생되지 않습니다. 취소는 최선 노력(best-effort)이며 Codex가 중지되었음을 증명하지 않습니다. 확인되지 않은 턴은 종료된 것이 아니라 중단된 것으로 기록되며 계속 실행되고 작업 공간에 쓰기를 수행할 수 있으므로, 수동으로 재시도하기 전에 작업 트리를 검사하세요.

이 레거시 브리지는 의도적으로 기존 stdio 연결 안에서 codex mcp-server를 다시 생성하지 않으며, 스레드를 투명하게 재생하지도 않습니다. codex-reply 상태는 이전 Codex 프로세스에 속하므로, 종료된 자식 프로세스의 스레드 ID는 재연결 후 재개될 수 없습니다. 동일 연결에서 지속되는 복구를 위해서는 투명한 레거시 패스스루에서 codex app-server 위의 MCP 어댑터(thread/start, turn/start, turn/interrupt, thread/resume)로의 별도 마이그레이션이 필요합니다.

Claude Code 연동

전역에 설치된 mcp-agents 바이너리를 사용하여 프로젝트의 .mcp.json에 항목을 추가하세요:

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

npm(전역 설치)과 npx — 전역에 설치된 바이너리를 선호하세요. 위의 command: "mcp-agents" 형식은 로컬에 설치된 바이너리를 직접 실행합니다. 아래의 npx 대안은 모든 프로세스 시작 시 npx -y mcp-agents를 실행합니다. 이는 콜드 스타트 속도만이 아니라 안정성과 관련이 있습니다. Claude Code는 (재)연결할 때마다 — 세션 중 재연결 이후를 포함해 — stdio 서버를 다시 실행하며, npx는 오프라인 폴백 없이 매 실행마다 패키지 레지스트리 해석을 수행합니다. 그 해석이 느리거나(VPN, 캡티브 포털, 레지스트리 일시 장애), 더 이상 존재하지 않는 버전으로 오래된 캐시가 고정되어 있거나(npm error code ETARGET), 또는 다른 이유로 실패하면 실행이 실패하고, 전송이 닫히며, 세션 동안 도구를 사용할 수 없게 됩니다. 전역에 설치된 바이너리(또는 node server.js의 절대 경로)는 네트워크 의존성과 시그널/해체 경로의 프로세스 한 단계를 제거합니다. npm install -g mcp-agents(또는 소스 체크아웃에서 npm link)로 한 번 설치한 다음, 설정이 이를 가리키게 하세요.

개인 Codex 브리지로 사용하는 **소스 체크아웃(from-source checkout)**의 경우, 사용자 수준의 ~/.claude.json 항목이 트리를 직접 실행하고 요청별 유휴 상한을 비활성화할 수 있습니다(그렇게 하면 길고 정당하게 조용한 리뷰가 조기에 중단되지 않고 클라이언트 자체의 벽시계 타임아웃에 의해서만 제한됩니다):

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

단순히 node라고 쓰면 MCP 클라이언트의 PATH를 기준으로 확인됩니다. node가 해당 환경에서 초기화되지 않은 버전 관리자(nvm/fnm/asdf)로 관리되고 있다면, 절대 노드 경로를 대신 사용하세요(which node, 예: /opt/homebrew/bin/node).

서버 시작 시 codex 기본값을 재정의하세요:

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

모든 초기 codex 호출은 gpt-5.6-sol 또는 gpt-5.6-terra와 medium, high, xhigh, max 중 하나를 선택할 수 있습니다. 생략된 선택자는 서버 기본값을 사용하며, 회신은 두 선택을 모두 상속합니다. 다른 모델, 원시 config, 호출별 승인 정책 인자는 Codex 실행 전에 거부됩니다. 기본 목표를 제공하려면 args에 "--goal", "<text>"를 추가하세요(위의 목표 주입 참조).

Claude는 서버별 timeout을 밀리초 단위의 하드 벽시계 상한으로 해석합니다. 진행 상황이 이를 연장하지 않습니다. 응답 여유를 포함해 래퍼의 --timeout(기본값 7,200초)보다 높게 유지하세요. 프로젝트 .mcp.json 항목은 같은 이름의 사용자 수준 MCP 항목을 재정의할 수 있으므로, 사용자 수준 사본에 의존하지 말고 타임아웃을 프로젝트 항목에 두세요.

위에서 설명한 명시적인 Fast-mode 쌍을 제외하고, 브리지는 일반 ~/.codex/config.toml에서 설정을 상속하지 않습니다. 특히 상속된 MCP 서버는 브리지된 Codex 세션 내에서 의도적으로 사용할 수 없는 상태로 유지됩니다.

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

npx는 프로세스 실행에만 영향을 줍니다. 일단 연결되면 도구 호출 지연 시간은 어느 쪽이든 동일한 서버 코드입니다. 그러나 모든 실행(각 재연결 포함)은 오프라인 폴백 없이 npm 레지스트리에서 패키지를 해석하므로, 느리거나 오프라인이거나 오래된 캐시 상태의 해석은 실행을 실패시키고 세션 중간에 도구를 잃을 수 있습니다(위의 npm vs npx 참조). mcp-agents@x.y.z를 고정하면 세션 중간에 @latest가 갓 게시된 버전을 가져오는 것을 피할 수 있지만, 실행별 네트워크 의존성은 제거되지 않습니다. npx는 설치 없음이 실행 안정성보다 중요할 때만 사용하세요.

OpenAI Codex 연동

~/.codex/config.toml에 항목 두 개를 추가하세요 — 사용하려는 각 공급자당 하나씩입니다. 960초 Claude 클라이언트 타임아웃은 차단 방식의 900초 claude_code 도구와의 호환성을 유지합니다. 백그라운드 리뷰는 하나의 MCP 요청을 계속 열어 두지 않습니다. claude-start는 즉시 반환되고 각 claude-status 폴링은 최대 60초 동안 지속됩니다.

[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

Codex 세션에서 Claude의 소견이나 리뷰를 요청하고 claude-start → claude-status → claude-result를 사용하세요. claude_code는 작은 차단 프롬프트용으로 유지하고, gemini는 계속 차단 도구로 남습니다.

개발

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

npm link 후 server.js를 수정하면 재설치 없이 즉시 적용됩니다.

실제 /tmp 프로젝트 .mcp.json 파일을 통해 시작 경로를 벤치마크하세요:

npm run bench:mcp-startup

이는 initialize와 tools/list를 통한 MCP 시작을 측정하며, 공급자 모델/도구를 호출하지 않습니다.

수동으로 Claude 백그라운드 검사를 수행하려면 짧은 리뷰 프롬프트와 이 리포지토리를 cwd로 하여 claude-start를 호출하고, 반환된 각 커서로 claude-status를 폴링한 다음 claude-result로 결과를 읽으세요. 반대 방향으로는 Claude Code가 codex-start를 호출하고 codex-status를 폴링한 다음 codex-result를 읽게 하세요. 이러한 스모크 검사는 실제 모델 호출을 사용하며 결정적 테스트 스위트 게이트와는 별개입니다.

작동 방식

1. MCP 클라이언트가 stdio를 통해 연결합니다.

2. 서버는 argv에서 --provider <name>을 읽습니다(기본값은 codex).

3. Gemini는 차단 CLI 도구 하나를 등록합니다. Claude는 레거시 차단 도구와 일회성 리뷰 작업 도구를 등록합니다. Codex는 네이티브 도구를 전달하고 백그라운드 작업 도구를 추가합니다.

4. 클라이언트는 도구 이름과 prompt로 tools/call을 호출합니다.

5. 서버는 CLI를 분리된 자식 프로세스로 실행합니다. Claude 리뷰 작업은 stream-json을 안전한 상태 및 보존된 결과 페이지로 파싱하고, 차단 도구는 정규화된 공급자 출력을 반환합니다.

서버는 작은 keepalive 타이머를 유지하여, async 하위 프로세스가 활성 핸들을 등록하기 전에 stdin이 EOF에 도달해도 Node.js가 조기 종료되지 않도록 합니다. Claude 및 Gemini 제공자 모드의 경우, 해당 keepalive는 종료 중에 해제됩니다. MCP stdio 연결이 닫히면 활성 Claude 작업은 인터럽트와 제한된 TERM/KILL 폴백을 수신하며, 추적 중인 분리된 제공자 프로세스 그룹은 서버가 종료되기 전에 정리됩니다.

License

MIT