Claude Code에서 MCP를 통해 Codex를 호출할 때 최소 설정에서 겪은 문제

Claude Code로 설계를 마친 후, 구현만 Codex에 위임하고 싶은 상황이 있었습니다. 매번 별도의 터미널에서 Codex를 실행하고 작업 범위나 금지 사항을 수동으로 붙여넣다 보면 누락이 발생합니다.

그래서 Claude Code에서 Codex를 MCP 서버로서 호출하는 설정을 도입했습니다. 문제가 된 부분은 MCP의 JSON 자체보다는, Codex CLI의 실체, 작업 디렉토리(working directory), sandbox / approval policy의 전제가 모호한 상태에서 호출해 버리는 점이었습니다.

이 기사에서는 1개 기사당 1개의 트러블로 한정하여 「Claude Code에서 Codex를 호출하는 최소 설정」에 집중합니다. Codex 측에 어떤 일을 시킬지, 리뷰를 어떻게 돌려받을지에 대한 설계론은 별도의 기사로 나눕니다.

이 리포지토리에서는 프로젝트 루트에 다음 .mcp.json을 두고 있습니다.

{
"mcpServers": {
"codex": {
...

설정 자체는 이것뿐입니다. Claude Code는 이 정의로부터 codex라는 MCP 서버를 찾아내고, codex mcp-server를 실행합니다.

포인트는 여기에 작업 규칙을 쑤셔 넣지 않는 것입니다. .mcp.json은 「어떤 명령어로 MCP 서버를 실행할 것인가」만을 갖게 합니다. 구현 범위, 금지 사항, 검증 명령어는 호출하는 쪽의 skill이나 의뢰 문구로 고정합니다.

저의 운용 방식에서는 Codex를 호출하기 전에 다음을 확인합니다.

Codex MCP 호출 전 체크:
- codex CLI가 PATH에서 실행 가능한가
- Claude Code를 대상 리포지토리의 루트에서 실행했는가
...

MCP 서버 등록만 하면 Codex는 「호출할 수 있는」 상태가 됩니다. 하지만 호출할 수 있는 것과, 의도한 작업만을 맡길 수 있는 것은 별개의 문제입니다.

특히 cwd(current working directory)는 명시해야 합니다. Claude Code를 프로젝트 루트에서 실행하지 않으면, Codex 측이 다른 디렉토리를 전제로 동작할 수 있습니다. 의뢰 문구에는 다음과 같이 작성합니다.

대상 리포지토리의 루트를 cwd로 하여 작업해 주세요.
작업 범위는 다음 파일로 한정해 주세요.
- src/main/services/exampleService.js
...

첫 번째 실패는 Claude Code 측에서 바라본 codex 명령어를 찾을 수 없다는 것이었습니다. 자신의 터미널에서는 동작하더라도, Claude Code가 실행되는 환경에서는 PATH가 다를 수 있습니다.

이 경우 command에 절대 경로를 쓰고 싶어지지만, 공개 리포지토리에 로컬 절대 경로를 두면 환경 의존적이 됩니다. 우선은 설치 경로와 PATH를 수정하고, 공개 설정은 다음과 같이 유지하는 방침으로 정했습니다.

{
"mcpServers": {
"codex": {
...

또 다른 함정은 PATH에는 codex가 있지만, 실체가 망가져 있는 케이스입니다. 로컬 확인을 위해 codex --help를 실행했을 때, Node의 shim이 참조 대상을 찾지 못해 실패하는 상태가 있었습니다. 이 경우 역시 .mcp.json의 문제가 아니라, Codex CLI의 설치 상태 문제로 분리하여 대응합니다.

Codex에 구현을 맡길 때, 처음부터 넓은 권한을 부여하면 사고가 발생합니다. 반대로 권한이 부족하면 필요한 명령어에서 멈추게 됩니다.

저의 운용에서는 기본적으로 다음과 같은 사고방식을 취했습니다.

sandbox:
- 일반 편집: workspace-write
- 조사 전용: read-only 상당
...

MCP 서버 등록 JSON에는 이 판단을 전부 적지 않습니다. 대신 Codex에 전달하는 의뢰 문구에 「추가 권한이 필요하면 멈추고 이유를 보고할 것」이라고 명시합니다.

네트워크, 외부 서비스, 추가 권한, danger-full-access가 필요해지면 작업을 중단하고,
필요한 이유와 미완료 범위를 보고해 주세요.

이렇게 하면 Codex가 멋대로 권한을 확장하는 것이 아니라, 사용자의 판단으로 돌아올 수 있습니다.

Claude Code에서 Codex를 호출하는 용도는 구현 위임으로 한정했습니다.

반대로 Codex에서 Claude Code를 호출할 때는 review-only로 합니다. 양쪽 모두가 동일한 worktree에서 구현을 시작하면, 차이점(diff)의 소유자가 누구인지 알 수 없게 됩니다.

그렇기 때문에 Codex에 전달하는 의뢰는 다음과 같은 형태로 맞추고 있습니다.

당신은 구현 담당입니다.
설계된 계획에 따라, 체크박스 순서대로 구현해 주세요.
작업 범위는 계획 파일에 작성된 파일과 책임(responsibility)으로 한정해 주세요.
...

MCP 서버는 단순한 접속구입니다. 작업 계약(work contract)을 부여하지 않으면, 편리한 호출구가 '광범위하게 접근 가능한 입구'가 되어 버립니다.

문제가 발생했을 때는 Claude Code 측의 MCP 설정을 의심하기 전에, 먼저 codex 명령어를 단독으로 실행하여 문제를 분리(isolation)합니다.

codex --help
codex mcp-server --help

여기서 실패한다면 MCP의 JSON 문제가 아니라 CLI의 설치나 PATH 문제입니다. 반대로 단독 명령어가 작동한다면, 다음으로는 Claude Code를 실행한 위치, .mcp.json을 둔 위치, 의뢰문에서 지정한 cwd(current working directory)를 확인합니다.

이 순서를 따르면 "MCP가 잘못된 것인지", "Codex CLI가 잘못된 것인지", "작업 디렉토리가 다른 것인지"를 혼동하지 않을 수 있습니다.

• Claude Code에서 Codex를 호출하는 최소 설정은 .mcp.json의 command: "codex"와 args: ["mcp-server"]만으로 충분함
• 실제로 막히는 부분은 Codex CLI가 Claude Code 측의 PATH에서 실행 가능한지, 작업 디렉토리가 맞는지, 권한 방침이 명확한지 여부임
• .mcp.json에는 실행 방법만 작성하고, 작업 범위·cwd·금지 사항·verify는 의뢰문이나 skill로 고정함
• 구현 위임과 리뷰 위임을 섞지 말고, Codex에는 한정된 구현만을 맡기며 commit / push는 시키지 않음

Codex MCP 서버 등록은 입구에 불과합니다. 입구를 만든 후, 무엇을 하게 하고 어디서 멈추게 할지를 결정하는 것이 본론이었습니다.

• harness17/zenn-articles - 본 기사에서 다룬 기사 리포지토리
• OpenAI Codex CLI - Codex CLI의 공개 리포지토리
• Codex와 Claude Code를 상호 호출하는 하네스(harness)를 구축함 - 상호 호출 전체의 설계 메모