Ch11. MCP 연동

Codex는 MCP(Model Context Protocol)로 외부 도구와 데이터를 연결합니다. 팀에서는 MCP 서버를 표준화하고 사용 범위를 제한해야 합니다.

MCP 설계 원칙(팀 기준)

• 서버/도구는 allowlist 기반: "누가 어떤 MCP를 켤 수 있는지"를 정책으로 정한다
• 자격증명은 환경변수로: 토큰/키를 config.toml에 하드코딩하지 않는다
• 툴 범위는 좁게: enabled_tools/disabled_tools로 위험 툴을 최소화한다
• 시간 제한: startup_timeout_sec/tool_timeout_sec로 장시간/무응답을 방지한다

고급 팁

• 서버 표준화: 공통 MCP 서버 목록을 팀 기준으로 고정
• 출력 제한: 대량 데이터 반환은 페이지네이션/요약 적용
• 권한 분리: 민감 MCP 도구는 별도 승인 정책 적용
• mcp 명령 표준화: codex mcp로 서버 추가/관리 절차를 통일

릴리스 기반 운영 포인트 (0.99.0~0.139.0)

• required MCP fail-fast: 필수 서버가 시작/재개 시 깨져 있으면 더 빨리 실패합니다. required는 정말 필수인 경우에만 지정하세요
• OAuth resource 전달 개선: 특정 서버가 oauth_resource를 요구한다면 최신 흐름이 더 안정적입니다
• structured MCP elicitation: app-server v2는 MCP elicitation을 raw event가 아니라 request/response 흐름으로 다루므로 클라이언트 구현이 쉬워졌습니다
• resume/start 병목 완화: MCP auth 체크로 세션 시작이 막히는 현상이 줄어들어 대규모 워크스페이스 UX가 개선됐습니다
• App integrations Responses API tool-search (0.115.0): App 통합에서 Responses API tool-search를 사용하며 fallback 경로도 갖추어, MCP 도구 탐색이 더 안정적입니다
• MCP Apps/custom server 확장 (0.119.0): resource read, tool-call metadata, custom-server tool search, server-driven elicitation, file-parameter upload까지 범위가 넓어졌습니다. 팀이 "읽기 전용 문맥 서버"와 "실행 도구 서버"를 섞어 쓸 때 유용합니다
• /mcp 경량화 + startup 소음 감소 (0.119.0): hyphenated server names 처리, 느린 full inventory probe 제거, disabled 서버 auth probe 생략으로 세션 시작과 점검이 더 빨라졌습니다
• MCP cleanup 안정화 (0.120.0): app-server disconnect 시 thread/resource cleanup이 더 정확해져 장시간 연결에서 누수성 잔여 상태가 줄었습니다
• MCP/plugin surface 확장 (0.121.0): MCP Apps tool call, namespaced MCP registration, parallel-call opt-in, sandbox-state metadata가 추가되어 서버 쪽 책임을 더 명확히 분리할 수 있습니다
• plugin marketplace source 확장 (0.121.0~0.122.0): codex marketplace add와 plugin workflow가 GitHub/git URL/로컬 디렉토리/직접 marketplace.json URL, remote·cross-repo·local source까지 다루기 시작했습니다
• /mcp verbose (0.123.0): 세션에서 보이는 MCP surface를 더 자세히 검사할 수 있어, "도구가 왜 안 보이는지"를 빠르게 파악하기 쉬워졌습니다
• remote marketplace read/list (0.124.0): remote plugin marketplace를 목록/읽기 단위로 다룰 수 있어, 플러그인 공급원을 운영 정책으로 통제하기 쉬워졌습니다
• remote plugin install + marketplace upgrade (0.125.0): app-server plugin management가 remote plugin 설치와 marketplace upgrade를 지원해, MCP 번들 공급망 관리가 한 단계 더 자동화됐습니다
• MCP tool search 기본화 (0.143.0): MCP 도구는 기본적으로 tool search를 사용하므로, 대규모 tool surface의 컨텍스트 비용과 discovery 동작을 새 기준으로 재검증합니다
• session/interactive auth (0.143.0~0.144.0): ChatGPT-hosted MCP 서버는 session auth를 명시할 수 있고, MCP 도구의 interactive authentication은 experimental opt-in 없이 동작합니다
• Unix socket integrations (0.125.0): app-server integrations가 Unix sockets를 지원해, 로컬 호스트 안에서만 노출할 내부 연동을 더 좁은 경계로 운영할 수 있습니다
• plugin sharing + source filtering (0.129.0): workspace sharing, share access controls, source filtering, local share path tracking, marketplace removal/upgrades, remote bundle sync가 들어와 플러그인을 팀 배포 단위로 관리하기 쉬워졌습니다
• plugin details의 bundled hooks 표시 (0.130.0): plugin이 어떤 lifecycle hook을 함께 싣는지 설치 전에 더 쉽게 볼 수 있습니다. hooks가 포함된 plugin은 단순 도구 추가가 아니라 실행 루프 변경으로 취급하세요
• built-in MCP first-class runtime servers (0.130.0): 내장 MCP가 runtime server surface로 정리되면서, "내장/외부"보다 "어떤 권한과 승인 정책으로 실행되는지"를 중심으로 inventory를 점검해야 합니다
• plugin marketplace CLI + version-aware sharing (0.131.0): plugin marketplace CLI commands, share checkout, version-aware sharing, clearer shared-workspace buckets가 들어와 플러그인 배포/회수 절차를 더 명시적으로 운영할 수 있습니다
• 통합 @ picker (0.131.0): files, directories, plugins, skills가 한 picker에서 검색되므로, plugin/skill 이름 충돌과 팀 naming convention을 inventory 정책에 포함하세요
• MCP OAuth callback 식별성 (0.131.0): local MCP OAuth redirects에 callback ids가 추가되어 여러 인증 흐름을 병렬로 다룰 때 추적성이 좋아졌습니다
• per-server environment targeting + OAuth options (0.134.0): streamable HTTP MCP 서버의 OAuth 옵션과 서버별 environment targeting이 보강되어, 같은 서버라도 dev/prod 자격증명과 실행 환경을 분리하기 쉬워졌습니다
• read-only MCP tools 병렬 실행 (0.134.0): MCP tool이 readOnlyHint를 광고하면 읽기 전용 호출을 병렬로 처리할 수 있습니다. 문서 검색/메타데이터 조회 서버는 read-only hint를 정확히 선언해 성능을 얻고, mutating tool에는 절대 붙이지 마세요
• richer MCP server status (0.136.0): app-server integrations에서 MCP 서버 상태를 더 풍부하게 볼 수 있으므로, 내부 클라이언트는 "서버가 없음/꺼짐/인증 필요/도구 없음"을 같은 오류로 뭉개지 말고 구분해 표시하세요
• plugin JSON output + cached remote catalog suggestions (0.137.0): codex plugin list --json과 remote catalog suggestion cache가 들어와, 플러그인 인벤토리를 CI/감사 스크립트로 수집하기 쉬워졌습니다
• plugin/marketplace JSON 계약 확장 (0.138.0~0.139.0): plugin add/remove와 marketplace 명령이 --json을 지원하고, codex plugin list --available --json은 미설치 marketplace plugin과 marketplaceSource를 함께 다룰 수 있습니다. marketplace install/upgrade 결과의 selected/upgraded/error 필드를 감사 로그로 보존하세요
• tool input schema 보존 (0.139.0): connector/MCP tool input schema가 oneOf와 allOf를 보존하고, 큰 schema도 더 얕은 구조를 유지하므로 richer MCP tool 호환성이 좋아졌습니다. 사내 MCP 서버는 breaking change가 schema flattening에 묻히지 않도록 JSON Schema version과 fixture를 같이 보관하세요
• MCP startup warning scoping (0.139.0): subagent에서 발생한 MCP startup warning이 parent thread로 중복 전파되지 않도록 thread owner 기준으로 스코프가 정리됐습니다. 모니터링은 parent/child thread id를 분리해서 기록해야 합니다

0.119.0 이후 팀 설계 포인트

MCP가 이제 단순한 "툴 호출"에 그치지 않고 더 풍부한 메타데이터와 업로드까지 다루기 시작했으니, 팀 운영도 그만큼 잘게 나누는 편이 좋습니다.

• resource server / action server 분리: 문서 읽기·검색 위주의 서버와 실제 변경을 일으키는 서버를 분리
• tool-call metadata 기록: 감사가 필요한 팀은 어떤 MCP 호출이 어떤 컨텍스트에서 나갔는지 별도 로그 필드를 두기
• file upload 허용 기준: 업로드 가능한 파일 종류와 크기를 정책으로 제한
• elicitation UX 표준화: 서버가 추가 입력을 요청하는 경우, 사람이 무엇을 승인/입력하는지 UI 카피를 통일

CLI로 MCP 서버 추가(운영 절차)

문서 기준으로 codex mcp add는 환경변수와 함께 STDIO 서버 커맨드를 등록합니다.

codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio-server-command>

OAuth를 지원하는 서버는 codex mcp login <server-name> 흐름을 씁니다.

config.toml 예시(공식 문서 기반)

STDIO 서버

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"

Streamable HTTP 서버

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }

Skills에서 MCP 의존성 선언

스킬의 agents/openai.yaml에서 MCP 서버 의존성을 선언하면, 스킬 사용 시 자동으로 설치/연결됩니다.

# agents/openai.yaml
dependencies:
  tools:
    - type: 'mcp'
      value: 'openaiDeveloperDocs'
      description: 'OpenAI Docs MCP server'
      transport: 'streamable_http'
      url: 'https://developers.openai.com/mcp'

Plugins + @plugin으로 MCP 번들링 (0.110.0~0.112.0)

플러그인 시스템이 들어오면서 MCP는 단독 서버 목록이 아니라 skills/app connectors와 함께 배포되는 컨텍스트 번들에 가까워졌습니다.

• config 또는 local marketplace에서 플러그인 로드
• 세션 시작 시 Codex가 활성 플러그인 목록을 먼저 파악
• @plugin 멘션으로 관련 MCP/app/skill 컨텍스트를 명시적으로 붙일 수 있음

팀 운영 팁:

• MCP 서버 이름과 plugin 이름을 동일하게 맞추지 말고, 업무 단위로 묶어 관리한다
• required MCP는 플러그인 분리 없이 최소 수만 둔다
• plugin enable/disable 변경은 changelog처럼 기록해 "왜 켰는지"를 남긴다

플러그인 마켓플레이스와 라이프사이클 관리 (0.113.0)

0.113.0부터 플러그인 워크플로우가 크게 넓어졌습니다. 기존 로컬 config 기반 관리에서 마켓플레이스 기반 탐색·설치·제거 체계로 옮겨갔습니다.

마켓플레이스 탐색(Discovery)

• plugin/list에서 마켓플레이스 검색이 가능해졌습니다
• 각 플러그인의 메타데이터가 풍부해져 설명, 버전, 의존 MCP 서버, 권한 요구사항 등을 설치 전에 확인할 수 있습니다
• 팀에서는 "승인된 플러그인 목록"을 마켓플레이스 기준으로 관리하면 표준화가 수월합니다

설치 시 인증 검증(Auth Checks)

• 플러그인 설치 시점에 필요한 인증 정보가 갖춰져 있는지 사전 검증합니다
• OAuth 토큰이 만료되었거나 환경변수가 누락된 경우, 설치 단계에서 즉시 안내가 나옵니다
• 이전에는 설치 후 세션에서 "MCP 서버 연결 실패"로 뒤늦게 알았던 문제를 미리 막아줍니다

플러그인 제거(Uninstall)

• plugin/uninstall 엔드포인트가 추가되어 클린 제거가 가능합니다
• 연결된 MCP 서버·스킬·앱 컨텍스트도 함께 정리됩니다

Plugin sharing 운영 (0.129.0~0.132.0)

최근 plugin workflow는 개인 설치 메뉴를 넘어 팀 배포와 공유 통제 쪽으로 옮겨갔습니다.

• 공유 권한: workspace sharing과 share access controls를 기준으로 "누가 설치/공유/수정할 수 있는지"를 분리
• 공급원 필터링: source filtering으로 개인 marketplace, 로컬 경로, remote bundle의 허용 범위를 나눔
• hook 가시성: bundled hooks가 보이면 plugin 설치가 세션 라이프사이클에 영향을 줄 수 있으므로 보안/플랫폼 리뷰 대상에 포함
• remote bundle sync: remote bundle이 자동 동기화될 수 있으므로 버전 핀, 롤백, 감사 로그를 plugin 운영 절차에 포함

0.139.0 이후에는 plugin inventory를 사람이 보는 TUI 목록뿐 아니라 codex plugin list --json, codex plugin list --available --json, codex plugin marketplace list --json 출력으로도 수집할 수 있습니다. 팀 표준 플러그인을 운영한다면 "설치된 plugin 목록, source, marketplaceSource, version, discoverability, bundled hook 여부, remote MCP server 포함 여부"를 정기 점검 대상으로 넣으세요.

Codex App에서 MCP 단축키 (0.106.0+)

Codex App 작성기에서 MCP 관련 새 단축키가 추가되었습니다:

• 설치 키워드 제안
• "컨텍스트 추가" 메뉴에 MCP 서버 서브메뉴

세션에서 MCP 상태 확인

• /mcp: 현재 세션에서 사용 가능한 MCP 도구 목록 확인(의도대로 enable 되었는지 점검)

/mcp
/mcp verbose

0.146.0 연결·도구 새로고침

MCP 인증이나 config, App/Plugin enablement를 바꾼 뒤 CLI를 재시작하지 않고 연결과 tool inventory를 새로고칠 수 있습니다. refresh 후에는 /mcp·/mcp verbose로 서버 상태를, /apps·/skills로 노출된 surface를 확인하세요. proxy를 쓰는 환경은 auth redirect와 WebSocket까지 같은 proxy 정책을 타는지도 함께 검증합니다.

MCP 2026-07-28 protocol opt-in (0.147.0+)

0.147.0은 새 MCP protocol revision을 opt-in으로 지원합니다. pagination, 여러 차례의 왕복 상호작용, nonblocking server startup을 사용하는 서버는 기존 protocol과 새 protocol을 각각 smoke test하세요. 0.148.0에서는 reconnect와 MCP OAuth 흐름, hook에서의 MCP tool invocation도 보강됐습니다. server가 "connected"라고 표시되는 것만으로 충분하지 않으므로 첫 페이지/다음 페이지, multi-round 응답, OAuth refresh, hook 호출을 별도 검증합니다.

MCP 서버 진입점 제거 (0.154.0)

2026-09-05 공식 공지와 0.154.0 릴리스는 codex mcp-server 및 독립 codex-mcp-server 제거를 명시합니다. 업그레이드 전에 이를 실행하는 기존 caller를 수정하세요. 외부 MCP 서버를 연결하는 codex mcp는 계속 지원합니다. 대체 통합인 codex app-server는 experimental이며 production workload 지원 대상이 아닙니다. transport와 인증·재연결을 검증한 뒤 이전 여부를 결정하세요.

0.154.0의 OAuth token 갱신 실패는 재인증을 요청하고 거절된 tool 호출을 자동 재실행하지 않습니다.

공식 Changelog

참고 문서

• MCP 개요: https://developers.openai.com/codex/mcp (영어)
• config 레퍼런스(MCP 키): https://developers.openai.com/codex/config-reference (영어)
• 슬래시 커맨드(/mcp): https://developers.openai.com/codex/cli/slash-commands (영어)
• Skills(MCP 의존성): https://developers.openai.com/codex/skills (영어)
• GitHub Releases: https://github.com/openai/codex/releases (영어)