codex-as-mcp

codex-as-mcp는 MCP 클라이언트(Claude Code, Cursor 등)가 Codex CLI에 작업을 위임할 수 있도록 하는 작은 Model Context Protocol (MCP) 서버입니다.

이 서버는 서버의 현재 작업 디렉토리(current working directory)에서 Codex를 실행하는 두 가지 도구(tools)를 제공합니다:

spawn_agent(prompt: str)

spawn_agents_parallel(agents: list[dict])

내부적으로 각 에이전트는 다음과 유사한 명령을 실행합니다:
codex exec --cd <server cwd> --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox "<prompt>"

참고: --dangerously-bypass-approvals-and-sandbox 옵션은 샌드박싱(sandboxing)과 확인 프롬프트(confirmation prompts)를 비활성화합니다. 신뢰할 수 있는 저장소(repos)에서만 이 서버를 사용하십시오.

codex-as-mcp에는 두 가지 도구가 있습니다.

프롬프트를 사용하여 병렬로 Codex 서브 에이전트(subagents)를 생성할 수 있습니다.

다음은 두 가지 작업을 병렬로 위임하는 Codex 세션의 샘플입니다.

Codex CLI >= 0.46.0 버전이 필요합니다

npm install -g @openai/codex@latest
codex login
# 설치 확인
...

Codex CLI가 사용자의 머신에서 비대화형(non-interactively)으로 실행될 수 있는지 확인하십시오 (~/.codex/config.toml에 provider + credentials가 있거나, 참조하는 provider별 환경 변수(env var)를 통해 설정되어 있어야 함).

제3자 제공자(third-party provider)를 사용하는 경우, Codex config.toml에서 이를 구성하고 model_provider를 해당 제공자로 지정하십시오. 제공자가 env_key를 사용하는 경우, Codex CLI는 실행 시 해당 환경 변수가 존재할 것을 기대합니다.

예시:

model_provider = "custom_provider"
[model_providers.custom_provider]
name = "custom_provider"
...

codex-as-mcp를 사용할 때, MCP 서버 프로세스에 해당 환경 변수가 설정되어 있어 생성된 codex 프로세스로 전달될 수 있도록 해야 합니다. 환경 변수 이름은 반드시 위의 env_key 값과 일치해야 합니다 (여기서는: PROVIDER_API_KEY).

옵션 A (권장): MCP 클라이언트 설정에 환경 변수 설정 (지원되는 경우)

{
"mcpServers": {
"codex-subagent": {
...

옵션 B: 서버 인자(args)를 통해 환경 변수 전달

uvx codex-as-mcp@latest --env PROVIDER_API_KEY=KEY_VALUE

옵션 C: Codex CLI를 통해 추가 (codex mcp add)

codex mcp add codex-subagent --env PROVIDER_API_KEY=KEY_VALUE -- uvx codex-as-mcp@latest

보안 주의 사항: 명령줄 인자 (command-line args)를 통해 비밀 정보 (secrets)를 전달하면 사용 중인 머신의 프로세스 목록 (process lists)을 통해 노출될 수 있습니다. 가능한 경우 옵션 A를 권장합니다.

.mcp.json에 추가:

{
"mcpServers": {
"codex-subagent": {
...

또는 Claude Desktop 명령어를 사용하십시오:

claude mcp add codex-subagent -- uvx codex-as-mcp@latest

Codex CLI를 직접 설정하는 경우 (예: ~/.config/codex/config.toml), 다음을 추가하십시오:

[mcp_servers.subagents]
transport = "stdio"
command = "uvx"
...

spawn_agent(prompt: str)

– 서버의 작업 디렉토리 (working directory)를 사용하여 자율적인 Codex 서브에이전트 (subagent)를 생성하고 에이전트의 최종 메시지를 반환합니다.

spawn_agents_parallel(agents: list[dict])

– 여러 개의 Codex 서브에이전트를 병렬로 생성합니다. 각 항목에는 반드시 prompt 키가 포함되어야 하며, 결과에는 에이전트당 output 또는 error가 포함됩니다.

만약 다음과 같은 오류가 발생하는 경우:

tool call failed for `subagents/spawn_agent`
timed out awaiting tools/call after 60s
deadline has elapsed

이는 일반적으로 클라이언트 측의 MCP 도구 호출 (tool-call) 타임아웃 (timeout)입니다. spawn_agent는 생성된 codex exec 프로세스가 완료될 때까지 반환되지 않으며, 이 과정은 60초보다 오래 걸릴 수 있습니다.

해결 방법: MCP 클라이언트의 도구 호출 타임아웃을 늘리십시오.

Codex 설정 파일 (~/.codex/config.toml 또는 ~/.config/codex/config.toml)에서 MCP 서버에 대해 더 높은 tool_timeout_sec를 설정하십시오:

[mcp_servers.subagents]
transport = "stdio"
command = "uvx"
...

MCP Inspector로 로컬 테스트를 수행하는 경우, 요청 타임아웃 (request timeouts)을 늘리십시오 (또는 이 값들을 내보내는(export) ./test.sh를 실행하십시오):

export MCP_SERVER_REQUEST_TIMEOUT=300000
export MCP_REQUEST_TIMEOUT_RESET_ON_PROGRESS=true
export MCP_REQUEST_MAX_TOTAL_TIMEOUT=28800000