codex mcp 설정 — 서버 추가와 프로젝트 적용
Codex CLI에 MCP 서버를 붙이는 명령은 codex mcp add <이름> -- <실행명령> 한 줄입니다. 주소로 접속하는 원격 서버라면 codex mcp add <이름> --url <주소>를 씁니다. 이 명령이 하는 일은 ~/.codex/config.toml에 [mcp_servers.이름] 항목을 적어 넣는 것뿐이라, 설정 파일을 직접 손으로 고쳐도 결과는 똑같습니다. 아래는 codex-cli 0.151.0을 윈도우에 직접 깔아 명령을 하나씩 돌려 본 결과입니다.
1. codex mcp add — 서버 추가 명령
MCP 서버는 두 종류뿐입니다. 내 컴퓨터에서 프로그램으로 띄우는 stdio 서버, 그리고 주소로 접속하는 Streamable HTTP 서버입니다. 명령이 갈리는 지점은 --url이 있느냐 없느냐입니다.
# stdio 서버 — `--` 뒤가 서버를 띄우는 명령
codex mcp add fs -- npx -y @modelcontextprotocol/server-filesystem D:/project/myapp
# Streamable HTTP 서버 — 주소를 준다
codex mcp add ctx7 --url https://mcp.context7.com/mcp
# 환경변수를 같이 넘길 때 (stdio 전용)
codex mcp add envtest --env API_KEY=abc123 --env MODE=dev -- node server.js성공하면 Added global MCP server 'fs'. 한 줄이 뜹니다. 여기서 global이라는 단어를 눈여겨보세요. codex mcp add는 어느 폴더에서 실행하든 항상 사용자 전역 설정에만 씁니다. 프로젝트마다 다르게 두는 방법은 4번에서 따로 다룹니다.
codex mcp add는 명령이 실제로 존재하는지 검사하지 않습니다. 없는 명령을 적어도 Added global MCP server 'bad'.라고 그대로 성공합니다(직접 확인). 오타는 나중에 Codex를 띄웠을 때야 드러납니다.
2. 추가하면 config.toml에 뭐가 써지나
위 세 명령을 차례로 돌린 뒤 ~/.codex/config.toml을 열면 이렇게 되어 있습니다. 설정 파일이 없던 상태였는데 첫 add 때 파일이 새로 만들어집니다.
[mcp_servers.fs]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "D:/project/myapp"]
[mcp_servers.ctx7]
url = "https://mcp.context7.com/mcp"
[mcp_servers.envtest]
command = "node"
args = ["server.js"]
[mcp_servers.envtest.env]
API_KEY = "abc123"
MODE = "dev"규칙이 눈에 보입니다. 서버 하나가 [mcp_servers.이름] 표 하나이고, stdio면 command·args, HTTP면 url이 들어갑니다. 환경변수는 [mcp_servers.이름.env]라는 별도 표로 빠집니다. 이 구조를 알면 add 명령을 외울 필요 없이 파일에 바로 적어도 됩니다.
참고로 클로드 코드 mcp 연결은 JSON(.mcp.json)을, gemini cli mcp 설정은 settings.json을 쓰는데, Codex만 TOML입니다. 형식만 다를 뿐 "이름 · 실행명령 · 인자 · 환경변수"를 적는다는 뼈대는 셋이 같습니다.
3. codex mcp list 읽는 법 — Status는 연결 상태가 아니다
등록한 서버는 codex mcp list로 봅니다. 출력이 표 두 개로 나뉘어 나오는데, 위가 stdio, 아래가 HTTP 서버입니다.
Name Command Args Env Cwd Status Auth
envtest node server.js API_KEY=*****, MODE=***** - disabled Unsupported
fs npx -y @modelcontextprotocol/... - - enabled Unsupported
Name Url Bearer Token Env Var Status Auth
ctx7 https://mcp.context7.com/mcp CONTEXT7_API_KEY enabled Bearer token여기서 착각하기 쉬운 게 Status 열입니다. 이건 연결 성공 여부가 아니라 설정에서 켜져 있는지를 보여줍니다. 없는 명령을 적어 둔 서버도 enabled로 뜹니다. 실제로 서버가 붙었는지는 codex를 띄워 TUI 안에서 /mcp를 쳐야 보입니다.
Env 열의 값이 *****로 가려지는 것도 확인했습니다. API 키를 넣어 둬도 목록에서는 새지 않습니다. 값까지 그대로 보고 싶으면 codex mcp get <이름>을 쓰고, 스크립트에서 다루려면 codex mcp list --json이 편합니다.
| 명령 | 하는 일 / 실제 출력 |
|---|---|
codex mcp list |
등록된 서버를 stdio·HTTP 표로 나눠 출력 |
codex mcp list --json |
같은 내용을 JSON으로 (스크립트용) |
codex mcp get <이름> |
서버 하나 상세 + 지우는 명령까지 알려 줌 |
codex mcp remove <이름> |
Removed global MCP server 'bad'. / 없으면 No MCP server named 'nosuch' found. |
codex mcp login <이름> |
OAuth 로그인. stdio 서버에 쓰면 OAuth login is only supported for streamable HTTP servers. |
서버를 지우지 않고 잠깐만 꺼 두려면 설정에 enabled = false 한 줄을 넣으면 됩니다. 이때 codex mcp get은 상세를 감추고 envtest (disabled) 한 줄만 찍습니다.
4. 프로젝트마다 다른 MCP를 쓰려면 — 신뢰 등록이 먼저다
공식 문서에 따르면 Codex는 사용자 설정(~/.codex/config.toml) 말고 프로젝트 안의 .codex/config.toml도 읽습니다. 다만 조건이 붙습니다 — 신뢰한 프로젝트에서만입니다.
이 조건이 실제로 어떻게 걸리는지 확인해 봤습니다. 빈 폴더에 .codex/config.toml을 만들고 서버 하나를 적은 뒤 그 폴더에서 codex mcp list를 돌리면, 그 서버는 목록에 나오지 않습니다. 더 곤란한 건 아무 경고도 없다는 점입니다. 파일에 일부러 깨진 TOML을 넣어 봐도 에러 한 줄 없이 그냥 지나갑니다. 즉 파일이 읽히지도 않은 것이고, 겉으로는 "설정을 잘못 썼나?"와 구분이 안 됩니다.
사용자 설정에 아래처럼 신뢰 항목을 넣자 그제야 프로젝트 서버가 목록에 나타났습니다.
# ~/.codex/config.toml
[projects.'C:\Users\사용자\project\myapp']
trust_level = "trusted"codex를 처음 띄웠을 때 나오는 "이 폴더를 신뢰하겠습니까" 물음에 예라고 답하면 자동으로 들어갑니다. 프로젝트 설정이 안 먹으면 설정 문법보다 신뢰 등록부터 의심하세요.
"C:\Users\..."라고 쓰면 TOML이 \U를 유니코드 escape로 읽어 too few unicode value digits, expected unicode hexadecimal value 에러를 내고 Codex가 아예 시작되지 않습니다. 작은따옴표(TOML 리터럴 문자열)를 쓰거나 \\로 두 번 적어야 합니다.
5. 자주 쓰는 추가 옵션
명령으로는 못 넣고 config.toml에 직접 적어야 하는 값들입니다. 공식 문서에 정리된 기본값과 함께 자주 쓰는 것만 추렸습니다.
| 키 | 설명 | 기본값 |
|---|---|---|
startup_timeout_sec |
서버가 켜질 때까지 기다리는 시간(초) | 10 |
tool_timeout_sec |
도구 하나를 실행할 때 기다리는 시간(초) | 60 |
enabled |
false면 지우지 않고 꺼 둠 |
true |
required |
true면 이 서버가 안 뜰 때 Codex 시작 자체를 실패시킴 |
— |
enabled_tools / disabled_tools |
쓸 도구만 허용 / 뺄 도구 차단(허용 목록 다음에 적용) | — |
cwd |
stdio 서버를 띄울 작업 폴더 | — |
서버가 도구를 20개씩 물고 오면 프롬프트가 무거워집니다. 그럴 때 enabled_tools로 실제 쓰는 것만 남기는 편이 낫습니다. 서버가 파일을 건드리는 게 걱정된다면 codex 샌드박스 설정과 같이 보세요 — MCP 도구도 결국 Codex의 승인·샌드박스 정책 아래에서 돕니다.
6. API 키가 필요한 원격 서버 붙이기
토큰이 필요한 HTTP 서버는 키를 설정 파일에 직접 적지 말고 환경변수 이름만 가리키게 하는 방식을 씁니다.
codex mcp add ctx7 --url https://mcp.context7.com/mcp \
--bearer-token-env-var CONTEXT7_API_KEY[mcp_servers.ctx7]
url = "https://mcp.context7.com/mcp"
bearer_token_env_var = "CONTEXT7_API_KEY"이렇게 두면 Codex가 CONTEXT7_API_KEY 값을 읽어 Authorization: Bearer … 헤더로 보냅니다. 설정 파일에는 키가 남지 않으니 저장소에 올려도 안전합니다. OAuth를 쓰는 서버라면 codex mcp login <이름>으로 따로 로그인하고, 고정 헤더가 필요하면 http_headers를 씁니다.
자주 묻는 질문 (FAQ)
Q. 클로드 코드에서 쓰던 MCP 설정을 그대로 가져올 수 있나요?
파일을 복사해 붙이는 방식으로는 안 됩니다. 클로드 코드는 JSON, Codex는 TOML이라 형식이 다릅니다. 다만 적는 내용은 같아서, command·args·env 세 값만 옮겨 codex mcp add로 다시 등록하면 됩니다.
Q. codex mcp add에 프로젝트 범위 옵션은 없나요?
0.151.0 기준 codex mcp add --help에 범위(scope) 옵션이 없습니다. 항상 전역에 씁니다. 프로젝트별로 두려면 .codex/config.toml을 손으로 만들고, 그 폴더를 신뢰 등록해야 합니다(4번).
Q. 서버를 추가했는데 Codex가 도구를 못 씁니다.
codex mcp list의 enabled는 연결됐다는 뜻이 아닙니다. codex를 띄워 /mcp로 실제 붙었는지 보고, 안 붙었다면 ① 명령 오타, ② 실행 파일 경로(전역 설치 안 된 npx 패키지 등), ③ startup_timeout_sec(기본 10초) 초과를 차례로 의심하세요.
Q. ChatGPT 데스크톱 앱이나 IDE 확장에서도 같은 설정이 쓰이나요?
공식 문서상 데스크톱 앱·CLI·IDE 확장이 같은 Codex 설정 계층을 공유합니다. 한 번 등록하면 클라이언트를 바꿔도 다시 설정할 필요가 없습니다.
마무리
정리하면 세 줄입니다. ① 추가는 codex mcp add <이름> -- <명령>(원격은 --url), ② 결과는 ~/.codex/config.toml의 [mcp_servers.이름], ③ 프로젝트별로 두려면 .codex/config.toml + 신뢰 등록. 그리고 codex mcp list의 enabled를 연결 성공으로 읽지 마세요 — 실제 확인은 TUI의 /mcp입니다. Codex는 갱신이 잦으니 codex --version으로 버전을 먼저 확인하고, 옵션은 codex mcp --help로 대조하는 습관을 들이면 좋습니다.
📚 참고 출처 (2026년 8월 30일 확인 · codex-cli 0.151.0에서 직접 실행)
· OpenAI Codex 공식 문서 — Model Context Protocol
· OpenAI Codex 공식 문서 — Config basics
COMMENTS