Codex MCP 설정: 원격 서버용 codex mcp add, config.toml 형태, codex mcp login으로 OAuth, 도구 로드 확인까지.

요약: Codex는 ~/.codex/config.toml에서 MCP 서버를 읽으며, CLI가 이 파일을 대신 편집해 줍니다. 원격 서버라면 명령 하나로 충분합니다: codex mcp add unifapi --url https://mcp.unifapi.com. codex mcp list로 등록되었는지 확인하고, 처음 사용할 때 OAuth 로그인이 열리지 않았다면 codex mcp login unifapi를 실행하세요. Codex IDE 확장은 같은 파일을 읽으므로, 한 번 추가한 서버는 터미널과 VS Code에서 모두 사용할 수 있습니다.

OpenAI의 코딩 에이전트인 Codex는 CLI와 IDE 확장에서 Model Context Protocol을 지원합니다. 설정이 TOML 파일 하나라서 설정하기 쉬운 클라이언트에 속하지만, 미묘하게 틀리기도 쉬운 클라이언트입니다. 잘못된 테이블에 서버를 추가하거나 stdio 서버를 URL로 선언하면, 도구를 요청할 때까지 아무 말 없이 실패합니다. 이 가이드는 UnifAPI MCP 서버(https://mcp.unifapi.com, 소셜 플랫폼과 SEO 스택의 실시간 공개 데이터)를 예시로 사용하며, 단계는 어떤 원격 서버에도 동일합니다.

필요한 것

Codex CLI(npm install -g @openai/codex 또는 brew install codex) 또는 VS Code, Cursor, Windsurf의 Codex 확장. 둘 다 ~/.codex/config.toml을 읽습니다.
로그인된 Codex(codex login). MCP는 ChatGPT 로그인과 API 키 모두에서 동작합니다.
UnifAPI의 경우: OAuth 프롬프트가 열릴 때 쓸 UnifAPI 계정, 그리고 첫 과금 호출 전에 워크스페이스 크레딧. 카탈로그 둘러보기는 무료입니다.

codex mcp add로 원격 서버 추가

원격(streamable HTTP) 서버는 URL입니다. 등록하세요.

codex mcp add unifapi --url https://mcp.unifapi.com

기록되었는지 확인하세요.

codex mcp list
codex mcp get unifapi

codex mcp list는 설정된 모든 서버를 transport와 인증 상태와 함께 출력합니다. Codex가 OAuth로 보호된 서버와 함께 세션을 처음 시작하면 브라우저에서 로그인을 엽니다. 열리지 않았거나 브라우저가 없는 머신이라면 직접 실행하세요.

codex mcp login unifapi
# headless: print the URL instead of opening a browser
codex mcp login unifapi --no-browser

OAuth 로그인은 streamable HTTP 서버에만 제공됩니다. stdio 서버에는 로그인 단계가 없습니다. 토큰은 키링(또는 Codex가 대신 쓰는 자격 증명 파일)에 저장되어 세션 간에 재사용됩니다. codex mcp logout unifapi는 토큰을 지우고, codex mcp remove unifapi는 서버를 제거합니다.

그 뒤에 있는 config.toml

CLI가 기록한 것은 모두 [mcp_servers.<name>] 아래의 평범한 TOML입니다. UnifAPI 항목은 한 줄입니다.

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

다른 원격 서버에서는 선택 필드 두 가지가 중요합니다.

[mcp_servers.example]
url = "https://mcp.example.com"
# Read a static bearer token from this environment variable instead of OAuth
bearer_token_env_var = "EXAMPLE_TOKEN"
# Extra headers, literal or sourced from the environment
http_headers = { "X-Client" = "codex" }
env_http_headers = { "X-Tenant" = "EXAMPLE_TENANT" }

UnifAPI는 워크스페이스 API 키를 bearer_token_env_var로 받기도 하지만, 권장 경로는 OAuth입니다. dotfile에 붙여넣을 것이 없고, 토큰은 읽기 전용입니다.

로컬 stdio 서버는 url 대신 command와 args를 사용합니다. 두 형태는 배타적이며, 둘을 섞은 테이블은 거부됩니다.

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Projects"]
env = { "NODE_OPTIONS" = "--max-old-space-size=512" }

프로젝트별 서버

Codex는 프로젝트 수준의 .codex/config.toml(저장소 루트에 있고, 프로젝트가 신뢰된 경우)을 홈 설정 위에 병합합니다. 한 저장소에서만 필요한 서버는 거기에 두고, 팀원이 같은 도구를 받도록 파일을 커밋하세요. codex mcp login은 병합된 설정에서 이름을 찾으므로, 프로젝트 스코프의 OAuth 서버도 같은 방식으로 로그인합니다.

도구 로드 확인

프로젝트에서 세션을 시작하고, 서버만 답할 수 있는 것을 요청하세요.

unifapi MCP 서버를 사용해 Reddit에서 사용할 수 있는 작업을 나열해 줘.

답변 전에 list_operations 도구 호출이 보여야 합니다. IDE 확장에서는 MCP 서버와 도구가 확장의 설정 패널에 나열됩니다. 거기서 서버 상태가 빨간색이면 대개 OAuth 토큰이 없거나(codex mcp login) URL이 잘못된(codex mcp get) 경우입니다.

승인 모드(codex --ask-for-approval, 또는 IDE에서 고른 모드)에 따라 Codex가 도구 호출마다 확인을 요청할 수 있습니다. UnifAPI처럼 읽기 전용인 서버라면 세션 동안 허용해도 안전합니다. 호출이 소비할 수 있는 것은 워크스페이스 크레딧뿐이고, get_operation이 call_api 실행 전에 record당 가격을 보여줍니다.

크레딧이 아깝지 않은 첫 작업

UnifAPI의 MCP 서버는 큰 카탈로그를 세 가지 도구로 노출합니다. 발견을 위한 list_operations, 스키마와 호출 예시를 위한 get_operation, 하나를 실행하는 call_api입니다. Codex는 이 구조에 능합니다. CLI를 다룰 때와 같은 루프, 즉 명령을 찾고, 도움말을 읽고, 실행하는 순서이기 때문입니다. 범위가 제한된 첫 프롬프트:

unifapi MCP 도구를 사용해 "OpenAI Developers"로 찾은 X 계정의 최근 공개 게시물 20개를 가져오고, 게시물, 좋아요, 리포스트, 한 줄 주제를 표로 정리해 줘. call_api 전에 list_operations와 get_operation을 호출해.

과금은 공개 데이터 record당 워크스페이스 크레딧으로 이루어집니다(개당 $0.001, 대부분의 record는 1크레딧, 최소 크레딧이 더 높은 작업은 카탈로그에 게시). 모델 토큰은 OpenAI 플랜에서 소비됩니다. 새 워크스페이스는 첫 충전 전까지 크레딧이 없고 첫 충전에는 일회성 보너스가 따라오므로, 첫 call_api 전에 UnifAPI 콘솔에서 한 번 충전하세요.

작업 단위로 일하려면, 플랫폼 에이전트와 SEO 에이전트가 Codex에 준비된 프롬프트와 필요한 작업 목록을 제공합니다.

문제 해결

증상	해야 할 일
`codex mcp list`에는 서버가 보이는데 도구가 나타나지 않음	새 세션 시작. 서버는 세션 시작 시 로드됨. IDE에서는 창 다시 로드
"OAuth login is only supported for streamable HTTP servers"	테이블에 `url` 대신 `command`가 있음. stdio 서버에는 로그인 단계가 없음
브라우저 로그인이 완료되지 않음	`codex mcp login unifapi --no-browser`를 실행하고, 출력된 URL을 아무 브라우저에서 열어 콜백을 터미널에 다시 붙여넣기
`call_api`가 `insufficient_credits`를 반환	워크스페이스에 아직 크레딧이 없음. 콘솔에서 한 번 충전한 뒤 같은 프롬프트 재실행
한 저장소에서만 서버가 사라짐	프로젝트의 `.codex/config.toml`이 홈 설정을 덮어쓰고 있음. `codex mcp get <name>`이 항목의 출처 파일을 보여줌
도구 호출이 거부됨	승인 모드가 차단하고 있음. 세션 동안 승인하거나 이 프로젝트의 모드를 완화

확인한 출처

2026년 10월 14일에 Codex CLI의 MCP 설정 레퍼런스와 현재 릴리스의 codex mcp 하위 명령(add, list, get, login, logout, remove), 그리고 Codex MCP에 관한 OpenAI 개발자 문서에 맞춰 작성했습니다. config.toml의 필드 이름은 CLI 자체 스키마에서 가져왔습니다.

다음에 읽을 글

MCP 설정 - 모든 클라이언트의 호스팅 커넥터 안내.

Claude에 MCP 서버 추가하는 방법 - 커넥터, claude_desktop_config.json, claude mcp add.

Cursor MCP 설정 - mcp.json과 원클릭 설치 링크.

MCP 카탈로그 도구 설계 - 서버가 엔드포인트마다 하나가 아니라 세 가지 도구를 노출하는 이유.