서론

Claude Code를 위한 MCP 설정 방법을 정리한 전편에 이어, 이번에는 Codex에서의 MCP 도입 방법을 정리하면서 config.toml의 기술 방식 및 Claude Code와의 차이점에 대해서도 다루어 보고자 합니다.

Codex의 MCP 기본 아키텍처

설정 파일의 위치와 스코프 (Scope)

Codex의 MCP 설정은 config.toml에 집약되어 있으며, 주로 다음 두 가지 스코프(Scope)로 관리합니다.

스코프	경로	대상
사용자 / 글로벌	~/.codex/config.toml	모든 Codex 세션에 적용
프로젝트	.codex/config.toml	해당 프로젝트 하위에서만. 신뢰된 프로젝트에서만 읽힘

중요한 점은, Codex CLI와 IDE 확장(Extension)은 동일한 설정 레이어를 참조한다는 것입니다. CLI 측에서 MCP 서버를 추가하면 IDE 확장 측에서도 사용할 수 있으며, IDE 확장에서 config.toml을 열어 편집한 내용도 CLI 측에 반영됩니다.

설정 우선순위는 대체로 다음과 같습니다. 상위일수록 우선순위가 높습니다.

• CLI 플래그 / --config를 통한 일시적 덮어쓰기
• 프로젝트 config (.codex/config.toml, 신뢰된 프로젝트만. 현재 위치와 가까운 것이 우선)
• 프로필 config (--profile로 선택하는 ~/.codex/<profile-name>.config.toml)
• 사용자 config (~/.codex/config.toml)
• 시스템 config (Unix에서는 /etc/codex/config.toml이 존재하는 경우)
• 내장 기본값

MCP 서버의 설정 방법

Codex에서 MCP 서버를 설정하는 방법은 두 가지가 있습니다.

• codex mcp 명령어로 추가·삭제한다
• config.toml을 직접 편집한다

Codex가 다루는 주요 MCP 트랜스포트(Transport)는 다음 두 종류입니다.

트랜스포트	방식	인증·시크릿(Secret) 전달 방식
stdio	로컬 프로세스를 자식 프로세스로 실행하여 표준 입출력으로 통신	env / env_vars를 통해 자식 프로세스에 환경 변수를 전달
Streamable HTTP	HTTPS 엔드포인트로 접속	OAuth, Bearer Token, HTTP 헤더

stdio 서버의 설정

로컬에서 실행되는 MCP 서버를 stdio를 통해 사용할 경우의 설정 예시입니다.

CLI 명령어로 추가하기

# Context7(개발자용 문서 MCP)을 추가하는 예시
codex mcp add context7 -- npx -y @upstash/context7-mcp
# 설정 확인
...

config.toml에 직접 작성하기

# ~/.codex/config.toml
[mcp_servers.context7]
command = "npx"
...

command는 문자열이며, args는 배열입니다.

stdio 서버에 환경 변수 전달하기

stdio 서버가 외부 API를 호출하는 경우, API 토큰을 환경 변수로 전달하는 경우가 있습니다.

Codex에서는 주로 두 가지 방법이 있습니다.

# 기존 로컬 환경 변수를 허용하여 자식 프로세스에 전달
[mcp_servers.internal_tools]
command = "node"
...

또는, 고정값을 해당 서버의 환경 변수로 설정합니다.

[mcp_servers.internal_tools]
command = "node"
args = ["./scripts/mcp-server.js"]
...

Streamable HTTP 서버의 설정

Remote MCP 서버에 접속할 경우에는 url을 지정합니다.

[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"

CLI에서 추가할 경우에는 --url을 사용합니다.

codex mcp add linear --url https://mcp.linear.app/mcp
codex mcp login linear

--url을 붙이면, stdio 실행 명령어가 아닌 Streamable HTTP 서버로 등록됩니다.

Bearer Token을 사용하는 경우

Bearer Token 인증을 지원하는 Remote MCP 서버에서는 토큰을 환경 변수에서 읽어옵니다.

# Stripe MCP를 Bearer Token으로 사용하는 예
# STRIPE_API_KEY에는 restricted API key를 설정해 둡니다
codex mcp add stripe \
...

config.toml에 직접 작성하는 경우에는 bearer_token_env_var를 사용합니다.

# Stripe — 결제·청구 관련 작업
[mcp_servers.stripe]
url = "https://mcp.stripe.com"
...

HTTP 헤더를 사용하는 경우

고정 헤더는 http_headers를, 환경 변수에서 헤더 값을 읽는 경우에는 env_http_headers를 사용할 수 있습니다.

[mcp_servers.example]
url = "https://mcp.example.com/mcp"
http_headers = { "X-Client" = "codex" }
...

단, 일반적인 Bearer Token이라면 bearer_token_env_var를 사용하는 것이 의도가 더 명확합니다.

OAuth를 사용한 Remote MCP 연동

OAuth 플로우의 기본

Codex는 Streamable HTTP MCP 서버의 OAuth 인증을 지원합니다.

OAuth 지원 서버를 추가했다면, 최초 1회만 codex mcp login <server-name>을 실행합니다.

# OAuth 지원 서버 로그인
codex mcp login <server-name>
# 인증 정보 삭제
...

OAuth 지원 서버의 최소 구성은 기본적으로 url뿐입니다.

[mcp_servers.notion]
url = "https://mcp.notion.com/mcp"
[mcp_servers.figma]
...

등록 후에 로그인합니다.

codex mcp login notion
codex mcp login figma
codex mcp login linear

OAuth 스코프(Scope)를 지정하기

서버 측에서 scopes_supported를 통지하는 경우, Codex는 서버가 통지한 스코프를 우선합니다. 필요에 따라 config.toml에 scopes를 작성할 수도 있습니다.

[mcp_servers.atlassian]
url = "https://mcp.atlassian.com/v1/mcp/authv2"
scopes = ["read:jira-work", "write:jira-work", "read:confluence-content.all"]

CLI 로그인 시에 지정할 수도 있습니다.

codex mcp login atlassian --scopes read:jira-work,write:jira-work,read:confluence-content.all

OAuth의 resource 파라미터가 필요한 서버에서는 oauth_resource를 사용합니다.

[mcp_servers.example]
url = "https://mcp.example.com/mcp"
oauth_resource = "https://api.example.com"

OAuth 콜백 URL 커스터마이징

Devbox나 Remote 환경 등, localhost로의 콜백을 사용하기 어려운 경우에는 최상위 레벨(top-level)에 다음 설정을 작성할 수 있습니다.

# ~/.codex/config.toml의 최상위 레벨(top-level)에 설정
# 고정 포트가 필요한 OAuth 프로바이더(Provider)용
mcp_oauth_callback_port = 54321
...

대표적인 OAuth 대응 MCP 서버 예시

# Notion
[mcp_servers.notion]
url = "https://mcp.notion.com/mcp"
...

codex mcp login notion
codex mcp login figma
codex mcp login linear
...

Codex를 MCP 서버로 사용하기

Codex는 MCP 클라이언트(Client)로서 외부 서버에 접속할 수 있을 뿐만 아니라, Codex 자체를 MCP 서버(Server)로서 다른 에이전트(Agent)나 도구(Tool)에 제공할 수도 있습니다.

# Codex를 MCP 서버 모드로 실행 (stdio)
codex mcp-server

이 모드에서는 Claude Desktop, Claude Code, OpenAI Agents SDK, 독자적인 오케스트레이터(Orchestrator) 등의 MCP 클라이언트로부터 Codex를 호출할 수 있습니다.

공개되는 도구

codex mcp-server는 주로 다음 두 가지 도구를 공개합니다.

도구 이름	역할
codex()	새로운 Codex 세션을 시작하여 태스크(Task)를 실행
codex-reply()	기존 Codex 세션을 지속하여 추가 지시를 전달

codex-reply()를 사용함으로써, 오케스트레이터 측에서 Codex 세션을 상태 유지(Stateful)가 가능한 작업 단위로 다룰 수 있습니다. 한 번의 지시로 완결되지 않는 다단계 구현 태스크를 대화를 지속하며 위임할 수 있습니다.

Claude Code에서 Codex 호출하기

수동으로 codex mcp-server를 계속 실행해 둘 필요는 기본적으로 없습니다.

Claude Code와 같은 MCP 클라이언트 측에 stdio 서버로 등록해 두면, 세션 시작 시 자식 프로세스(Child Process)로서 자동으로 실행됩니다.

Claude Code의 프로젝트 설정인 .mcp.json에 작성한다면, 예를 들어 다음과 같은 형태가 됩니다.

{
"mcpServers": {
"codex-worker": {
...

CLI에서 추가할 경우에는 stdio 서버로서 codex mcp-server를 등록합니다.

claude mcp add codex-worker -- codex mcp-server

stdio 서버는 "URL에 접속하는" 것이 아니라, "명령어를 실행하여 표준 입출력(Standard I/O)을 통신 경로로 사용하는" 방식입니다. 따라서 Claude Code 세션이 종료되면, 통상적으로 자식 프로세스인 codex mcp-server도 함께 종료됩니다.

실전 유스케이스 (Use Case)

Claude Code에서 호출하는 MCP 브로커(Broker) 구성

Codex 측에 Backlog, Sentry, Linear 등 여러 MCP를 설정해 두고, Claude Code는 이를 직접 보유하지 않고 Codex를 경유하여 질의하는 구성을 취할 수도 있습니다.

Claude Code (사고·판단·설계·구현에 집중)
↓ codex() 도구를 호출
Codex (MCP의 창구 역할 = 브로커)
...

Claude Code 측의 컨텍스트(Context)에는 Codex로부터 반환된 요약(Summary) 정보만 들어가기 때문에, 외부 서비스의 로우 데이터(Raw Data)나 MCP의 도구 정의가 Claude Code의 컨텍스트를 압박하기 어렵습니다.

Claude Code도 MCP 서버로 사용할 수 있음

"MCP 서버로 공개할 수 있는 것은 Codex 고유의 기능"이라고 설명되는 경우가 있지만, 현재의 Claude Code에도 claude mcp serve가 있습니다 (사실 조사하기 전까지는 몰랐습니다... w)

claude mcp serve

하지만 Codex와 달리 Claude Code의 경우, 추론 능력을 이용할 수 있는 것도 아니며, Codex처럼 다른 MCP를 간접적으로 이용할 수 있는 것도 아닙니다. 간단히 말하면 Claude Code의 "손발"(파일 조작·셸 실행 도구)을 다른 MCP 클라이언트에게 도구로서 빌려주는 것이며, 주요 이용 용도는 Claude Desktop이 됩니다. Claude Desktop에 파일 편집·명령 실행 기능을 사후에 추가할 수 있게 됩니다.

"Codex에서 Claude 측의 Backlog 등의 MCP를 간접 이용하고 싶다"라거나 "Codex에서 태스크를 통째로 Claude에게 위임하여 자율적으로 수행하게 하고 싶다"는 경우, claude mcp serve로는 불가능한 것으로 보입니다.

MCP 서버 방식과 Codex 플러그인(codex-plugin-cc)의 차이

Claude Code에서 Codex를 사용하는 방법으로, 본 기사에서 해설한 MCP 서버 방식과는 별개로 OpenAI가 제공하는 **Codex 플러그인(codex-plugin-cc)**도 있습니다.

MCP 서버 방식 (본 기사)	Codex 플러그인 (codex-plugin-cc)
연계 방식	Claude Code 등의 MCP 클라이언트로부터 codex mcp-server를 기동
주요 진입점	codex() / codex-reply()
실행 모델	MCP 도구로서 직접 호출. 세션 지속에 적합
범용성	임의의 MCP 클라이언트나 자체 제작 오케스트레이터에서 사용 가능
설정(Setup)	.mcp.json이나 MCP 클라이언트 측의 설정이 필요
적합한 케이스	멀티 에이전트 구성, 외부 MCP 브로커, Agents SDK 연계

두 방식 모두 Codex 측의 ~/.codex/config.toml에 설정한 MCP 서버를 활용할 수 있습니다. 차이점은 연계의 깊이와 진입점입니다.

• Codex와 대화를 지속하면서 여러 단계의 작업을 진행하고 싶다 → MCP 서버 방식
• Claude Code 내부에서 간편하게 Codex 리뷰나 태스크 위임을 호출하고 싶다 → Codex 플러그인

Claude Code와의 비교

상급자를 위해, 두 도구의 MCP 설정을 횡단적으로 비교합니다.

설정 파일

비교 항목	Claude Code	Codex
주요 설정 형식	.mcp.json / ~/.claude.json (JSON)	config.toml (TOML)
글로벌 설정	~/.claude.json의 user scope	~/.codex/config.toml
프로젝트 설정	.mcp.json (리포지토리 루트)	.codex/config.toml (trust 필수)
CLI·IDE 설정 공유	Claude Code의 스코프 설정으로 관리	CLI와 IDE 확장이 동일한 설정 레이어를 공유
스코프	local / project / user	user / project + profile / system 등

트랜스포트(Transport) 지원

트랜스포트	Claude Code	Codex
stdio	✅	✅
...

인증

인증 방식	Claude Code	Codex
환경 변수 (stdio)	✅	✅
Bearer Token	✅	✅ bearer_token_env_var
OAuth	✅	✅ codex mcp login <name>
OAuth 콜백 조정	클라이언트 측 구현에 의존	mcp_oauth_callback_port / mcp_oauth_callback_url

MCP 서버 기능

기능	Claude Code	Codex
MCP 서버로 공개	✅ claude mcp serve	✅ codex mcp-server
공개되는 주요 경험	Claude Code의 도구 모음을 MCP를 통해 이용	codex() / codex-reply()를 통해 Codex 세션을 작업 단위로 호출
프로젝트 신뢰 모델	스코프 (Scope)로 제어	projects.<path>.trust_level로 제어
IDE 설정의 일원성	Claude Code의 설정 스코프를 따름	CLI 및 IDE 확장이 공통의 config.toml을 참조
프로젝트 지시 파일	CLAUDE.md	AGENTS.md

설계 사상의 차이

Claude Code의 MCP 설계는 local, project, user 스코프를 사용한 관리가 중심입니다. 팀과 공유하고 싶은 MCP는 .mcp.json에 두고, 개인 설정은 ~/.claude.json에 분리하는 방식이 자연스럽습니다.

반면 Codex는 config.toml을 중심으로 CLI와 IDE 확장을 일원 관리하는 설계입니다. 프로젝트 설정도 .codex/config.toml에 둘 수 있지만, 신뢰된 프로젝트에서만 읽어옵니다. 또한, Codex 자신을 MCP 서버로서 다른 오케스트레이터(Orchestrator)에서 호출할 수 있기 때문에 멀티 에이전트 (Multi-agent) 구성을 만들기 쉽다는 것이 특징입니다.

팀 개발에서의 설정 예시

프로젝트에 Codex의 MCP 설정을 포함하는 경우의 구성 예시입니다.

project/
├── .codex/
│   └── config.toml # 팀 공통 MCP 설정 (git 관리)
...

.codex/config.toml에는 시크릿(Secret) 값이 아니라, 환경 변수 이름이나 OAuth 대응 URL을 작성합니다.

# .codex/config.toml (git 관리하는 팀 공통 설정)
# GitHub Remote MCP (PAT를 사용하는 경우)
[mcp_servers.github]
...

최초 셋업 시에는 다음과 같은 형태가 됩니다.

cd project/
# 최초 실행 시 trust를 요청하는 프롬프트가 표시되면 내용을 확인하고 승인
codex
...

trust 승인을 수행하면, 사용자 측의 ~/.codex/config.toml에 다음과 같은 설정이 추가됩니다. 수동으로 작성할 수도 있습니다.

[projects."/path/to/project"]
trust_level = "trusted"

보안상의 주의점

Codex 고유의 리스크: trusted project

프로젝트의 .codex/config.toml이 유효해지는 것은 trust한 디렉토리뿐이지만, 한 번 trust하면 이후에는 자동으로 읽어옵니다.

• OSS 컨트리뷰션이나 외부 리포지토리를 클론했을 때, codex trust나 최초 trust 승인 전에 .codex/config.toml의 내용을 확인한다.
• 알 수 없는 .codex/config.toml이 포함된 리포지토리에 대한 trust는 신중하게 수행한다.
• 프로젝트 config에서 실행되는 stdio MCP 서버의 command / args / cwd를 반드시 확인한다.

툴 포이즈닝 (Tool Poisoning) · 프롬프트 인젝션 (Prompt Injection)

MCP 서버의 툴 설명문이나 외부 서비스 유래 데이터에 악의적인 명령이 매립될 리스크는 Codex에서도 마찬가지입니다. Codex가 다루는 코드베이스에는 기밀 정보가 포함되는 경우가 많기 때문에 더욱 주의가 필요합니다.

• 사용하는 MCP 서버는 공식적이고 신뢰할 수 있는 소스로 한정한다
• 커뮤니티 제작 서버는 소스 코드를 확인한 후 도입한다
• codex mcp get <name> --json 명령으로 실제로 로드되고 있는 설정을 정기적으로 확인한다
• 불필요한 MCP 서버는 enabled = false로 무효화하거나, codex mcp remove <name>으로 삭제한다
• 권한이 넓은 토큰이 아니라, 읽기 전용(read-only)이나 제한된 키(restricted key) 등 최소 권한의 인증 정보를 사용한다

HTTP MCP의 인증 정보

Streamable HTTP MCP에서는 OAuth 토큰이나 Bearer Token이 외부 서비스에 대한 액세스 권한이 됩니다.

[mcp_servers.stripe]
url = "https://mcp.stripe.com"
bearer_token_env_var = "STRIPE_API_KEY"

이러한 설정에서는 STRIPE_API_KEY의 값을 어디에서 관리할지가 중요합니다.

• .env.local은 .gitignore에 포함시킨다
• CI / devbox에서는 시크릿 매니저(Secret Manager)를 사용한다
• API 키는 용도별로 분리하고, 정기적으로 로테이션(rotation)한다
• 운영 권한(production) 키를 로컬 검증용 MCP에 유용하지 않는다

마치며

Codex의 MCP는 CLI, IDE, 기타 에이전트와의 연동을 일원적으로 다룰 수 있다는 점이 큰 특징입니다.

Claude Code와의 차이점을 파악하면서, 용도에 따라 적절히 구분하여 사용하면 좋을 것 같습니다.

참고 링크

Discussion