서론

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와의 차이점을 파악하면서, 용도에 따라 적절히 구분하여 사용하면 좋을 것 같습니다.

Insights

Codex의 MCP 도입 방법 정리 — config.toml / Claude Code와의 비교 (2026년 6월 시점)

요약

핵심 포인트

서론