MCP Codex-CLI Integration

codex-cli란?

codex-cli (@openai/codex-shell-tool-mcp) ├── Type: Shell Execution Tool (NOT AI Model) ├── Function: mcp__codex-cli__shell ├── Capability: Execute shell commands └── Limitation: No AI prompting capability

핵심 이해

구분 gemini-cli codex-cli

타입 AI Model MCP Shell Tool MCP

AI 응답 ✅ 가능 ❌ 불가능

스킬 처리 자체 처리 Claude가 처리

용도 AI 질의 명령 실행

When to use this skill

• 명령 실행: 빌드, 테스트, 배포 스크립트 실행

• 파일 조작: 파일 읽기/쓰기, 디렉토리 생성

• 환경 확인: 시스템 상태, 의존성 확인

• 스킬 기반 작업: 스킬 로드 후 codex-cli로 실행

Instructions

Step 1: 스킬 + codex-cli 통합 패턴

패턴 A: 스킬 읽기 → Claude 처리 → codex-cli 실행

1. Claude가 스킬 파일 읽기 (Read tool)
2. 스킬 내용 기반으로 작업 계획 수립
3. codex-cli로 명령 실행
4. 결과 분석 및 다음 단계 진행

예시:

사용자: "api-design 스킬을 참조해서 새 API 엔드포인트 생성해줘"

Claude 처리:

1. Read: .agent-skills/backend/api-design/SKILL.md
2. 스킬 내용 분석 및 코드 생성
3. codex-cli: 파일 생성 및 테스트 실행

Step 2: codex-cli 명령 실행

기본 사용법:

// MCP 도구 호출 mcp__codex-cli__shell({ command: "npm run build", workdir: "/path/to/project" })

응답 형식:

{ "exit_code": 0, "output": "Build successful", "duration": {"secs": 5, "nanos": 123456789}, "timed_out": false }

Step 3: 스킬 기반 작업 실행

Infrastructure 스킬 예시:

1. 스킬 로드: infrastructure/system-environment-setup
2. Claude가 스킬 분석
3. codex-cli로 Docker Compose 실행:
   • docker-compose up -d
   • docker-compose logs
   • docker-compose ps

Code Quality 스킬 예시:

1. 스킬 로드: code-quality/code-review
2. Claude가 리뷰 기준 확인
3. codex-cli로 린트/테스트 실행:
   • npm run lint
   • npm run test
   • npm run type-check

Step 4: 결과 처리 패턴

codex-cli 실행 ↓ exit_code 확인 ↓ ├── 0 (성공): 다음 단계 진행 ├── 1 (실패): 오류 분석 후 수정 └── timeout: 명령 최적화 또는 분할

통합 워크플로우

sequenceDiagram participant U as User participant C as Claude Code participant S as SKILL.md participant X as codex-cli

U->>C: 작업 요청
C->>S: Read 스킬 파일
S-->>C: 스킬 내용
C->>C: 스킬 기반 계획 수립
C->>X: shell 명령 실행
X-->>C: 실행 결과
C->>C: 결과 분석
C->>U: 완료 보고

실전 예제

예제 1: 스킬 기반 프로젝트 초기화

사용자: "infrastructure 스킬을 참조해서 Docker 환경 세팅해줘"

Claude 작업:

1. Read: .agent-skills/infrastructure/system-environment-setup/SKILL.md
2. 스킬의 docker-compose.yml 템플릿 활용
3. Write: docker-compose.yml 생성
4. codex-cli: docker-compose up -d
5. codex-cli: docker-compose ps (상태 확인)

예제 2: 스킬 기반 코드 리뷰

사용자: "code-review 스킬로 이 PR 체크해줘"

Claude 작업:

1. Read: .agent-skills/code-quality/code-review/SKILL.md
2. 리뷰 체크리스트 확인
3. codex-cli: git diff --name-only
4. Read: 변경된 파일들
5. 스킬 기준으로 리뷰 수행
6. codex-cli: npm run lint (자동 검사)

예제 3: 스킬 기반 배포

사용자: "deployment 스킬로 스테이징 배포해줘"

Claude 작업:

1. Read: .agent-skills/infrastructure/deployment-automation/SKILL.md
2. 배포 절차 확인
3. codex-cli: npm run build
4. codex-cli: npm run test
5. codex-cli: ./deploy.sh staging
6. 결과 보고

Constraints

필수 규칙 (MUST)

• 스킬은 Claude가 처리: codex-cli는 AI 응답 불가, 스킬 해석은 Claude가 담당

• workdir 명시: 모든 codex-cli 명령에 절대 경로 workdir 필수

• 결과 확인: exit_code 확인 후 다음 단계 진행

금지 사항 (MUST NOT)

• codex-cli에 프롬프트 전달 금지: AI 응답 기대하지 않음

• 무한 루프 금지: 실패 시 3회 이상 재시도 금지

• 민감 정보 출력 금지: 환경변수, 비밀키 로깅 주의

Best practices

1. 스킬 로드 → Claude 처리 → codex 실행

올바른 패턴

1. Claude: Read 스킬 파일

2. Claude: 작업 계획 수립

3. codex-cli: 명령 실행

4. 명령 체이닝

codex-cli에서 && 사용

npm install && npm run build && npm run test

3. 타임아웃 설정

mcp__codex-cli__shell({ command: "npm run build", workdir: "/path", timeout_ms: 60000 // 60초 })

gemini-cli vs codex-cli 사용 가이드

작업 유형 권장 도구 이유

AI 질의/분석 gemini-cli AI 응답 필요

창의적 아이디어 gemini-cli (brainstorm) 평가 점수 포함

명령 실행 codex-cli 빠른 shell 실행

파일 조작 codex-cli 또는 Bash 직접 실행

스킬 기반 작업 Claude + codex-cli 스킬은 Claude, 실행은 codex

Metadata

버전

• 현재 버전: 1.0.0

• 최종 업데이트: 2026-01-05

• 호환 플랫폼: Claude Code

관련 스킬

• git-workflow

• workflow-automation

태그

#mcp #codex-cli #shell #automation #integration

Examples

Example 1: Basic usage

Example 2: Advanced usage

References

• Official Documentation

• Best Practices Guide