Codex MCP 서버 사용법: Agents SDK에서 코덱스를 도구처럼 호출하는 워크플로 | DAKER 커뮤니티

Codex MCP 서버 사용법은 codex mcp-server로 Codex CLI를 MCP 서버처럼 띄우고, OpenAI Agents SDK 같은 MCP 클라이언트에서 codex 도구를 호출하는 방법입니다. 2026년 6월 기준 OpenAI Codex 공식 문서는 이 서버가 codex와 codex-reply 두 도구를 제공한다고 설명합니다. 지금 중요한 이유는 개발자가 Codex를 단발 채팅이 아니라 검증 가능한 에이전트 파이프라인의 한 단계로 넣을 수 있기 때문입니다.

## Codex MCP 서버는 언제 쓰면 좋나요?

한 줄 요약: Codex를 사람이 직접 여는 도구가 아니라 다른 에이전트가 호출하는 개발 실행 도구로 쓰고 싶을 때 MCP 서버가 맞습니다.

문제 상황은 이렇습니다. 팀이 요구사항 정리 에이전트, 구현 에이전트, 검증 에이전트를 나눠 운영하고 있습니다. 그런데 실제 저장소를 읽고 파일을 고치는 단계는 Codex CLI가 잘합니다. 이때 각 에이전트가 직접 셸 명령을 만들게 두기보다, Codex를 MCP 도구로 붙이면 역할을 더 선명하게 나눌 수 있습니다.

Codex MCP 서버란 Codex CLI를 장시간 실행되는 MCP 서버로 열어 외부 MCP 클라이언트가 Codex 세션을 시작하거나 이어가게 하는 연결 방식입니다. 공식 문서 기준 첫 호출은 codex 도구가 맡고, 이어지는 후속 호출은 threadId를 넘겨 codex-reply로 진행합니다.

기존에 MCP 연결 자체가 낯설다면 DAKER의 [코덱스 MCP와 앱 연결 확인 글](https://daker.ai/community/codex-tool-usage-18-check-mcp-app-connection)을 먼저 보면 좋습니다. 최신 문서 확인 루틴은 [코덱스 웹 검색 근거 수집 글](https://daker.ai/community/codex-tool-guide-21-web-search-evidence-surface)과 함께 잡으면 안전합니다.

## Agents SDK에서 Codex MCP 연결 구조는 어떻게 보이나요?

핵심 개념은 “오케스트레이션과 코드 실행을 분리한다”입니다. Agents SDK 쪽 에이전트는 역할, handoff, trace, guardrail을 다루고, Codex MCP 서버는 저장소 안에서 계획·수정·검증을 수행합니다.

| 구성 요소 | 맡는 일 | 주의할 점 |

| --- | --- | --- |

| codex mcp-server | Codex CLI를 MCP 서버로 실행 | Codex CLI 설치와 인증이 선행되어야 함 |

| codex 도구 | 새 Codex 세션 시작 | prompt, cwd, sandbox, approval-policy를 좁게 지정 |

| codex-reply 도구 | 기존 세션 이어가기 | 응답의 threadId를 보존해야 함 |

| Agents SDK | 에이전트 역할, handoff, 추적 | Codex에게 맡길 작업 범위를 너무 넓히지 않기 |

OpenAI 문서에 따르면 codex 도구는 prompt를 필수로 받고, 필요하면 cwd, model, sandbox, approval-policy, config, profile 같은 설정을 함께 받을 수 있습니다. 이 말은 자동화에서 “어디서, 어떤 권한으로, 어떤 지시를 실행할지”를 코드로 고정할 수 있다는 뜻입니다.

## Codex MCP 서버는 어떤 순서로 설정하나요?

단계별 사용법은 아래 순서가 가장 단순합니다.

1. 로컬에서 Codex CLI가 설치되어 있고 codex 명령이 실행되는지 확인합니다.

2. Agents SDK를 쓸 Python 환경을 만들고 필요한 패키지를 설치합니다.

3. MCP 클라이언트 코드에서 codex mcp-server를 stdio 서버로 실행합니다.

4. 첫 작업은 codex 도구로 시작하고, 후속 작업은 응답의 threadId를 저장해 codex-reply로 이어갑니다.

5. cwd, sandbox, approval-policy를 작업별로 좁게 지정합니다.

6. 완료 후에는 Codex가 만든 변경, 테스트 결과, 검증 로그를 별도 단계에서 확인합니다.

운영 자동화라면 DAKER의 [Codex GitHub Action CI 리뷰 글](https://daker.ai/community/codex-github-action-safe-pr-review-automation)을 같이 참고하세요. GitHub Actions 안에서는 직접 CLI를 조립하기보다 공식 액션이 더 안전한 경우가 많고, 로컬·사내 도구에서는 MCP 서버 방식이 더 유연한 경우가 많습니다.

## 짧은 예시는 어떻게 구성하나요?

아래는 운영 코드가 아니라 구조를 보여 주는 최소 예시입니다. 핵심은 Codex를 “개발자 역할의 도구”로 등록하고, 실행 권한을 좁게 지정한 뒤 결과를 검증 단계로 넘기는 것입니다.

1. MCP 클라이언트가 codex mcp-server를 stdio 서버로 실행합니다.

2. 개발자 역할 에이전트에는 “저장소 변경은 Codex MCP 도구로 수행한다”는 지시를 둡니다.

3. 첫 요청에는 작업 목표, cwd, sandbox, approval-policy를 함께 넘깁니다.

4. 응답에서 받은 threadId를 저장하고, 후속 요청은 codex-reply로 이어갑니다.

5. 완료 뒤에는 변경 파일, 테스트 출력, 남은 위험을 사람이 읽을 수 있는 형식으로 남깁니다.

실제 팀 workflow에서는 Codex 호출 전후에 입력 검증, 변경 파일 범위 확인, 테스트 명령 제한, 결과 trace 저장이 필요합니다.

## 실수 방지 체크리스트는 무엇인가요?

- codex mcp-server를 실행하기 전에 Codex CLI 인증과 작업 디렉터리를 확인했나요?

- cwd 없이 넓은 위치에서 Codex를 호출하지 않았나요?

- 자동화에서 danger-full-access를 기본값처럼 쓰고 있지 않나요?

- 첫 호출의 threadId를 저장하지 않아 후속 codex-reply가 새 맥락으로 흩어지지 않나요?

- Agents SDK의 handoff 지시와 Codex 프롬프트가 서로 다른 목표를 말하고 있지 않나요?

- 결과를 “성공”으로만 읽지 않고 변경 파일, 테스트 출력, 남은 위험을 확인했나요?

- 외부 배포, 비용 발생, 권한 변경, 민감정보 접근은 별도 승인 경계로 분리했나요?

## 공식 출처는 어디에서 확인했나요?

이 글은 2026년 6월 28일 기준 OpenAI Developers의 Codex SDK, 비인터랙티브 실행 모드, Agents SDK 연결 문서를 확인해 작성했습니다. DAKER 공개 본문에는 디렉터리 정책상 외부 URL을 노출하지 않고, 브라우저로 확인한 DAKER 내부 글만 링크했습니다.

방법론의 한계도 있습니다. 이 글은 공식 문서의 공개 기능 설명을 바탕으로 한 실무 구성 안내입니다. 실제 동작은 설치된 Codex CLI 버전, Agents SDK 버전, 조직의 인증 방식, 로컬 sandbox 정책, MCP 클라이언트 구현에 따라 달라질 수 있습니다.

## 자주 묻는 질문

### Codex MCP 서버와 codex exec는 무엇이 다른가요?

codex exec는 스크립트나 CI에서 Codex를 비인터랙티브로 한 번 실행하기 좋습니다. Codex MCP 서버는 외부 에이전트나 MCP 클라이언트가 Codex 세션을 시작하고 이어가야 할 때 더 적합합니다.

### codex-reply에는 무엇을 넘겨야 하나요?

기존 Codex 세션을 이어가려면 threadId와 다음 prompt가 필요합니다. 첫 codex 호출 응답에서 받은 threadId를 잃어버리면 같은 맥락을 안정적으로 이어가기 어렵습니다.

### Agents SDK 없이도 Codex MCP 서버를 쓸 수 있나요?

가능합니다. MCP 클라이언트라면 원칙적으로 codex mcp-server에 연결할 수 있습니다. 다만 이 글은 OpenAI 공식 가이드가 설명한 Agents SDK 연결 방식을 기준으로 정리했습니다.

### 자동화에서는 어떤 sandbox가 적당한가요?

읽기만 필요한 조사 작업은 read-only, 파일 수정이 필요한 작업은 workspace-write부터 시작하는 편이 안전합니다. danger-full-access는 격리된 실행 환경과 명확한 필요가 있을 때만 검토하세요.

### Codex MCP 서버를 팀 workflow에 바로 넣어도 되나요?

바로 전체 배포 파이프라인에 넣기보다 작은 저장소, 좁은 작업, 명확한 테스트 명령으로 시작하세요. trace와 변경 diff를 사람이 검토할 수 있어야 팀 workflow로 확장할 수 있습니다.

오늘 사내 개발 에이전트에 Codex를 붙이려 한다면, 먼저 codex mcp-server가 맡을 작업 하나와 그 작업의 cwd, sandbox, 검증 명령부터 문서로 고정해 보세요.

DAKER 코덱스: Agents SDK에서 Codex MCP 서버를 호출하는 기본 구조

DAKER 코덱스: codex mcp-server 연결 전 확인할 실행 단계와 안전 경계