핵심 요약
- Codex는 ~/.codex/config.toml(전역)이나 .codex/config.toml(프로젝트)에서 MCP 서버를 읽습니다. 각 항목은 [mcp_servers.<name>] 테이블로, 로컬 stdio 서버에는 command/args, 원격에는 url을 적습니다.
- codex mcp add context7 -- npx -y @upstash/context7-mcp는 파일을 건드리지 않고 stdio 서버를 설치합니다; codex mcp add <name> --url https://mcp.example.com/mcp는 원격을 등록합니다.
- 원격 서버는 첫 연결 때 브라우저에서 인증하고(Codex가 Detected OAuth support를 출력하고 동의 화면을 엽니다), 이후 codex mcp login <name>으로도 가능합니다.
- 검증은 TUI 안의 /mcp나 셸의 codex mcp list로. Codex 0.160.1은 추가로, 원격 env 변수와 함께 원격 stdio 서버를 띄울 때 SYSTEMROOT·TEMP·TMP를 보존합니다.
OpenAI Codex + MCP: How to Install MCP Servers in Codex (Step by Step)
채널: Nathan Sebhastian8:48
OpenAI Codex Tutorial #9 - MCP Servers
채널: Net Ninja6:46
How to Add MCP Servers to OpenAI Codex CLI
채널: Snyk9:14
Connect Codex to an MCP server — official documentation
공식 문서: developers.openai.com/codex
이 페이지의 모든 명령, 파일 경로, 설정 키는 공식 Codex MCP 문서와 대조해 검증했습니다. 위 영상들이 시각·사실 자료이며, OAuth 동의 화면과 데스크톱 앱의 MCP 메뉴도 여기에 포함됩니다.
스크린샷의 권리는 각 제작자에게 있으며, 해당 타임스탬프로 바로 연결됩니다. 얼굴이 나온 장면은 사용하지 않았습니다.
Codex에 MCP 서버 추가하기, 단계별로
파트 1 — 첫 번째 stdio 서버
- 1
공식 MCP 문서에서 서버 고르기
developers.openai.com/codex/mcp을 여세요 — Codex 자체 문서에 최신 명령 문법이 있고, CLI와 IDE 확장이 이 설정을 공유합니다. 문서에는 먼저 시도할 만한 ready-made 서버가 나열됩니다: 실시간 라이브러리 문서를 위한 Context7, Figma, GitHub 등. MCP 서버는 수백 개입니다; 첫 테스트는 Context7 같은 읽기 전용으로 고르세요.
공식 Connect Codex to an MCP server 페이지 — codex mcp add 문법과 바로 복사할 수 있는 Context7 예제.0:20부터 시청 - 2
codex mcp add로 설치
예제를 복사해 터미널에서 실행하세요: codex mcp add context7 -- npx -y @upstash/context7-mcp. 이중 대시 뒤가 서버 프로세스를 띄우는 명령입니다. Codex는 "Added global MCP server 'context7'"라고 답합니다 — global은 사용자 수준 설정에 들어갔고 모든 프로젝트에서 쓸 수 있다는 뜻.
명령 하나, 파일 편집 없이: CLI가 전역 설정에 추가됐음을 확인해 줍니다.0:45부터 시청 - 3
CLI가 config.toml에 쓴 것 보기
codex mcp add는 ~/.codex/config.toml의 생성기에 불과합니다. 파일을 열면 command = "npx"와 args = ["-y", "@upstash/context7-mcp"]를 곁들인 [mcp_servers.context7]을 찾을 수 있습니다. 항목은 손으로 쓸 수도 있습니다: API 키용 env 테이블을 더하거나, 느린 서버를 위해 startup_timeout_sec(기본 10)과 tool_timeout_sec(기본 60)을 정하거나. 손 편집이 바로 소스 카드의 Snyk과 Net Ninja 영상이 택한 길입니다.
- 4
Codex를 띄우고 /mcp로 검증
프로젝트에서 codex를 시작하고 /mcp를 입력하세요. MCP Tools 패널에는 설정된 서버가 상태·실행 명령·노출 도구와 함께 나열됩니다 — Context7은 query_docs와 resolve-library-id를 보여 줍니다. 여기 빠진 게 있다면 항목이 잘못된 파일에 들어갔거나 시작에 실패한 겁니다.
Codex TUI 안의 /mcp 패널: context7이 활성화돼 있고 두 도구가 이름으로 나열됩니다.1:05부터 시청
파트 2 — 써 보고, 원격으로
- 5
서버를 실제로 쓰는 프롬프트 만들기
MCP 도구는 수요가 있을 때 불립니다. 그러니 그것이 필요한 부탁을 하세요: "Context7로 현재 Tailwind CSS 셋업 문서를 확인해 줘". Codex는 라이브러리를 해석하고, MCP 서버를 통해 문서를 끌어오고, 출처를 밝히며 답합니다. 도구 호출이 흘러가는 걸 보면 서버가 끝까지 작동한다는 증거가 됩니다.
Codex의 답변에는 MCP 서버를 통해 끌어온 Context7 문서의 정확한 URL이 인용돼 있습니다.1:30부터 시청 - 6
--url로 원격 서버 추가
많은 프로바이더가 MCP 서버를 원격으로도 호스팅합니다 — 로컬 프로세스도, npx도 필요 없습니다. codex mcp add context7 --url https://mcp.context7.com/mcp로 등록하면 Codex가 OAuth 지원을 자동 감지하고, "Detected OAuth support. Starting OAuth flow..."를 출력하며, 브라우저를 열어 승인을 받습니다. config.toml의 항목은 [mcp_servers.context7] 아래 url = "https://mcp.context7.com/mcp"이 전부입니다.
한 터미널에 담긴 원격의 전체 흐름: --url 추가, OAuth 감지, 승인 URL, Successfully logged in.2:22부터 시청 - 7
OAuth 동의 화면 승인
브라우저는 Codex가 프로바이더를 대신해 계정에 접근해도 되는지 묻습니다. 요청된 스코프를 검토하고 Allow를 누르면 터미널이 "Successfully logged in"을 확인합니다. OAuth 플로우가 없는 서버는 codex mcp login <name>으로 별도 인증하고, 토큰 기반 서버는 환경 변수를 가리키는 bearer_token_env_var를 받습니다.
Context7의 동의 화면: Codex가 요청하는 스코프를 검토하고 Allow.2:02부터 시청 - 8
.codex/config.toml로 서버를 한 프로젝트에 한정
한 리포지토리에서만 의미가 있는 서버 — 데이터베이스와 대화하는 stdio 서버 DBHub 같은 — 는 프로젝트 설정으로 갑니다. 리포지토리에 .codex 폴더를 만들고, [mcp_servers.dbhub] 항목을 넣은 config.toml을 추가하고, 연결 문자열은 --dsn 인자로 넘기세요(문서의 Postgres 예제를 MySQL 등 여러분 환경에 맞게 조정). 커밋하면 팀원 전원이 같은 서버를 얻습니다. 불러오려면 폴더가 신뢰된 프로젝트여야 합니다.
프로젝트의 .codex/config.toml: DBHub가 stdio로 돌고 args에 리포지토리 데이터베이스의 DSN이 있습니다.3:30부터 시청
파트 3 — 진짜 서버와 2일 차 관리
- 9
MCP 도구로 데이터베이스 조회
DBHub가 설정되면 Codex에게 데이터베이스를 물어보세요: "Petco 데이터베이스를 찾아 테이블을 설명해 줘", 이어서 "가장 잘 팔리는 상품은 뭐야?". Codex는 서버의 describe_table과 execute_sql 도구를 호출하고, SQL 실행 전에 허락을 구하며, 실제 데이터의 숫자로 답합니다. 백엔드 작업 중 스키마 디버깅과 데이터 검증은 이게 최선입니다.
Codex는 dbhub의 execute_sql 도구를 실행하고 가장 잘 팔리는 상품과 그 매출로 답했습니다.4:40부터 시청 - 10
원격 MCP 서버로 GitHub 연결
github/github-mcp-server의 README가 Codex 설정을 문서화합니다: url = "https://api.githubcopilot.com/mcp/"를 곁들인 [mcp_servers.github] 항목을 추가하고, OAuth로 인증하거나 개인 액세스 토큰을 환경 변수로 export하세요(GitHub Settings의 Developer settings에서 Administration과 Contents를 허용한 fine-grained PAT 생성). 이 서버와 Figma MCP 서버 같은 remote-first 서버는 6단계와 같은 패턴입니다.
GitHub MCP 서버 설치 가이드: Codex CLI 항목과 OAuth/PAT 인증 메모.5:22부터 시청 - 11
재시작하고 도구를 실전 투입
codex를 재시작하고 배너를 보세요: "Starting servers (0/3): context7, dbhub, github". 이제 "openai/codex 리포지토리를 내 계정으로 fork해 줘" 같은 명령 하나면 충분합니다 — Codex는 GitHub의 fork 도구를 골라, 승인을 구하고, 실행합니다. 작업별 설정은 이제 없습니다: 도구는 오늘부로 모든 세션의 일부입니다.
- 12
codex mcp list와 데스크톱 앱으로 관리
codex mcp list는 셸에서 설정된 서버를 모두 출력합니다; 제거는 config.toml에서 그 블록을 지우고 확인 차 명령을 다시 도는 것. 데스크톱 앱과 IDE 확장은 같은 ~/.codex/config.toml을 읽으므로, 여기서 설치한 서버는 데스크톱 앱의 Settings, MCP servers 페이지에 켜고 끄는 토글과 함께 나타납니다.
Codex 데스크톱 앱의 MCP servers 설정: 토글 달린 context7, dbhub, github과 추천 서버 목록.7:30부터 시청
Codex의 로컬 stdio vs 원격 MCP 서버
두 종류 모두 같은 [mcp_servers.*] 테이블에 살고 같은 /mcp 패널에 나타납니다 — 차이는 서버가 어디서 도는지, 어떻게 인증하는지. 프로젝트별이 아니라 서버별로 고르세요.
- 1로컬 stdio: Codex가 command와 args — 보통 npx나 바이너리 — 로 직접 프로세스를 띄웁니다. 내 머신에서 돌기에 개발 데이터베이스 같은 localhost 서비스에 닿을 수 있지만(워크스루에서 DBHub가 MySQL을 조회한 게 그렇습니다), 런타임과 업데이트는 여러분이 제공합니다.
- 2원격: Codex는 호스팅된 url과 streamable HTTP로 대화합니다. 살려 둘 프로세스도 없고 인증은 중앙화됩니다 — 기본은 OAuth, 토큰 방식이면 bearer_token_env_var와 http_headers. 문서 자체의 예제는 url = "https://mcp.figma.com/mcp"인 [mcp_servers.figma]입니다.
- 3원격 실행 stdio: 실험적 중간지대. stdio 항목에 experimental_environment = "remote"를 설정하면 실행이 원격 executor로 옮겨가고, env_vars가 어떤 변수가 여행하는지 정합니다 — source = "remote" 표시 항목 포함. Codex 0.160.1이 단단히 다진 길이 이것입니다.
- 4스코프: codex mcp add는 언제나 전역 ~/.codex/config.toml에 씁니다; 프로젝트 전용 서버는 리포지토리 안 .codex/config.toml로 갑니다(신뢰 프로젝트만). 어디서나 원하는 도구는 전역, 환경별 자격 증명을 나르는 건 프로젝트로.
- 5양쪽에 통하는 컨트롤: 느린 서버를 위한 startup_timeout_sec(기본 10)과 tool_timeout_sec(기본 60), Codex가 호출할 수 있는 것을 허용 목록으로 잠그는 enabled/disabled_tools, 그리고 서버가 반드시 떠야 한다면 required = true.
실용적인 기본값: Context7 같은 읽기 전용 문서 서버는 전역으로도 충분하고; 자격 증명이나 데이터를 만지는 것 — DBHub, PAT를 곁들인 GitHub — 은 리포지토리와 함께 검토·철회할 수 있는 프로젝트 설정에 속합니다.
설정했는데 안 될 때: 단골 용의자
Codex에서의 MCP 실패 대부분은 스코프, 타임아웃, 인증 문제 — 그 순서입니다. 서버 자체를 만지기 전에 이 목록을 훑으세요.
- 1/mcp에 서버가 없다: 어떤 파일을 편집했는지 확인하세요. 전역은 ~/.codex/config.toml, 프로젝트는 .codex/config.toml이고 신뢰 프로젝트 한정입니다. 셸에서 codex mcp list를 돌리면 Codex가 실제로 보는 것이 보입니다.
- 2서버가 시작에서 타임아웃: startup_timeout_sec 기본은 10초이고, 큰 패키지의 npx 콜드 다운로드는 그걸 쉽게 넘습니다. 패키지를 미리 설치하거나 항목의 startup_timeout_sec을 올리세요.
- 3도구 호출이 401/403으로 실패: 자격 증명이 없거나 낡았습니다. OAuth 서버면 codex mcp login <name>을, 아니면 bearer_token_env_var를 정하고 변수를 export하세요. 고치면 /mcp가 서버를 다시 enabled로 보여 줍니다.
- 4원격 stdio 서버가 이상한 Windows 관련 에러로 죽는다: 0.160.1 이전에는 명시적으로 설정된 원격 환경 변수와 함께 원격 stdio MCP 서버를 띄우면 SYSTEMROOT·TEMP·TMP가 빠져 Windows executor의 시작 환경이 깨질 수 있었습니다. 0.160.1 이상으로 업데이트하세요.
- 5서버는 뜨는데 답이 틀리거나 비어 있다: 많은 호스팅 서버는 OAuth 위에서도 자체 API 키를 원합니다 — 예컨대 Context7은 env로 건네지는 API 키를 요구합니다. 프로바이더 문서에서 정확한 env 이름을 확인하고 항목의 env 테이블에 추가하세요.
디버깅 중 유용한 레버 둘: 의존하는 서버에 required = true를 걸어 Codex가 그것 없이 조용히 시작하지 않게 하고, enabled = false로 설정을 지우지 않고 하나를 끕니다.