Codex에 MCP를 연결하면 저장소 밖의 도구와 컨텍스트까지 사용할 수 있습니다.
Codex CLI, IDE 확장 프로그램과 ChatGPT 데스크톱 앱은 같은 Codex Host의 MCP 설정을 공유합니다. 한 번 연결한 Server를 여러 로컬 Codex 인터페이스에서 다시 설정하지 않고 사용할 수 있다는 뜻입니다.
이번 글에서는 로컬 stdio와 원격 Streamable HTTP Server 등록, OAuth, 사용자·프로젝트 설정 범위, Tool별 승인과 문제 해결을 2026년 9월 공식 OpenAI 문서와 현재 CLI 명령을 기준으로 설명합니다.
1. Codex와 MCP가 연결되는 구조
Codex는 사용자의 요청과 프로젝트 컨텍스트를 관리하는 MCP Host입니다. 등록한 MCP Server는 Codex가 사용할 수 있는 Tool과 외부 데이터를 제공하며, Codex는 필요할 때 적합한 Tool과 입력값을 선택합니다.
공식 문서 기준으로 Codex는 STDIO Server와 Streamable HTTP Server를 지원합니다. Server가 초기화 과정에서 instructions를 제공하면 Codex는 이를 해당 Server 전체에 적용되는 지침으로 읽습니다. 다만 Tool의 실제 동작과 데이터 접근 범위는 Server 구현과 연결 계정 권한에 따라 달라집니다.
ChatGPT 웹은 로컬
~/.codex/config.toml을 읽지 않습니다. 웹에서는 플러그인을 통해 제공되는 원격 MCP 도구를 사용하고, 이 글의 설정은 로컬 Codex CLI·IDE·데스크톱 앱을 중심으로 합니다.2. 시작 전 Codex와 실행 환경 확인하기
먼저 Codex CLI가 설치되어 있고 로그인과 프로젝트 접근이 정상인지 확인합니다. 로컬 Server를 사용할 경우 Node.js, Python 또는 서버 전용 바이너리도 별도로 필요할 수 있습니다.
codex 명령이 실행되고 계정 로그인이 완료됐는가?CLI 버전에 따라 새 옵션이 추가될 수 있습니다. 블로그 예시와 설치된 버전의 동작이 다르면 codex mcp --help와 OpenAI 공식 MCP 문서를 우선하세요.
3. CLI로 로컬 stdio Server 추가하기
로컬 stdio Server는 Codex가 지정된 명령을 실행하고 표준 입출력으로 통신하는 방식입니다. 기본 문법에서 -- 뒤에는 MCP Server를 시작할 명령과 인수를 작성합니다.
--
공식 OpenAI 문서의 Context7 예시는 다음과 같습니다.
이 명령은 Codex의 MCP 설정에 context7 Server를 추가하고, 필요할 때 npx -y @upstash/context7-mcp를 로컬 프로세스로 실행하도록 구성합니다. 실제 사용 전 패키지 제공자와 소스, 설치 시 실행되는 코드를 확인하세요.
API 키나 토큰은 Server가 지원하는 환경 변수 전달 방식을 사용하고, 공유 저장소의 설정에는 값이 아니라 필요한 변수 이름만 기록하는 방식을 우선 검토하세요. PowerShell·Bash 기록과 화면 캡처에도 비밀값이 남을 수 있습니다.
4. 원격 HTTP Server와 OAuth 연결하기
원격 Server는 실행 명령 대신 --url을 사용합니다. Server가 OAuth를 지원하면 등록 후 별도 로그인 명령으로 인증을 시작할 수 있습니다.
공식 OpenAI의 Linear 연결 안내는 다음 명령을 예시로 사용합니다.
브라우저가 열리면 연결할 계정과 요청 권한을 확인합니다. 브라우저를 자동으로 열 수 없는 환경에서는 현재 CLI가 지원하는 --no-browser 옵션을 사용해 인증 URL과 콜백을 수동으로 처리할 수 있습니다.
Bearer Token을 요구하는 원격 Server는 토큰 값이 들어 있는 환경 변수 이름을 지정할 수 있습니다.
EXAMPLE_MCP_TOKEN은 실제 토큰을 담은 환경 변수의 이름입니다. 토큰은 서비스에서 최소 권한으로 발급하고, 노출이 의심되면 즉시 폐기·재발급하세요.5. config.toml로 사용자·프로젝트 범위 설정하기
Codex는 MCP Server 설정을 다른 로컬 설정과 함께 TOML 파일에 저장합니다. 개인 기본값과 프로젝트별 설정의 위치가 다르며, 프로젝트 설정은 신뢰한 저장소에서만 로드됩니다.
| 범위 | 파일 위치 | 적합한 상황 | 주의점 |
|---|---|---|---|
| 사용자 | ~/.codex/config.toml |
내 여러 프로젝트에서 공통으로 사용하는 Server | 같은 Codex Host의 CLI·IDE·데스크톱 앱이 공유 |
| 프로젝트 | .codex/config.toml |
특정 저장소에만 필요한 Server와 Tool 정책 | 신뢰한 프로젝트에서만 로드되며 비밀값을 커밋하지 않음 |
로컬 stdio Server를 직접 작성하는 기본 형태입니다.
원격 HTTP Server는 url을 사용합니다.
같은 설정 키가 충돌하면 프로젝트의 .codex/config.toml이 사용자 설정보다 높은 우선순위를 가집니다. 여러 프로젝트 설정이 적용되는 경우에는 현재 작업 디렉터리에 더 가까운 파일이 우선합니다.
외부에서 받은 저장소의
.codex/config.toml에는 로컬 프로그램을 시작하는 명령이나 원격 URL이 포함될 수 있습니다. 프로젝트를 신뢰하기 전에 [mcp_servers.*] 항목을 읽고 필요한 연결인지 확인하세요.6. 연결 상태와 사용 가능한 Tool 확인하기
설정 추가 메시지는 연결 성공이 아니라 “구성이 저장됐다”는 의미일 수 있습니다. 목록과 개별 설정, 실제 세션의 활성 Server를 차례로 확인합니다.
/mcp
Codex 터미널 UI 안에서는 /mcp를 입력해 현재 활성 Server를 볼 수 있습니다. IDE 확장 프로그램에서는 오른쪽 위 기어 메뉴의 MCP servers에서 Server를 추가·활성화하고, OAuth가 필요한 항목은 Authenticate를 선택한 뒤 확장 프로그램을 다시 시작합니다.
7. Tool 권한과 실행 범위를 제한하기
Server 전체를 연결해도 모든 Tool을 같은 방식으로 허용할 필요는 없습니다. Codex의 config.toml에서는 허용·차단 Tool 목록과 기본 승인 방식을 Server별로 설정할 수 있습니다.
공식 문서가 안내하는 Server 기본 승인 값은 auto, prompt, writes, approve입니다. 처음 연결하는 Server는 prompt로 시작하고, 반복 검증된 읽기 Tool만 필요에 따라 범위를 좁혀 조정하는 편이 안전합니다.
Tool 승인, Codex 샌드박스, MCP Server 계정, 하위 API 권한은 서로 다른 계층입니다. 한 계층이 제한적이어도 다른 계층이 넓은 권한을 가질 수 있으므로 삭제·배포·발송·결제 작업은 실행 전 대상과 영향 범위를 확인하세요.
8. 연결 오류를 해결하는 순서
| 증상 | 가능한 원인 | 확인 순서 |
|---|---|---|
| 목록에 Server가 없음 | 잘못된 설정 파일 위치, 프로젝트가 신뢰되지 않음 | codex mcp list와 사용자·프로젝트 config.toml 위치를 확인합니다. |
| stdio 초기화 실패 | 런타임·패키지 누락, command 또는 args 오류 | Server 실행 명령을 터미널에서 직접 실행하고 필수 환경 변수를 확인합니다. |
| 원격 연결 실패 | URL 오류, 네트워크·프록시 차단, Server 장애 | Streamable HTTP 엔드포인트와 서비스 상태, 네트워크 정책을 확인합니다. |
| OAuth 로그인 실패 | 계정 오류, 콜백 불일치, 범위 부족 | codex mcp login 이름을 다시 실행하고 표시된 계정·권한·콜백 URL을 검토합니다. |
| Tool 실행이 시간 초과 | Server 시작 지연 또는 긴 작업 | 먼저 Server 로그와 응답을 점검한 뒤 필요한 경우에만 startup_timeout_sec·tool_timeout_sec를 조정합니다. |
| 예상한 Tool이 보이지 않음 | enabled·disabled 목록, Server 버전, 초기화 실패 | 설정의 Tool 필터와 /mcp 활성 상태, Server의 실제 Tool 목록을 확인합니다. |
설정 위치와 프로젝트 신뢰 → 명령 또는 URL → 런타임과 환경 변수 → 인증 → Tool 필터 → 타임아웃 순으로 확인하면 문제를 좁히기 쉽습니다.
환경 변수, Authorization 헤더, OAuth 콜백과 데이터베이스 연결 문자열을 공유하기 전에 가립니다. 토큰 노출이 의심되면 로그를 지우는 것만으로 끝내지 말고 서비스에서 즉시 폐기·재발급하세요.
9. 핵심 정리
Server 검증 stdio 또는 HTTP config.toml 범위 OAuth·상태 확인 Tool 최소 권한
로컬 Server는
codex mcp add 이름 -- 명령, 원격 Server는 codex mcp add 이름 --url URL로 등록합니다. 사용자 기본 설정은 ~/.codex/config.toml, 신뢰한 프로젝트의 설정은 .codex/config.toml에 두고, codex mcp list·get·/mcp로 실제 활성 상태를 확인합니다.MCP는 Codex의 연결 범위를 넓히지만 결과의 정확성과 작업 안전을 보장하지는 않습니다. 읽기 전용 요청부터 시작하고 Tool 인수와 외부 시스템의 실제 변경 내용을 검증한 뒤 권한을 확대하세요.
다음 글에서는 Figma MCP를 사용해 디자인 컨텍스트를 코딩 에이전트에 연결하는 방법을 다룹니다.
🔗 MCP 완전정복 시리즈
참고: OpenAI 공식 Codex MCP 문서, OpenAI 공식 Codex Config basics, OpenAI 공식 Codex CLI 문서, OpenAI 공식 Linear 연동 안내
확인일: 2026-09-23 · Codex CLI 명령, 설정 키와 앱 화면은 업데이트될 수 있으므로 실제 연결 전 최신 OpenAI 공식 문서를 확인하세요.