Codex를 MCP 도구에 연결하기
Codex가 문서 검색이나 업무 서비스의 도구를 사용하게 하려면 MCP 연결을 검토합니다. 이때 Codex가 외부 MCP server의 도구를 쓰는 역할과 Codex 자체를 MCP server로 내보내는 역할은 다릅니다. 후자의 기존 명령은 제거되었습니다.
공식 문서를 참고한 비공식 한국어 가이드입니다. 아래 설정은 구조를 보여 주는 합성 예시이며 서버 설치·연결·OAuth 로그인은 실행 미검증입니다. 모르는 MCP 서버를 로컬에서 실행하지 않습니다.
연결 방식 선택
로컬 Codex 앱·CLI·IDE는 같은 host의 MCP 설정을 공유합니다. STDIO는 지정한 프로세스를 실행하고, Streamable HTTP는 원격 endpoint에 연결합니다. 웹은 로컬 config.toml을 읽지 않으며 플러그인 경로와 웹 호환 조건을 따로 확인합니다.
다음은 관리자가 제공한 읽기 전용 문서 서비스가 있다는 가정의 형태입니다. .invalid 주소는 실제 접속용이 아니므로 복사해서 등록하지 않습니다.
[mcp_servers.team_docs]
url = "https://docs.example.invalid/mcp"
enabled_tools = ["search_docs"]
설정하려면 실제 서버의 지원 도구 이름과 인증 방식을 확인합니다. URL이 맞다는 사실만으로 제공자나 도구의 안전성이 확인되지는 않습니다. STDIO의 command·args는 로컬 코드 실행으로 취급합니다.
등록·인증·호출을 따로 확인
CLI 등록 형식은 codex mcp add <name> -- <stdio-command> 또는 codex mcp add <name> --url <url>입니다. OAuth가 필요한 서버는 codex mcp login <name>, 세션 상태는 /mcp로 확인합니다. 앱은 Settings의 MCP servers에서 추가하고 다시 시작하는 흐름입니다.
등록 성공, 인증 성공, 실제 도구 호출 성공은 다른 단계입니다. 도구 목록만 읽을 수 있어도 업무 데이터 접근은 실패할 수 있습니다. 반대로 목록이 보인다고 쓰기를 허용한 것은 아닙니다. 처음에는 승인된 작은 조회만 수행하고 반환 데이터의 범위를 확인합니다.
도구와 시작 조건 제한
enabled_tools로 허용 집합을 좁히고 disabled_tools가 뒤에 적용되는 순서를 확인합니다. 이름이 안전해 보이는 도구도 실제로 파일·계정·데이터를 변경할 수 있으므로 설명과 제공자 문서를 읽습니다.
required = true의 연결 요구와 startup_readiness = "catalog"의 캐시 기반 시작은 다릅니다. 후자로 시작이 통과해도 실제 호출에는 연결이 필요합니다. 장애를 해결하려고 검증 없이 optional로 바꾸면 필수 도구가 없는 작업을 성공으로 오인할 수 있습니다.
OAuth callback은 화면/출력에 나온 정확한 URL을 사용합니다. listener 포트 설정과 등록 URL의 포트는 별개이므로 임의로 맞춰 쓰지 않습니다. confidential client secret이 설정 파일에 저장되는 경우가 있으니 버전 관리와 공유 범위를 주의합니다.
제거된 Codex MCP server
현재 공식 제거 안내는 codex mcp-server와 codex-mcp-server binary, 관련 옛 tool/Agents SDK 예제가 더 이상 지원되지 않는다고 명시합니다. 외부 서버 연결용 codex mcp까지 제거된 것은 아닙니다.
App Server는 자체 프로토콜이며 기존 MCP client에 URL만 바꿔 넣는 대체품이 아닙니다. 직접 클라이언트를 개발할 때는 지원 상태와 인증·승인 요청 처리를 먼저 검토하세요. 연결 실패나 악성 응답이 의심되면 호출을 멈추고 권한과 전송된 데이터 범위를 확인합니다.
공식 한국어 도움말: ChatGPT 플랜과 Codex에서 계정별 이용 안내를 확인할 수 있습니다. 이 글은 해당 도움말의 공식 번역이 아니며 계정 조건과 요금은 공식 안내를 우선합니다.