AI/MCP

개발자를 위한 MCP 추천(8) - CODEX MCP 설치 및 사용방법

안녕하세요! 갓대희입니다.

오늘은 CODEX MCP를 연동하고 사용하는 방법에 대해 알아보려고 한다.

Claude Code의 대화형 인터페이스와 OpenAI Codex의 코드 생성 능력을 함께 사용 해보려 한다.

사전 준비

필요 항목

ChatGPT 구독: Plus, Pro, Business, Edu, Enterprise 플랜 중 하나 (또는 OpenAI API 키)
운영체제: macOS 또는 Linux (Windows는 WSL 권장 - 실험적 지원)
Claude Code (VS Code 확장) 또는 Claude Desktop: 둘 중 하나 설치되어 있어야 함
터미널 접근: 기본 터미널 명령어 사용 가능
Node.js: npm 설치 방법을 활용시 필요

Step 0: Codex MCP가 뭐길래?

MCP(Model Context Protocol)는 여러 AI 도구를 하나의 인터페이스에서 불러 쓰도록 해주는 플러그인 프로토콜이다. Claude Code나 Claude Desktop이 MCP 서버를 친구처럼 호출해서 “코드를 직접 실행하거나”, “외부 API를 연결하거나” 같은 무거운 일을 대신 맡길 수 있다.

왜 Codex MCP인가?

Claude의 대화력 + Codex의 코드 생성력을 하나의 채팅에서 동시에 활용
프로젝트 파일을 Claude가 열람하고, 어려운 구현은 Codex에게 넘기는 하이브리드 작업 가능
MCP 서버 형태라서 VS Code, Cursor, Claude Desktop 어디서든 재사용

아래 단계에서는 Codex CLI를 설치하고, Claude에서 MCP 서버로 연결해서 바로 쓰는 과정을 순서대로 정리해보았다.

Step 1: Codex CLI 설치하기

Codex설치 및 인증 관련하여 자세한 내용이 필요한 경우는 하기 별도 링크를 참고 부탁 드립니다.

2025.09.19 - [AI/ChatGTP(Codex)] - GPT5 Codex CLI 사용방법(설치방법) - OpenAI Codex CLI 시작하기

대부분의 경우는 이미 설치가 되어 있으실테니, 간단하게만 살펴보도록 할 예정이다.

1-1. 설치 방법 선택

터미널에서 실행

방법 1: npm 사용 (모든 플랫폼, Node.js 필요)

npm install -g @openai/codex

방법 2: Homebrew 사용 (macOS 전용)

brew install --cask codex

💡 설치 팁
• npm 방식: 크로스 플랫폼 지원, Node.js 환경에서 관리 편하다.
• Homebrew 방식: macOS에 최적화, 시스템 패키지 관리자로 업데이트 간편함.
• 직접 다운로드: GitHub Releases에서 플랫폼별 바이너리 다운로드 가능 (macOS arm64/x86_64, Linux x86_64/arm64)

1-2. 설치 확인하기

설치 확인 명령어

codex --version

ex) 출력 예시

codex 0.57.0

❌ "command not found" 오류가 나온다면?
• npm 설치: 터미널 다시 열어보세요 (PATH 갱신 필요)
• Homebrew 설치: brew doctor로 Homebrew 상태 확인
• which codex 명령으로 설치 경로 확인
• npm global 경로 확인: npm config get prefix

Step 2: Codex CLI 첫 실행 및 인증

인증 방식 (Codex 5)

Codex CLI는 OpenAI의 GPT-5-Codex 모델을 사용하고, ChatGPT Plus/Pro/Business/Edu/Enterprise 플랜이나 OpenAI API 키가 필요해요. 첫 실행 시 자동으로 "Sign in with ChatGPT" 옵션이 나오고, 인증 토큰은 ~/.codex/auth.json에 안전하게 저장된다.

⚠️ 중요: 환경 변수 방식 지원 종료
최신 Codex CLI는 OPENAI_API_KEY 환경 변수를 더 이상 지원하지 않는다.
반드시 codex 명령으로 대화형 인증을 사용해야 한다.

2-1. Codex 첫 실행

터미널에서 실행

codex

2-2. "Sign in with ChatGPT" 선택

처음 실행하면 이런 화면이 나온다.

선택 화면

Welcome to Codex!

How would you like to authenticate?
  > Sign in with ChatGPT  (권장)
    Use API Key

화살표 키로 "Sign in with ChatGPT" 선택하고 Enter 누르면 된다!

2-3. 초기 설정 (선택사항)

인증 후 처음 실행하면 몇 가지 설정을 물어봐요:

설정 옵션

Approval Mode (승인 모드):
• Read Only: 코드 읽기만 가능
• Auto (권장): 파일 수정 자동 승인
• Full Access: 모든 작업 자동 승인
Model (모델 선택):
• GPT-5-Codex (권장): 코드 생성 특화
• GPT-5: 범용 모델
AGENTS.md 생성:
• 프로젝트 설정 파일 자동 생성 (나중에 /init 명령으로도 가능)

💡 재인증이 필요할 때
인증 토큰이 만료되거나 계정을 바꾸고 싶으면:

rm ~/.codex/auth.json
codex  # 다시 인증 화면 나옴

❌ 문제 해결
• 브라우저가 안 열린다면: 터미널에 표시된 URL 직접 복사해서 브라우저에 붙여넣기
• "Authentication failed" 오류: ChatGPT Plus/Pro 구독 확인
• WSL 환경: 브라우저 연동 안 되면 codex --help로 API 키 설정 방법 확인
• 재시도: rm ~/.codex/auth.json 후 다시 codex 실행

Step 3: MCP 서버 설정하기

각자의 환경에 따라 방법을 선택 하자.

Claude Code (VS Code 확장) → 방법 A
Claude Desktop (독립 앱) → 방법 B

방법 A: Claude Code (VS Code/Cursor 확장) 설정

VS Code나 Cursor에서 Claude Code 확장을 쓰고 있다면 이 방법으로 설정해요.
주의: settings.json이 아니라 mcp.json 파일을 사용한다!

A-1. mcp.json 파일 생성 또는 열기

Claude Code 확장은 mcp.json 파일로 MCP 서버를 설정합니다.

mcp.json 파일 위치

옵션 1: 글로벌 설정 (모든 프로젝트에 적용)

# Cursor 사용자
~/.cursor/mcp.json

# VS Code 사용자
~/.vscode/mcp.json

옵션 2: 워크스페이스 설정 (현재 프로젝트만)

# 프로젝트 폴더 내
.vscode/mcp.json

A-2. mcp.json 파일 내용 작성

mcp.json 파일을 열어서 다음 설정을 추가해요. 두 가지 방법 중 하나를 선택하자.

npm 래퍼 사용

{
  "mcpServers": {
    "codex": {
      "command": "npx",
      "args": ["-y", "codex-mcp-server"]
    }
  }
}

장점:

경로 문제 없음 (npx가 자동 해결)
Node 버전 바뀌어도 안정적
추가 기능 제공 (session management, listSessions 등)
환경 독립적

대안 방법: Codex CLI 직접 실행

{
  "mcpServers": {
    "codex-cli": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y", 
        "codex-mcp-server"
      ],
      "env": {}
    }
  },
}

장점:

최소 의존성 (Codex CLI만 필요)
네이티브 성능
직접적인 Codex 기능 접근

주의사항:

Codex CLI가 PATH에 있어야 함 (which codex로 확인)
PATH에 없다면 절대 경로 사용: "command": "/opt/homebrew/bin/codex"

방법 3: Claude Code CLI 명령어 사용

claude mcp add codex-cli -- npx -y codex-mcp-server

설명:

Claude Code CLI가 설치되어 있다면, 이 한 줄 명령으로 자동으로 mcp.json에 설정이 추가돼요!
가장 간단하고 오타 걱정도 없는 방법입니다.

💡 어떤 방법을 선택하면 좋을까?
• Claude Code CLI 있다면 → 방법 3 (CLI 명령어)이 가장 간단하다.
• 처음 사용하거나 경로 문제가 귀찮다면 → 방법 1 (npm 래퍼)
• 최소 의존성을 원하거나 네이티브 성능을 원한다면 → 방법 2 (Codex CLI 직접)

A-3. VS Code/Cursor 재시작

mcp.json 파일을 저장하고 에디터를 재시작하자.

방법 B: Claude Desktop 설정

Claude Desktop 독립 앱을 쓰고 있다면 이 방법으로 설정해요.

B-1. Codex 실행 파일 경로 찾기

방법 A-1과 동일하게 which codex 명령으로 경로 확인하고, 디렉토리 부분을 복사해두세요.
예: /usr/local/bin/codex → /usr/local/bin

B-2. Claude Desktop 설정 파일 위치

ex) 설정 파일 경로

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

B-3. 설정 파일 수정하기

텍스트 에디터로 설정 파일을 열자.

# macOS
code ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Linux
code ~/.config/Claude/claude_desktop_config.json

설정 내용 추가

{
  "mcpServers": {
    "codex": {
      "command": "codex",
      "args": ["mcp-server"],
      "env": {
        "PATH": "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
      }
    }
  }
}

⚠️ 주의: PATH 수정 필수!
위 설정에서 "PATH" 값을 B-1에서 확인한 경로로 바꿔야 한다.

예시:
• which codex 결과가 /opt/homebrew/bin/codex라면
• PATH에 /opt/homebrew/bin을 맨 앞에 추가:

"PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"

완성된 설정 파일 예시

{
  "mcpServers": {
    "codex": {
      "command": "codex",
      "args": ["mcp-server"],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
      }
    }
  }
}

B-4. Claude Desktop 재시작

파일 저장하고, Claude Desktop을 완전히 종료했다가 다시 실행해야 한다.

Claude Desktop 재시작 방법

Claude Desktop 완전히 종료 (창 닫기만 하면 안 됨!)
macOS: Cmd+Q 또는 메뉴에서 "Quit Claude"
Linux: 시스템 트레이에서 완전 종료
5초 기다린 후 Claude Desktop 다시 실행

❌ 자주 하는 실수
• args를 ["mcp"]로 쓰면 안 된다! → ["mcp-server"]가 정확함
• PATH에 Codex 디렉토리 없으면 "command not found" 오류 발생

Step 4: 연동 확인 및 첫 번째 테스트

4-1. MCP 서버 연결 확인하기

연결 확인 방법

Claude Code

쉽게 /mcp 로 확인 가능 하다.

Claude Desktop인 경우:

Claude Desktop 앱 열기
새 대화 시작
메시지 입력창 근처 도구 아이콘 클릭
연결된 MCP 서버 목록에서 "codex" 확인
codex 서버 확장하면 두 가지 도구 표시: codex, codex-reply

📌 참고
UI는 버전에 따라 조금씩 다를 수 있다. MCP 서버나 도구가 안 보이면, 재시작했는지, 설정 파일 저장했는지 다시 확인해보자.

4-2. 첫 번째 테스트: 간단한 코드 생성

이제 Claude Code에서 Codex를 호출 가능한데, 내 소스의 개선점 분석을 Codex와 함께 진행할 수있도록 해보겠다.

테스트 프롬프트

'emailTmpleate/server.js' 내 크롤링 소스인데 코덱스 CLI랑 함께 토론해서 해당 소스 개선 방향을 잡아줘.

Claude Code가 Codex MCP 서버로 요청 처리하고, 수행해 나가는 모습이다.

ex) codex cli와 토론 시키도록 유도

> '/Users/dedur/work/py/htmlGenerator/web/emailTmpleate/server.js' 내 크롤링 소스인데 코덱스 CLI랑 함께 토론해서 해당 소스 개선 
방향을 잡아줘.

4-3. Code MCP 활용 예시

연동 성공했으면, 이런 작업들도 간단하게 시도해보면 좋을 것 같다.

코드 리팩토링: 기존 코드 개선 요청
버그 찾기: 코드 스니펫 제공하고 문제점 찾기
테스트 코드 생성: 함수에 대한 단위 테스트 작성

세션 관리: 대화 연속성 유지하기

Codex MCP 서버는 세션 관리 기능을 제공한다. 세션을 활용하면 이전 대화의 맥락을 이어서 작업할 수 있다.

세션이란?

세션은 Codex와의 대화 기록을 저장하는 단위이다. 각 세션은 고유한 ID를 가지며, 24시간 동안 유지된다.

세션의 장점

대화 맥락 유지: 이전 요청 내용을 기억하고 이어서 작업
일관성 있는 코드: 같은 세션 내에서 코딩 스타일 유지
효율적인 협업: 여러 단계에 걸친 복잡한 작업 처리
자동 정리: 24시간 후 자동으로 만료 (TTL)

세션 목록 확인하기

Claude Code에서 현재 활성화된 세션 목록을 확인할 수 있다.

세션 목록 요청

현재 활성화된 Codex 세션 목록을 보여줘

Claude Code가 listSessions 도구를 사용해서 활성 세션 정보를 가져올 수 있다.

ex) 세션이 유지 되진 않았지만, 관련 내용에 대해서 Claude Code가 설명해주는 부분이 있어 첨부

특정 세션 이어서 작업하기

기존 세션 ID를 사용해서 이전 대화를 이어갈 수도 있다고 한다.

세션 ID 활용 예시

세션 ID abc123을 사용해서,
아까 작성한 피보나치 함수에 메모이제이션을 추가해줘

세션 TTL (Time To Live)

⏱️ 세션 만료 시간
모든 Codex 세션은 24시간의 생존 시간(TTL)을 가진다. 24시간이 지나면 자동으로 삭제되므로, 중요한 코드는 별도로 저장해두어야 된다.

이로써 codex mcp연동은 끝났지만, CODEX의 특징에 대해서도 간단하게 몇가지 중요한 사항은 정리 두려고 한다.

CODEX에 대한 내용 요약(codex mcp가 아닌 codex 기본 특징)

기본 사용법을 넘어, Codex MCP 서버의 고급 기능들을 활용해보자.

모델 선택 (Model Selection)

Codex는 여러 GPT 모델을 지원한다. 작업의 복잡도에 따라 적절한 모델을 선택할 수 있다.

사용 가능한 모델 (2025년 11월 2주차 codex 5.1이 출시되어 업데이트 시 다음과 같이 신규 모델을 사용할 수 있다.)

모델은 Claude Code와의 대화에서 간접적으로 영향을 받는다. Codex MCP 서버가 자동으로 최적의 모델을 선택하지만, 직접 Codex CLI를 사용할 때는 --model 옵션으로 지정할 수 있다.

추론 강도 조절 (reasoningEffort)

reasoningEffort 파라미터를 사용하면 Codex가 문제를 얼마나 깊이 분석할지 조절할 수 있다.

추론 강도 레벨

low: 빠른 응답, 간단한 코드 수정이나 질문
medium (기본값): 균형 잡힌 추론, 일반적인 코딩 작업
high: 심층 분석, 복잡한 아키텍처 설계나 알고리즘 최적화

💡 Tip
Claude Code를 통해 사용할 때는 이런 파라미터들이 자동으로 최적화된다. 직접 제어하고 싶다면 Codex CLI를 직접 사용하거나, Claude에게 "더 깊이 분석해줘" 같은 요청으로 간접적으로 조절할 수 있다.

대화 컨텍스트 최적화

Codex는 대화 기록을 유지하면서 토큰을 효율적으로 관리한다. 긴 세션에서는 다음 내용을 참고하자.

컨텍스트 최적화 전략

명확한 지시: "이전 코드를 기반으로" 같은 명시적 참조 사용
중간 요약: 복잡한 작업 중간에 "지금까지 내용 요약해줘" 요청
새 세션 시작: 완전히 다른 작업은 새 세션으로 분리
코드 블록 활용: 특정 코드 부분만 수정할 때 해당 블록 명시

Codex의 고급 기능 정리(상기 내용과 중복)

1. 모델 선택 및 추론 깊이 조정

Codex는 /model 명령으로 모델 바꿀 수 있다.

GPT-5-Codex Medium: 균형 잡힌 추론 능력 (기본)
GPT-5: 대안 모델
추론 깊이 조정: 복잡한 문제에 더 깊은 분석 적용 가능

2. 세션 컨텍스트 관리

Codex는 세션 기반으로 작동하고, 각 세션은 독립적인 컨텍스트 유지 가능하다.

컨텍스트 표시: "% context left" 지표로 남은 컨텍스트 확인
세션 상태: /status 명령으로 현재 설정 확인
AGENTS.md: 프로젝트별 지침 파일로 세션 간 기억 관리

3. 승인 정책 커스터마이징

안전성이랑 효율성 균형 맞추려면 승인 정책 조정하자.

untrusted: 모든 작업에 승인 필요 (제일 안전)
on-failure: 실패 시에만 승인 요청
never: 자동 실행 (제일 빠름, 주의 필요)

4. 웹 검색 통합 활용

Codex는 실시간 정보 가져올 수 있다.

최신 라이브러리 문서 참조
기술 스택 트렌드 확인
프레임워크 버전별 변경사항 검색

보안 모범 사례

중요한 보안 고려사항

샌드박스 모드 사용: 민감한 프로젝트에서는 read-only 또는 workspace-write 모드 권장
승인 정책 신중하게 설정: 프로덕션 환경에서는 untrusted 모드 사용
코드 리뷰 활용: /review 명령으로 커밋 전 독립 에이전트 검토
민감 정보 관리: 환경 변수나 시크릿은 절대 Codex에 직접 입력하지 말 것
Zero Data Retention: 데이터 보호 중요하면 ZDR 옵션 활용

자주 묻는 질문 ❓

Q1: 매번 codex login 해야 하나요?

A: 아니요, 한 번 인증하면 토큰이 ~/.codex/에 저장돼요. 토큰 만료되거나 다른 계정으로 바꿀 때만 다시 로그인하면 돼요.

Q2: API 사용량이 별도로 청구되나요?

A: ChatGPT Plus/Pro 구독으로 쓰는 경우 별도 청구 없어요. API 키 쓰는 경우에만 사용량에 따라 요금 부과돼요. 레거시 API 키 사용자는 새로운 청구 방식으로 마이그레이션 필요할 수 있어요.

Q3: 다른 MCP 서버랑 함께 쓸 수 있나요?

A: 네! 설정 파일의 mcpServers 객체에 여러 서버 추가할 수 있어요. Context7, Playwright, GitHub, Sentry 등 다른 MCP 서버랑 같이 설정 가능해요. Claude Code가 상황에 맞는 도구를 자동으로 골라줘요.

Q4: Windows에서는 안 되나요?

A: Windows는 실험적 지원 단계예요. WSL2(Windows Subsystem for Linux) 쓰면 대부분 정상적으로 작동해요. 네이티브 Windows 지원은 개선 중이에요. GitHub 저장소에서 최신 상태 확인하세요.

Q5: Codex CLI 버전은 어떻게 업데이트하나요?

A: npm 설치: npm update -g @openai/codex / Homebrew: brew upgrade codex 명령으로 최신 버전으로 업데이트할 수 있어요. Homebrew 업그레이드 관련 이슈는 공식 FAQ 참조하세요.

Q6: Claude Code랑 Codex 같이 쓰면 어떤 장점이 있나요?

A: Claude Code는 Anthropic의 Claude Sonnet 모델로 뛰어난 대화형 인터페이스랑 컨텍스트 이해력을 제공하고, Codex는 OpenAI의 GPT-5-Codex 모델로 강력한 코드 생성 능력을 제공해요. MCP로 이 둘을 결합하면, 서로 다른 AI 모델의 장점을 동시에 활용할 수 있어요. Claude의 자연어 이해력 + Codex의 코드 생성 능력 = 완전체! 🔥

Q7: Codex CLI는 오픈소스인가요?

A: 네, Codex CLI는 GitHub에서 Apache-2.0 라이선스로 공개되어 있어요. 50.3k+ 스타랑 230+ 기여자가 있는 활발한 프로젝트예요. Rust로 작성되어 있고(96.8%), 커뮤니티 기여 환영해요.

Q8: 성능은 어때요? 느리지 않나요?

A: Codex CLI는 Rust로 빌드되어서 로컬 실행 시 엄청 빨라요. 파일 읽기/쓰기는 네트워크 지연 없이 바로 실행되고, API 호출만 네트워크 필요해요. MCP 서버 시작은 처음 한 번만 발생하고, 이후 세션은 빠르게 응답해요.

📚 참고 자료

OpenAI Codex CLI 공식 저장소 (50.3k ⭐) - 최신 릴리스 및 이슈 트래킹
Codex CLI 공식 문서 - 상세한 사용법 및 옵션
Codex MCP 공식 문서 - MCP 서버 설정 가이드
Codex CLI 레퍼런스 - 전체 명령어 및 옵션 목록
GitHub Issues - 문제 해결 및 커뮤니티 지원
Codex 클라우드 버전 - 브라우저에서 바로 사용

저작자표시 비영리 변경금지 (새창열림)

'AI > MCP' 카테고리의 다른 글

Claude Code MCP 토큰 최적화 고민해보기(MCP 토큰 최적화에 대한 고찰 글) (3)	2025.12.16
Anthropic MCP 프로토콜 1년의 진화 - OpenAI 채택부터 Linux Foundation 이관까지 (2)	2025.12.15
개발자를 위한 MCP 추천(7) - Figma MCP 설치 방법 (5)	2025.10.21
개발자를 위한 MCP 추천(6) - Magic MCP 설치 및 사용방법 (6)	2025.10.15
개발자를 위한 MCP 추천(5) - Shrimp Task Manager MCP 설치 및 사용방법(claude code 사용 예시) (4)	2025.08.20

Contents

개발자를 위한 MCP 추천(8) - CODEX MCP 설치 및 사용방법

사전 준비

필요 항목

Step 0: Codex MCP가 뭐길래?

Step 1: Codex CLI 설치하기

1-1. 설치 방법 선택

터미널에서 실행

1-2. 설치 확인하기

설치 확인 명령어

Step 2: Codex CLI 첫 실행 및 인증

인증 방식 (Codex 5)

2-1. Codex 첫 실행

터미널에서 실행

2-2. "Sign in with ChatGPT" 선택

선택 화면

2-3. 초기 설정 (선택사항)

설정 옵션

Step 3: MCP 서버 설정하기

각자의 환경에 따라 방법을 선택 하자.

방법 A: Claude Code (VS Code/Cursor 확장) 설정

A-1. mcp.json 파일 생성 또는 열기

mcp.json 파일 위치

A-2. mcp.json 파일 내용 작성

npm 래퍼 사용

대안 방법: Codex CLI 직접 실행

방법 3: Claude Code CLI 명령어 사용

A-3. VS Code/Cursor 재시작

방법 B: Claude Desktop 설정

B-1. Codex 실행 파일 경로 찾기

B-2. Claude Desktop 설정 파일 위치

ex) 설정 파일 경로

B-3. 설정 파일 수정하기

설정 내용 추가

완성된 설정 파일 예시

B-4. Claude Desktop 재시작

Claude Desktop 재시작 방법

Step 4: 연동 확인 및 첫 번째 테스트

4-1. MCP 서버 연결 확인하기

연결 확인 방법

Claude Code

Claude Desktop인 경우:

4-2. 첫 번째 테스트: 간단한 코드 생성

테스트 프롬프트

4-3. Code MCP 활용 예시

세션 관리: 대화 연속성 유지하기

세션이란?

세션 목록 확인하기

세션 목록 요청

특정 세션 이어서 작업하기

세션 ID 활용 예시

세션 TTL (Time To Live)

CODEX에 대한 내용 요약(codex mcp가 아닌 codex 기본 특징)

모델 선택 (Model Selection)

사용 가능한 모델 (2025년 11월 2주차 codex 5.1이 출시되어 업데이트 시 다음과 같이 신규 모델을 사용할 수 있다.)

추론 강도 조절 (reasoningEffort)

추론 강도 레벨

대화 컨텍스트 최적화

Codex의 고급 기능 정리(상기 내용과 중복)

1. 모델 선택 및 추론 깊이 조정

2. 세션 컨텍스트 관리

3. 승인 정책 커스터마이징

4. 웹 검색 통합 활용

보안 모범 사례

중요한 보안 고려사항

자주 묻는 질문 ❓

📚 참고 자료

'AI > MCP' 카테고리의 다른 글

당신이 좋아할만한 콘텐츠

티스토리툴바