Model Context Protocol(MCP)

Model Context Protocol(MCP)는 모델이 외부 도구와 컨텍스트를 일관된 방식으로 사용할 수 있게 해 주는 표준 프로토콜입니다. Codex에 MCP 서버를 연결하면 서드파티 개발 문서를 검색하게 하거나, 브라우저와 Figma 같은 개발 도구를 조작하게 하거나, 팀 내부 시스템에서 필요한 정보를 가져오게 만들 수 있습니다.

MCP 서버는 Codex와 외부 시스템 사이에 놓이는 어댑터라고 보면 됩니다. Codex는 MCP 서버가 제공하는 도구, 리소스, 프롬프트를 발견하고 사용할 수 있고, 서버는 각 외부 서비스에 맞는 인증과 API 호출을 처리합니다. 이 구조 덕분에 Codex 자체를 매번 수정하지 않아도 새로운 도구를 연결할 수 있습니다.

MCP 용어로는 Codex가 host, Codex 안에서 서버와 연결을 유지하는 부분이 client, 외부 도구나 데이터 소스를 감싸는 쪽이 server입니다. 사용자가 직접 설정하는 대상은 대부분 MCP 서버입니다.

Codex는 CLI와 IDE 확장 모두에서 MCP 서버를 지원합니다.

MCP가 필요한 경우

Codex는 기본적으로 현재 프로젝트 파일과 터미널 명령을 중심으로 작업합니다. 하지만 실제 개발 업무에서는 저장소 밖의 정보가 필요한 경우가 많습니다. 예를 들어 최신 라이브러리 문서, Figma 디자인, GitHub 이슈, Sentry 로그, 사내 지식 저장소, 브라우저 상태 같은 정보는 프로젝트 폴더 안에 들어 있지 않습니다.

이런 외부 맥락을 Codex가 직접 다룰 수 있게 만드는 방법이 MCP입니다. MCP 서버는 다음과 같은 기능을 노출할 수 있습니다.

Tools: Codex가 실행할 수 있는 작업입니다. 예를 들어 브라우저 열기, 로그 검색, 이슈 조회 같은 기능이 여기에 해당합니다.
Resources: Codex가 읽을 수 있는 데이터입니다. 문서, 파일 목록, API 응답처럼 컨텍스트로 활용할 수 있는 정보입니다.
Prompts: 반복해서 사용할 수 있는 프롬프트 템플릿입니다.

MCP를 연결할 때는 서버가 어떤 도구를 제공하는지, 그 도구가 읽기 전용인지 실행 권한을 갖는지 확인해야 합니다. 특히 원격 서비스에 쓰기 작업을 수행하거나 민감한 로그와 토큰을 읽을 수 있는 서버는 신뢰할 수 있는 환경에서만 사용하는 것이 좋습니다.

지원되는 MCP 기능

Codex는 다음 유형의 MCP 서버를 사용할 수 있습니다.

STDIO 서버: 로컬 프로세스로 실행되는 서버입니다. 지정한 명령으로 서버를 시작하고, 표준 입출력을 통해 Codex와 통신합니다.
- 환경 변수 설정
Streamable HTTP 서버: URL로 접근하는 서버입니다. 로컬 또는 원격 주소에서 실행될 수 있습니다.
- Bearer 토큰 인증
- OAuth 인증. OAuth를 지원하는 서버는 codex mcp login <server-name>으로 로그인할 수 있습니다.

STDIO 서버는 로컬 개발 도구나 npx로 실행하는 문서 서버를 붙일 때 자주 사용합니다. Streamable HTTP 서버는 이미 실행 중인 서비스, 원격 MCP 서버, 브라우저나 SaaS 도구가 제공하는 MCP 엔드포인트를 연결할 때 적합합니다.

Codex에 MCP 서버 연결하기

Codex는 MCP 설정을 다른 Codex 설정과 함께 config.toml에 저장합니다. 기본 위치는 ~/.codex/config.toml입니다. 신뢰된 프로젝트에서는 프로젝트 단위 설정인 .codex/config.toml에 MCP 서버를 지정할 수도 있습니다.

CLI와 IDE 확장은 같은 설정 파일을 공유합니다. 한 번 MCP 서버를 설정해 두면 CLI에서 Codex를 실행하든 IDE 확장을 사용하든 같은 서버 구성을 다시 사용할 수 있습니다.

MCP 서버를 설정하는 방법은 두 가지입니다.

CLI 사용: codex mcp 명령으로 서버를 추가하고 관리합니다.
config.toml 직접 편집: ~/.codex/config.toml 또는 신뢰된 프로젝트의 .codex/config.toml을 수정합니다.

CLI로 설정하기

MCP 서버 추가하기

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

예를 들어 개발자 문서를 검색할 수 있는 무료 MCP 서버인 Context7을 추가하려면 다음 명령을 실행합니다.

codex mcp add context7 -- npx -y @upstash/context7-mcp

이 명령은 context7이라는 이름으로 STDIO MCP 서버를 등록합니다. -- 뒤에 오는 부분은 실제 서버를 시작하는 명령입니다. 위 예시에서는 npx가 @upstash/context7-mcp 패키지를 실행합니다.

다른 CLI 명령

사용 가능한 MCP 명령을 모두 보려면 다음 명령을 실행합니다.

codex mcp --help

터미널 UI(TUI)

codex TUI 안에서는 /mcp를 입력해 현재 활성화된 MCP 서버를 확인할 수 있습니다.

config.toml로 설정하기

MCP 서버 옵션을 더 세밀하게 제어하려면 ~/.codex/config.toml 또는 프로젝트 단위 .codex/config.toml을 직접 편집합니다. IDE 확장에서는 톱니바퀴 메뉴에서 MCP settings > Open config.toml을 선택하면 설정 파일을 열 수 있습니다.

설정 파일에서는 각 MCP 서버를 [mcp_servers.<server-name>] 테이블로 정의합니다. <server-name>은 Codex 안에서 해당 서버를 식별하는 이름입니다.

STDIO 서버

command (필수): 서버를 시작하는 명령입니다.
args (선택): 서버 명령에 전달할 인수입니다.
env (선택): 서버 프로세스에 설정할 환경 변수입니다.
env_vars (선택): Codex 환경에서 허용하고 서버로 전달할 환경 변수입니다.
cwd (선택): 서버를 시작할 작업 디렉터리입니다.
experimental_environment (선택): 사용 가능한 원격 실행 환경을 통해 STDIO 서버를 시작하려면 remote로 설정합니다.

env_vars에는 단순한 변수 이름이나, 변수를 어디에서 읽을지 지정하는 객체를 넣을 수 있습니다.

env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }]

문자열 항목과 source = "local"은 Codex의 로컬 환경에서 값을 읽습니다. source = "remote"는 원격 실행 환경에서 값을 읽으며, 원격 MCP STDIO가 필요합니다.

Streamable HTTP 서버

url (필수): 서버 주소입니다.
bearer_token_env_var (선택): Authorization 헤더로 보낼 Bearer 토큰이 들어 있는 환경 변수 이름입니다.
http_headers (선택): 헤더 이름과 고정값의 매핑입니다.
env_http_headers (선택): 헤더 이름과 환경 변수 이름의 매핑입니다. 실제 값은 환경 변수에서 읽습니다.

기타 설정 옵션

startup_timeout_sec (선택): 서버 시작 제한 시간입니다. 단위는 초이며 기본값은 10입니다.
tool_timeout_sec (선택): 서버가 도구를 실행할 때의 제한 시간입니다. 단위는 초이며 기본값은 60입니다.
enabled (선택): 서버 설정을 삭제하지 않고 비활성화하려면 false로 설정합니다.
required (선택): true로 설정하면 이 서버가 초기화되지 않을 때 Codex 시작을 실패로 처리합니다.
enabled_tools (선택): 사용할 도구의 허용 목록입니다.
disabled_tools (선택): 사용할 수 없는 도구의 차단 목록입니다. enabled_tools가 적용된 뒤에 다시 적용됩니다.

OAuth 공급자가 고정된 콜백 포트를 요구한다면 config.toml 최상위에 mcp_oauth_callback_port를 설정합니다. 이 값을 설정하지 않으면 Codex는 임시 포트를 사용합니다.

MCP OAuth 흐름에서 특정 콜백 URL이 필요하다면 mcp_oauth_callback_url을 설정합니다. 예를 들어 원격 Devbox ingress URL이나 커스텀 콜백 경로를 써야 하는 경우가 여기에 해당합니다. Codex는 이 값을 OAuth redirect_uri로 사용하면서, 콜백 리스너 포트에는 mcp_oauth_callback_port를 계속 사용합니다. localhost 같은 로컬 콜백 URL은 로컬 인터페이스에 바인딩되고, 로컬이 아닌 콜백 URL은 콜백이 호스트에 도달할 수 있도록 0.0.0.0에 바인딩됩니다.

MCP 서버가 scopes_supported를 알리면 Codex는 OAuth 로그인 중 서버가 알린 scope를 우선 사용합니다. 그렇지 않으면 config.toml에 설정된 scope로 대체합니다.

config.toml 예시

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

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

# MCP OAuth 콜백 재정의 옵션(`codex mcp login`에서 사용)
mcp_oauth_callback_port = 5555
mcp_oauth_callback_url = "https://devbox.example.internal/callback"

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

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"] # enabled_tools 적용 후 다시 적용됨
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true

유용한 MCP 서버 예시

MCP 서버 생태계는 계속 커지고 있습니다. 다음은 개발 작업에서 자주 쓰이는 예시입니다.

OpenAI Docs MCP: OpenAI 개발자 문서를 검색하고 읽을 수 있습니다.
Context7: 최신 개발자 문서에 연결할 수 있습니다.
Figma Local 및 Remote: Figma 디자인에 접근할 수 있습니다.
Playwright: Playwright를 사용해 브라우저를 제어하고 검사할 수 있습니다.
Chrome Developer Tools: Chrome을 제어하고 검사할 수 있습니다.
Sentry: Sentry 로그에 접근할 수 있습니다.
GitHub: git만으로는 다루기 어려운 pull request, issue 같은 GitHub 기능을 관리할 수 있습니다.

처음 MCP를 도입한다면 읽기 전용 문서 서버부터 연결해 보는 것이 안전합니다. 이후 팀 워크플로에 맞춰 디자인 도구, 이슈 트래커, 관측 도구처럼 더 강한 권한이 필요한 서버를 단계적으로 추가하는 편이 좋습니다.