Codex에서 첫 MCP 서버를 연결하는 방법 (2026)
Codex는 MCP 클라이언트예요. 서버 모드는 없어요. 서버를 추가하는 가장 빠른 방법은 CLI에서 codex mcp add <name> -- <command>를 실행하거나, Desktop 앱의 Settings → MCP servers → Add server, 또는 IDE 확장의 기어 메뉴에서 추가하는 거예요. 설정은 ~/.codex/config.toml의 [mcp_servers.<name>] 아래에 저장돼요. 이 글에서는 OpenAI 공식 문서에 그대로 나오는 중립적인 context7 예제로 세 가지 방법을 모두 살펴볼게요. 제가 밀고 있는 제품이 아니에요.
- 아래의 명령어, 플래그, config.toml 구문은 작성 시점(2026년 8월)에 learn.chatgpt.com/codex/extend/mcp 공식 문서와 교차 확인했어요. Codex CLI는 문서보다 빠르게 바뀌니, 이 내용에 의존하기 전에 codex mcp add --help를 실행해 설치된 버전을 확인하세요.
Codex에서 "MCP 서버 연결"이 의미하는 것
MCP(Model Context Protocol)는 도구마다 일회성 연동을 만드는 대신, 하나의 공유 인터페이스를 통해 에이전트가 외부 도구/데이터를 호출하게 해주는 오픈 표준이에요. Codex에서 "MCP 서버 연결"이란 어떤 명령어(또는 URL)가 서버를 실행하는지, 그리고 실행에 필요한 환경 변수나 토큰을 Codex에 알려주는 걸 뜻해요.
먼저 기억할 점은 이거예요. Codex는 MCP 클라이언트로만 동작해요. 외부 서버를 호출할 뿐, 다른 도구가 호출하는 MCP 서버로 변신하지는 않아요. Codex의 서버 모드를 확인해 주는 문서는 없어요. MCP 개념 자체가 아직 낯설다면(Codex에 국한된 게 아니라), 먼저 MCP가 무엇이고 어떻게 동작하는지부터 읽고 다시 돌아오세요.
서버를 추가하는 세 가지 방법
Codex는 서버를 추가하는 세 가지 경로를 제공하고, 어느 하나가 더 "정답"인 건 아니에요. 워크플로에 맞게 고르세요.
| 방법 | 하는 일 | 적합한 경우 |
|---|---|---|
CLI - codex mcp add | 터미널에서 명령어 하나 | STDIO 서버, 빠름, 컨텍스트 전환 없음 |
| Desktop 앱 | Settings → MCP servers → Add server | STDIO와 원격 HTTP 모두, 수동 TOML 편집 없음 |
| IDE 확장 | 기어 메뉴 → MCP servers → Add server | VS Code/IDE 안에서 작업, 별도 터미널 불필요 |
세 가지 모두 같은 곳, config.toml에 기록돼요. 전체 레퍼런스는 Codex MCP 공식 문서에 있어요. 아래 섹션에서는 CLI와 직접 편집 방법을 자세히 다뤄요. 터미널이 이미 익숙하다면 이 둘이 가장 빨라요.
방법 1 - CLI에서 서버 추가하기 (STDIO)
핵심 명령어의 형태는 하나예요.
codex mcp add <server-name> -- <server-launch-command>OpenAI 공식 문서에 그대로 나오는 실제 예제예요. context7(버전을 인식하는 라이브러리/프레임워크 문서 조회)을 npx로 실행해요.
codex mcp add context7 -- npx -y @upstash/context7-mcp상용 벤더의 서버 대신 이 예제를 쓰는 이유는 중립적이기 때문이에요. 누군가 자기 제품을 첫 실행 예제로 슬쩍 끼워 넣지 않죠. 대부분의 서드파티 Codex-MCP 가이드는 자사 서버를 데모로 쓰는데, 그것도 동작은 하지만 깨끗한 기준선이 아니라 그 제품이 잘 되는 경로를 테스트하는 셈이에요. 서버가 환경 변수(API 키, 토큰 등)를 필요로 하면 --env 플래그를 변수마다 반복해서 추가하세요.
codex mcp add my-server --env API_KEY=xxx --env REGION=us -- npx -y some-mcp-server추가한 뒤에는 두 가지 방법으로 확인하세요.
codex mcp list- 설정된 서버 목록을 보여줘요.- Codex TUI 세션 안에서
/mcp입력 - 그 세션에서 활성화된 서버를 보여줘요.
서버가 나타나지 않으면 거의 항상 --(codex mcp add 자체의 플래그와 서버의 실제 명령어를 구분하는 이중 하이픈)를 잘못 입력한 경우예요. 서버 자체가 고장 났다고 넘겨짚기 전에 그것부터 확인하세요.
방법 2 - config.toml 직접 편집하기
더 명시적으로 제어하고 싶거나, MCP 설정을 프로젝트와 함께 버전 관리하고 싶다면 파일을 직접 편집하세요. STDIO 서버는 이렇게 생겼어요.
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
[mcp_servers.context7.env]
API_KEY = "your-value-here"Streamable HTTP(원격) 서버는 다른 키 세트를 써요. command/args 대신 url을 쓰죠. 예를 들어 Figma 서버라면 이렇게요.
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_TOKEN"
http_headers = { "X-Client" = "codex" }bearer_token_env_var는 실제 토큰을 담은 환경 변수의 이름을 가리켜요. 그 변수는 자기 컴퓨터에서 설정하고, 토큰을 파일에 직접 쓰지는 않아요. ~/.codex/config.toml은 모든 프로젝트에 적용되는 전역 파일이에요. 신뢰됨으로 표시된 프로젝트의 경우, Codex는 프로젝트 디렉터리 안의 .codex/config.toml 파일도 읽어요. 리포지토리별 MCP 설정을 버전 관리에 넣고 싶을 때 유용해요.
원격(Streamable HTTP) 서버 추가하기
현재 HTTP 서버의 확실한 경로는 Desktop Settings나 IDE 확장의 기어 메뉴예요. 이름을 입력하고, STDIO나 HTTP를 고른 뒤, URL을 붙여넣으세요. 이 경로는 문서에 명확히 나와 있어요.
여기서 신중해야 할 부분이에요. 일부 서드파티 가이드(공식 문서가 아님)는 HTTP 서버를 CLI에서 바로 추가하는 codex mcp add <name> --url <url> 같은 구문을 보여줘요. OpenAI 공식 문서는 작성 시점 기준 CLI 구문 섹션에서 이 --url 플래그를 확인해 주지 않아요. 존재한다고 단정하지 마세요. 의존하기 전에 codex mcp add --help를 실행해, 설치된 정확한 CLI 버전이 그것을 지원하는지 확인하세요. 최악의 경우에도 config.toml을 직접 편집하는 방법(위의 방법 2)은 특정 플래그의 존재에 의존하지 않으므로, 설치된 CLI 버전이 무엇을 지원하든 동작해요.
몇 가지 미세 조정 키는 STDIO와 HTTP 모두에 적용되고, 같은 [mcp_servers.<name>] 블록 안에서 선언해요. startup_timeout_sec, tool_timeout_sec, enabled(서버 켜기/끄기), 그리고 enabled_tools/disabled_tools(그 서버가 노출할 수 있는 도구를 허용 목록/차단 목록으로 지정)예요.
Codex와 Claude Code - MCP 설정은 같지 않아요
이 사이트는 Claude Code와 Codex를 모두 다루니 분명히 말할게요. 한 도구의 습관을 다른 도구로 그대로 가져오지 마세요.
| 항목 | Codex | Claude Code |
|---|---|---|
| 설정 형식 | TOML - config.toml | JSON - .mcp.json |
| 추가 명령어 (STDIO) | codex mcp add <name> -- <command> | claude mcp add <name> -- <command> |
| 추가 명령어 (HTTP) | 확인된 CLI 플래그 없음 - Desktop/IDE 설정 사용 | claude mcp add --transport http <name> <url> -H "Authorization: Bearer TOKEN" |
| 스코프 | 전역(~/.codex/config.toml)과 선택적 프로젝트 범위 파일, 명시적 스코프 플래그 없음 | 명시적 -s 플래그: local(기본값) / project / user |
같은 실제 서버(GitHub)를 반대쪽에서 어떻게 연결하는지 보고 싶나요? GitHub MCP 서버를 Claude Code에 연결하기를 읽어보세요. 이론이 아니라 도구를 넘나드는 구체적인 예시예요.
제대로 됐는지 확인하기
가장 빠른 확인 방법은 TUI에서 /mcp를 입력해 현재 세션에서 활성화된 서버를 보는 거예요. 가장 흔한 실패 유형은 이래요.
- 환경 변수 누락 - 서버가
API_KEY를 필요로 하는데--env나 TOML의.env블록을 빠뜨린 경우. - 잘못된
command/args- 패키지 이름 오타, 또는npx로 실행할 때-y누락. - HTTP 토큰 미설정 -
bearer_token_env_var가 가리키는 변수가 컴퓨터에 설정되지 않아, 구문이 맞아도 서버 인증이 실패하는 경우.
경계를 분명히 하는 한마디. MCP 서버는 Codex에 호출할 새 도구를 줘요(Figma 파일 읽기, 데이터베이스 조회 등). AgentKit의 스킬 레이어(agentkit.best, 유료 키트 - OpenAI의 AgentKit과는 다름)는 그 위에 얹히는 별개의 레이어로, 미리 만들어진 워크플로를 패키징해요. MCP 서버 연결과는 다른 것이고, 하나를 쓰기 위해 다른 하나가 필요하지도 않아요.
자주 묻는 질문 (FAQ)
Codex는 MCP 서버인가요, 아니면 클라이언트일 뿐인가요?
클라이언트일 뿐이에요. Codex는 더 많은 도구/데이터를 얻기 위해 외부 MCP 서버를 호출해요. Codex 자체가 다른 도구들이 호출하는 MCP 서버로 동작한다는 걸 확인해 주는 문서는 없어요.
MCP 서버를 추가하는 정확한 명령어는 무엇인가요?
codex mcp add <server-name> -- <launch-command>, 예를 들어 codex mcp add context7 -- npx -y @upstash/context7-mcp예요. 환경 변수는 --env KEY=VALUE를 변수마다 반복해서 추가하세요.
Codex는 MCP 설정을 어디에 저장하나요?
~/.codex/config.toml(전역, 모든 프로젝트에 적용)의 [mcp_servers.<name>] 아래예요. 신뢰된 프로젝트의 경우, Codex는 프로젝트 디렉터리 안의 .codex/config.toml 파일도 읽어요.
STDIO와 Streamable HTTP의 차이는 무엇인가요?
STDIO는 command/args를 통해 서버를 로컬 프로세스로 실행해요(예: npx로 시작). Streamable HTTP는 url로 원격 서버를 호출하고, bearer_token_env_var나 커스텀 헤더로 인증해요. 로컬에 설치할 게 없어요.
원격 서버를 CLI에서 바로 추가할 수 있나요?
확인되지 않았어요. 일부 서드파티 가이드는 --url 플래그를 보여주지만, Codex 공식 문서는 작성 시점 기준 그것을 명시하지 않아요. 현재 확인된 경로는 Desktop Settings나 IDE 기어 메뉴예요. 사용하는 CLI가 지원하는지 확인하려면 codex mcp add --help를 실행하세요.
Codex의 MCP 설정은 Claude Code와 같나요?
아니요. Codex는 TOML(config.toml)을 쓰고 명시적 스코프 플래그가 없어요. Claude Code는 JSON(.mcp.json)을 쓰고 명시적 -s local/project/user 플래그가 있어요. 바탕이 되는 MCP 표준은 같지만 설정 방식이 달라요. 한 도구의 구문을 다른 도구로 그대로 복사하지 마세요.
결론
빠른 STDIO 추가에는 CLI를, 원격 HTTP 서버가 필요한데 CLI가 그 플래그를 지원하는지 아직 모를 때는 Desktop/IDE를, 프로젝트별 설정을 버전 관리에 두고 싶을 때는 config.toml을 직접 편집하세요. MCP를 넘어 Codex를 확장하고 싶나요? Codex Skills (SKILL.md)를 보세요. MCP를 대체하는 게 아니라 나란히 가는 확장 경로예요. Codex 자체가 처음인가요? 먼저 OpenAI Codex가 무엇인지부터 시작하세요.