Codex MCP 연결법: 설정·OAuth·보안 체크리스트

세 줄 요약

MCP는 Codex에 외부 문서·데이터·도구를 표준 방식으로 연결한다.
로컬 프로세스인 STDIO와 원격 Streamable HTTP를 지원하며 HTTP는 Bearer·OAuth 인증을 사용할 수 있다.
서버 연결은 신뢰 부여다. 최소 권한, 비밀정보 전달 경로, 쓰기 도구 승인 범위를 먼저 확인해야 한다.

Codex가 저장소 밖의 문서, 디자인 도구, 브라우저나 사내 시스템을 써야 한다면 복사·붙여넣기만으로는 최신성과 재현성이 떨어진다. Model Context Protocol은 모델이 사용할 도구와 컨텍스트를 공통 방식으로 노출한다.

다만 “MCP를 설치했다”는 말은 기능 추가와 동시에 새로운 신뢰 경계를 만들었다는 뜻이다. 어떤 프로세스가 실행되는지, 어떤 서버로 데이터가 가는지, 읽기와 쓰기 중 무엇을 제공하는지 확인해야 한다.

MCP가 연결하는 세 가지

첫째는 도구다. 이슈 생성, 디자인 조회, 데이터베이스 질의처럼 명시된 작업을 호출한다. 둘째는 리소스와 문서다. 모델이 필요한 컨텍스트를 검색·읽는다. 셋째는 서버 지침이다. 서버 전체의 작업 순서, 제한, 속도 규칙을 초기화 시 전달할 수 있다.

OpenAI 문서는 서버 지침의 첫 512자를 자체 완결적으로 쓰라고 권한다. Codex가 도구 선택을 판단할 때 가장 중요한 경계가 앞부분에 있어야 한다.

STDIO와 HTTP 중 무엇을 고를까

STDIO 서버는 로컬 명령으로 프로세스를 시작한다. 로컬 파일이나 개발 도구와 가까운 통합에 편하지만 설치 패키지와 실행 명령을 신뢰해야 한다.

Streamable HTTP 서버는 URL로 접속하며 Bearer 토큰, OAuth, 동적 클라이언트 등록 등을 지원한다. 팀이 중앙에서 운영하는 서비스에 적합하지만 전송되는 데이터와 원격 보관 정책을 확인해야 한다.

STDIO: 로컬 프로세스, 환경변수, 패키지 공급망 검토
HTTP: 원격 URL, 인증·TLS·데이터 보관 검토

데스크톱과 CLI에서 연결하기

ChatGPT 데스크톱 앱, Codex CLI, IDE 확장은 같은 Codex 호스트의 MCP 설정을 공유한다. 기본 설정은 Codex 홈의 config.toml, 신뢰된 프로젝트는 .codex/config.toml로 범위를 좁힐 수 있다.

CLI에서는 add로 등록하고 list로 확인한다. OAuth 서버는 login 명령으로 인증한다. 데스크톱 앱에서는 Settings의 MCP servers에서 유형과 명령 또는 URL을 넣고 재시작한다.

# STDIO 예시
codex mcp add context7 -- npx -y @upstash/context7-mcp

# 확인과 OAuth
codex mcp list
codex mcp login <server-name>

# TUI에서 연결 도구 보기
/mcp

OpenAI 공식 문서는 읽기 전용 Docs MCP로 붙일 수 있다

OpenAI는 developers.openai.com, platform.openai.com, learn.chatgpt.com을 검색·읽는 공개 MCP를 제공한다. 문서 전용이며 OpenAI API를 대신 호출하지 않는다.

등록 뒤 AGENTS.md에 OpenAI 제품 작업 시 이 문서 서버를 우선 사용하라는 짧은 지침을 둘 수 있다. 그러면 버전이 바뀔 수 있는 기능을 기억에 의존하는 대신 공식 페이지에서 확인하게 만들 수 있다.

codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp
codex mcp list

# config.toml
[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

연결 전 보안 체크리스트

서버 이름과 설명만 보고 신뢰하지 않는다. STDIO 명령이 설치·실행하는 패키지, HTTP 도메인, 인증 범위, 도구의 읽기·쓰기 구분, 반환 데이터에 비밀정보가 포함되는지 확인한다.

MCP 도구도 현재 승인 정책과 도구 주석에 따라 승인이 필요할 수 있다. 쓰기·삭제·메시지 전송·운영 변경은 명시적 확인이 보이도록 설계하고, 토큰은 설정 파일 본문보다 안전한 환경변수나 OAuth 흐름을 사용한다.

도구가 많아질수록 선택 규칙을 짧게 둬라

비슷한 검색 도구가 여러 개면 “최신 공식 API 정보는 OpenAI Docs MCP, 사내 정책은 내부 문서 서버”처럼 출처별 책임을 나눈다. 도구를 무조건 호출하라는 지시는 불필요한 지연과 데이터 노출을 만든다.

MCP 연결 문제를 디버깅할 때는 목록과 verbose 진단, 서버 로그, 인증 상태를 차례로 확인한다. 연결 실패를 해결하려고 무턱대고 전체 권한을 주는 것은 원인 진단이 아니다.

핵심 구분

프롬프트는 이번 일, AGENTS.md는 저장소 규칙, Skill은 반복 절차, Goal은 지속 목표다

서브에이전트는 독립 작업을 나누고 MCP는 외부 도구와 정보를 연결한다. 역할을 섞지 않을수록 지시는 짧아지고 결과는 더 예측 가능해진다.

자주 묻는 질문

Codex에서 MCP는 무엇인가?

외부 도구와 문서·컨텍스트를 표준 방식으로 Codex에 제공하는 프로토콜이다.

STDIO와 HTTP의 차이는?

STDIO는 로컬 프로세스를 실행하고, Streamable HTTP는 원격 서버에 접속한다. 설치 공급망과 원격 데이터 전송이라는 서로 다른 위험을 검토해야 한다.

OpenAI Docs MCP는 API를 호출하나?

아니다. 공식 문서를 검색하고 읽는 읽기 전용 서버이며 OpenAI API 요청을 대신 실행하지 않는다.

MCP 서버를 추가하면 자동으로 모든 권한이 생기나?

아니다. 현재 샌드박스, 승인 정책과 각 도구의 승인 설정이 계속 적용된다.