Model Context Protocol

ChatGPT 데스크톱 앱, Codex CLI 및 IDE 확장 프로그램은 MCP server를 지원하며 동일한 Codex 호스트의 MCP 구성을 공유합니다.

아래에서 지원되는 서버 기능은 Codex 호스트에 구성된 MCP server에 적용됩니다. 호스팅된 플러그인 도구는 기능이 다를 수 있습니다.

지원되는 MCP 기능

• STDIO 서버: 로컬 프로세스로 실행되는 서버입니다(명령으로 시작).
  • 환경 변수
• 스트리밍 가능 HTTP 서버: 주소를 통해 액세스하는 서버입니다.
  • Bearer 토큰 인증
  • Client ID Metadata Documents(CIMD) 및 Dynamic Client Registration(DCR)을 포함한 OAuth 인증
  • 신뢰할 수 있는 자사 서버를 위한 ChatGPT 세션 인증
• 서버 지침: Codex는 초기화 중 반환된 MCP instructions 필드를 읽고 서버 도구와 함께 서버 전체에 적용되는 지침으로 사용합니다.

Codex용 MCP server를 구축하거나 유지 관리한다면 서버 전체에 적용되는 도구 간 워크플로, 제약 조건 및 속도 제한에 instructions 필드를 사용하세요. Codex가 서버 사용 방법을 결정할 때 가장 중요한 지침을 활용할 수 있도록 처음 512자는 그 자체로 완결되게 작성하세요.

Codex를 MCP server에 연결하기

Codex는 다른 Codex 구성 설정과 함께 config.toml에 MCP 구성을 저장합니다. 기본 위치는 ~/.codex/config.toml이지만 .codex/config.toml을 사용해 MCP server의 범위를 프로젝트로 한정할 수도 있습니다(신뢰할 수 있는 프로젝트만 해당).

ChatGPT 데스크톱 앱, Codex CLI 및 IDE 확장 프로그램은 이 구성을 공유합니다. MCP server를 구성한 후에는 설정을 다시 하지 않고도 이러한 클라이언트 간에 전환할 수 있습니다.

ChatGPT 데스크톱 앱에서 구성하기

1. Settings 를 열고 MCP servers 를 선택합니다.
2. Add server 를 선택합니다.
3. 이름을 입력하고 STDIO 또는 Streamable HTTP 를 선택한 다음 서버의 명령 또는 URL을 제공합니다.
4. 서버를 저장한 다음 Restart 를 선택합니다.

서버 목록에는 활성화된 서버와 OAuth가 필요한 서버가 표시됩니다. OAuth 서버에 로그인이 필요하면 Authenticate 를 선택합니다. 작성란에 /mcp 명령을 입력하여 연결된 서버를 확인할 수 있습니다.

ChatGPT 웹에서 MCP 기반 도구 사용하기

다른 기기에서 Work Cloud의 로컬 컴퓨터 액세스를 사용해 대화를 이어가더라도 플러그인이 설치되거나 연결된 계정에 대한 액세스 권한이 부여되지는 않습니다.

Work Cloud의 로컬 컴퓨터 액세스에서는 Agent Security의 엔터프라이즈 mcp_servers TOML 요구 사항이 로컬 실행기에 적용됩니다. 클라우드 컨테이너에는 Work Cloud 정책이 그대로 적용됩니다. 로컬 MCP server와 전송 방식은 클라우드에서 사용할 수 없을 수 있으므로 연결과 인증을 별도로 확인하세요.

Work Cloud의 로컬 컴퓨터 액세스에서 엔터프라이즈 훅을 사용할 때는 다음 사항을 확인하세요.

• 엔터프라이즈 훅. 워크스페이스에서 활성화된 경우, Work Cloud의 로컬 컴퓨터 액세스는 지원되는 수명 주기 및 도구 이벤트에 대해 클라우드 코디네이터(오케스트레이터)에서 실행되는 관리자 정의 MCP 훅을 지원합니다. 도구가 로컬에서 실행되더라도 클라우드 오케스트레이션에서는 명령 훅과 로컬 구성 또는 플러그인의 훅이 지원되지 않습니다.
• 감사. 이러한 훅에 의존하기 전에 콜백 연결을 테스트하고, 수신하는 이벤트를 확인하고, 실패가 작업에 미치는 영향을 점검하세요. MCP 훅은 완전한 Compliance API 감사 추적 기록을 제공하지 않습니다.
• 제한 사항: 도구가 로컬에서 실행되더라도 클라우드 오케스트레이션에서는 명령 훅과 로컬 구성 또는 플러그인의 훅이 지원되지 않습니다. 개인 사용자에게는 이 기능의 훅 지원이 제공되지 않습니다. 오케스트레이션과 실행이 모두 로컬에서 이루어지는 경우, 기존에 지원되던 훅은 로컬 전용 Work 및 Codex 스레드에서 계속 작동합니다. 관리자는 이러한 워크플로에 대해 Agent Security에서 지원되는 관리형 훅을 계속 구성할 수 있습니다.

지원 범위는 훅과 구성 참조를 확인하세요.

호스팅된 ChatGPT Work 채팅에서 번들 커넥터와 원격 MCP 도구를 사용하려면 플러그인을 설치하세요. 설치 후 Chat과 Work에서 해당 도구를 사용할 수 있습니다. 워크스페이스 관리자는 사용할 수 있는 플러그인과 도구를 제어할 수 있습니다.

ChatGPT 웹은 로컬 Codex 구성 파일을 읽거나 로컬 Codex 명령 메뉴를 표시하지 않습니다. 사용 가능한 도구를 탐색하고 관리하려면 Plugins 탭을 여세요.

CLI로 구성하기

MCP server 추가

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

예를 들어 개발자 문서를 위한 무료 MCP server인 Context7을 추가하려면 다음 명령을 실행할 수 있습니다.

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

기타 CLI 명령

구성된 서버를 확인하려면 codex mcp list를 실행합니다. 사용 가능한 모든 MCP 명령을 확인하려면 codex mcp --help를 실행합니다. OAuth를 지원하는 서버의 경우 codex mcp login <server-name>을 실행합니다.

터미널 UI(TUI)

codex TUI에서 /mcp를 사용하여 활성 MCP server를 확인합니다.

IDE 확장 프로그램에서 구성

1. 톱니바퀴 메뉴를 연 다음 MCP servers 를 선택합니다.
2. Add server 를 선택합니다.
3. 이름을 입력하고 STDIO 또는 Streamable HTTP 를 선택한 다음 서버의 명령이나 URL을 제공합니다.
4. 서버를 저장한 다음 Restart extension 을 선택합니다.

MCP server 목록에는 활성화된 서버와 OAuth가 필요한 서버가 표시됩니다. OAuth 서버에 로그인이 필요하면 Authenticate 를 선택합니다.

config.toml로 구성하기

더 세밀하게 제어하려면 ~/.codex/config.toml 또는 프로젝트 범위의 .codex/config.toml을 편집하세요. 지원되는 모든 MCP 옵션을 검색할 수 있는 목록은 구성 참조에서 확인하세요.

구성 파일에서 각 MCP server를 [mcp_servers.<server-name>] 테이블로 구성합니다.

STDIO 서버

• command(필수): 서버를 시작하는 명령입니다.
• args(선택 사항): 서버에 전달할 인수입니다.
• env(선택 사항): 서버에 설정할 환경 변수입니다.
• env_vars(선택 사항): 허용하고 전달할 환경 변수입니다.
• 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(필수): 서버 주소입니다.
• auth(선택 사항): 구성된 전달자 토큰 및 권한 부여 헤더 다음에 시도할 인증입니다. 저장된 MCP OAuth 자격 증명을 사용하려면 oauth(기본값)을 사용합니다. 신뢰할 수 있는 자사 ChatGPT 출처에 현재 ChatGPT 세션을 사용하고 저장된 OAuth를 대체 수단으로 사용하려면 chatgpt를 사용합니다.
• bearer_token_env_var(선택 사항): Authorization으로 전송할 전달자 토큰의 환경 변수 이름입니다.
• http_headers(선택 사항): 헤더 이름을 정적 값에 매핑한 항목입니다.
• env_http_headers(선택 사항): 헤더 이름을 환경 변수 이름에 매핑한 항목입니다(값은 환경에서 가져옴).
• http_headers_helper(선택 사항): 헤더 이름과 문자열 값으로 구성된 JSON 객체를 출력하는 로컬 명령입니다(예: {"X-Auth": "temporary-token"}). 로컬 환경에서 이루어지는 HTTP MCP 연결에 지원되며, stdio 서버나 원격 실행 환경을 통해 이루어지는 연결에는 지원되지 않습니다.

Codex는 연결에 사용할 도우미 헤더를 캐시합니다. 동일 출처 POST가 401 또는 403을 반환하면 헤더를 한 번 새로 고치고, 도우미가 변경된 값을 반환하는 경우에만 다시 시도합니다. 명시적 전달자 토큰과 OAuth 자격 증명은 도우미가 제공한 Authorization 헤더보다 우선합니다. 범위가 부족하다고 보고하는 OAuth 403 응답은 도우미 새로 고침을 트리거하지 않습니다.

확인되는 자격 증명 소스가 없으면 Codex는 인증 없이 서버에 연결할 수 있습니다. MCP OAuth 로그인을 시작하려면 codex mcp login <server-name> 명령을 별도로 실행하세요.

기타 구성 옵션

• startup_timeout_sec(선택 사항): 서버 시작 제한 시간(초)입니다. 기본값: 10.
• tool_timeout_sec(선택 사항): 서버에서 도구를 실행하는 제한 시간(초)입니다. 기본값: 60.
• enabled(선택 사항): 서버를 삭제하지 않고 비활성화하려면 false로 설정합니다.
• required(선택 사항): 활성화된 이 서버를 초기화할 수 없을 때 시작이 실패하도록 하려면 true로 설정합니다.
• enabled_tools(선택 사항): 도구 허용 목록입니다.
• disabled_tools(선택 사항): 도구 거부 목록입니다(enabled_tools 이후 적용).
• default_tools_approval_mode(선택 사항): 이 서버의 도구에 적용할 기본 승인 동작입니다. 지원되는 값은 auto, prompt, writes 및 approve입니다. writes 모드에서는 읽기 전용으로 표시되지 않은 도구에 대해 승인을 요청합니다.
• tools.<tool>.approval_mode(선택 사항): 도구별 승인 동작 재정의입니다.
• tools.<tool>.output_token_limit(선택 사항): 표준 20% 직렬화 허용량을 적용하기 전, 도구 하나의 출력에 적용되는 양의 토큰 예산입니다. 해당 도구에 대한 모델의 기본 출력 잘림 예산을 재정의합니다.

최상위 mcp_optional_startup_grace_ms 설정은 Codex가 초기 도구 카탈로그를 구성할 때 선택적 MCP server를 기다리는 시간을 제어합니다. 기본값은 1000 밀리초입니다. 각 서버의 startup_timeout_sec만큼 기다리려면 0으로 설정합니다. 필수 서버에는 계속 해당 서버의 시작 제한 시간이 적용됩니다.

OAuth 클라이언트 등록 및 콜백

인증 서버에서 사전 등록된 OAuth 클라이언트를 요구하는 경우, MCP server를 추가할 때 해당 클라이언트 ID를 입력합니다.

codex mcp add example --url https://mcp.example.com --oauth-client-id my-client

기밀 클라이언트의 경우 --oauth-client-secret도 전달하세요. 시크릿은 환경 변수에서 읽어오세요:

codex mcp add example --url https://mcp.example.com --oauth-client-id my-client --oauth-client-secret "$MCP_CLIENT_SECRET"

이 옵션에는 비어 있지 않은 클라이언트 ID와 시크릿이 필요합니다. Codex는 시크릿을 mcp_servers.example.oauth.client_secret 값으로 config.toml에 저장합니다. 이 파일은 비공개로 유지하고 버전 관리에서 제외하세요.

Codex는 제공업체에 등록할 전체 콜백 URL을 표시합니다.

OAuth callback URL: http://127.0.0.1/callback

Codex는 이후 로그인에 사용할 수 있도록 클라이언트 ID와 함께 콜백을 config.toml에 저장합니다.

[mcp_servers.example]
url = "https://mcp.example.com"

[mcp_servers.example.oauth]
client_id = "my-client"
callback_url = "http://127.0.0.1/callback"

새로 추가된 사전 등록 클라이언트는 인증 서버가 authorization_response_iss_parameter_supported: true로 알리고 메타데이터 issuer를 제공하는 경우에만 고정 콜백을 사용합니다. 발급자 지원을 알리지 않으면 Codex는 http://127.0.0.1/callback/XuuuHAzzHOni와 같이 서버별 콜백 ID를 추가합니다. 저장된 콜백이 없는 기존 클라이언트는 계속해서 콜백 ID가 포함된 리디렉션을 사용합니다.

로그인 중 콜백 선택은 OAuth 구성과 인증 서버 메타데이터에 따라 달라집니다.

대체 동작은 저장된 콜백 URL을 수정하지 않습니다. Codex는 경로와 쿼리 문자열을 포함한 MCP server URL에서 콜백 ID를 파생합니다. 자동 로그인과 명시적 로그인에 동일한 선택 규칙이 적용됩니다.

사용자 지정 콜백 경로나 원격 Devbox 인그레스 URL이 필요한 경우 mcp_oauth_callback_url을 설정하세요. 새로 추가된 사전 등록 클라이언트는 제공업체가 발급자 식별을 지원하면 해당 URL을 변경 없이 사용합니다. 그렇지 않으면 구성된 URL에 서버별 콜백 ID를 추가하여 사용합니다. 항상 codex mcp add에서 표시하는 정확한 콜백을 등록하세요.

명시적 포트가 없는 http://127.0.0.1 콜백의 경우, Codex는 표시하고 저장하는 URL에서 리스너 포트를 생략한 뒤, 인가 과정에서 활성 리스너 포트를 삽입합니다. 이 치환은 localhost, IPv6 호스트, HTTPS URL 또는 이미 포트가 포함된 콜백에는 적용되지 않습니다. 인가 서버는 다음 규정에 따라 가변 루프백 포트를 허용해야 합니다. RFC 8252, 섹션 7.3.

mcp_oauth_callback_port를 설정해 고정 전역 리스너 포트를 선택하거나, mcp_servers.<server-name>.oauth.callback_port를 설정해 특정 서버의 포트를 재정의하세요. 콜백 URL에 포트를 명시해도 리스너가 구성되지는 않습니다. 직접 루프백 콜백의 경우, 명시적 포트 없이 http://127.0.0.1을 사용하거나 콜백 URL과 리스너에 동일한 포트를 명시적으로 구성하세요. 프록시를 거치는 콜백은 로컬 리스너 포트와 다른 외부 URL 포트를 의도적으로 사용할 수 있습니다. 로컬 콜백 URL은 로컬 인터페이스에 바인딩되고, 로컬이 아닌 콜백 URL은 0.0.0.0에 바인딩됩니다.

Codex는 인증 코드를 교환하기 전에 반환된 모든 iss를 검증합니다. iss가 일치하지 않으면 항상 응답을 거부합니다. 발급자 지원이 알려진 경우 iss가 누락되어도 응답을 거부합니다. 두 실패 모두 코드를 교환하거나 다른 콜백으로 대체하지 않습니다. 콜백 URL의 형식이 잘못되었거나 메타데이터 발급자 없이 발급자 지원만 알려진 경우에도 복구 불가능한 실패로 처리됩니다. 자세한 내용은 사용자 인증을 참조하세요.

서버의 OAuth 범위를 선택하려면 mcp_servers.<server-name>.scopes를 config.toml에 설정합니다. 한 번의 로그인에만 다른 범위를 적용하려면 다음을 실행합니다. codex mcp login <name> --scopes read,write. 둘 다 설정하지 않으면 Codex는 서버가 제공하는 OAuth 범위가 있을 경우 해당 범위를 사용합니다.

빈 목록(scopes = [])을 설정해도 OAuth 라이브러리가 범위를 선택할 수 있습니다. 인증 서버가 지원하는 경우 라이브러리는 offline_access도 추가할 수 있습니다.

OAuth 클라이언트 등록

Codex는 OAuth Client ID Metadata Documents(CIMD)와 Dynamic Client Registration(DCR)을 지원합니다. 기본적으로 인증 서버가 client_id_metadata_document_supported: true로 알리고, token_endpoint_auth_methods_supported에 none 값을 포함하며, 콜백이 지원되는 루프백 URL을 사용하면 Codex가 자동으로 CIMD를 선택합니다. 그렇지 않고 DCR을 사용할 수 있으면 Codex는 DCR을 사용합니다. 구성된 OAuth 클라이언트 ID는 항상 우선하며 클라이언트 등록을 건너뜁니다.

발급자에 바인딩된 응답이 없는 CIMD의 경우, Codex CLI는 ChatGPT에서 호스팅하는 MCP server별 메타데이터 문서를 사용합니다.

https://chatgpt.com/oauth/codex/<callback_id>/client.json

Codex는 MCP server URL에서 <callback_id>를 도출하여 다음과 같은 루프백 리디렉션 URI에 포함합니다: http://127.0.0.1:<port>/callback/<callback_id>. 메타데이터 문서에는 포트가 없는 해당 루프백 URI가 등록됩니다. 권한 부여 서버는 RFC 8252의 요구 사항에 따라 호스트와 경로가 정확히 일치하는 경우 로그인 시 선택된 포트를 허용해야 합니다. 사용자 지정 콜백 호스트, 경로 또는 쿼리 매개변수를 사용하려면 DCR 또는 구성된 OAuth 클라이언트 ID가 필요합니다.

Codex CLI는 고정된 공용 CIMD 문서도 지원합니다.

https://chatgpt.com/oauth/codex/client.json

Codex CLI는 인가 서버가 다음 조건을 충족할 때 공용 /callback 경로와 함께 고정 문서를 사용합니다. 인가 서버가 authorization_response_iss_parameter_supported: true 지원을 알리고, 메타데이터에 유효한 issuer를 제공하며, 인가 응답에 일치하는 iss를 포함해야 합니다. 발급자에 바인딩된 응답이 없는 서버는 콜백별 문서를 사용합니다.

한 번의 CLI 로그인에 사용할 등록 방식을 선택하려면 --oauth-client-registration 옵션을 사용합니다:

codex mcp login <server-name> --oauth-client-registration cimd
codex mcp login <server-name> --oauth-client-registration dcr

기본값은 auto입니다. 등록 방식 선택은 현재 로그인에만 적용되며 config.toml에 저장되지 않습니다.

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"

# Optional MCP OAuth callback overrides (used by `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"] # applied after enabled_tools
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true

[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"
output_token_limit = 30000

플러그인이 제공하는 MCP server

설치된 플러그인은 플러그인 매니페스트에 MCP server를 포함할 수 있습니다. 이러한 서버는 플러그인에서 시작되므로 사용자 구성에서 전송 명령을 설정하지 않습니다. 사용자 구성에서는 plugins.<plugin>.mcp_servers.<server> 아래에서 활성화/비활성화 상태와 도구 정책을 계속 제어할 수 있습니다.

[plugins."sample@test".mcp_servers.sample]
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["read", "search"]

[plugins."sample@test".mcp_servers.sample.tools.search]
approval_mode = "approve"

플러그인이 제공하는 HTTP MCP server도 .mcp.json에서 OAuth 설정을 선언할 수 있습니다. 플러그인 매니페스트는 camelCase 필드 이름인 clientId, callbackUrl 및 callbackPort 값을 사용합니다.

{
  "mcpServers": {
    "sample": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "my-pre-registered-client",
        "callbackUrl": "http://127.0.0.1/callback/registered"
      }
    }
  }
}

플러그인이 제공하는 MCP server에는 다른 MCP server와 동일한 콜백 선택 규칙이 적용됩니다. 플러그인이 clientId를 제공하고, 해당 제공업체가 발급자에 바인딩된 콜백을 지원하지 않으며, callbackUrl에 서버별 콜백 ID가 없으면 Codex는 로그인 시 해당 URL을 무시하고 mcp_oauth_callback_url 설정을 사용하며, 설정되지 않은 경우 http://127.0.0.1/callback에 콜백 ID를 추가하여 사용합니다. 구성된 callbackUrl 값은 변경되지 않습니다.

플러그인의 oauth.callbackPort는 전역 mcp_oauth_callback_port 설정을 재정의합니다. 둘 다 설정되지 않으면 Codex는 임시 포트를 선택합니다. callbackUrl에 포함된 포트는 리스너 포트를 선택하지 않습니다. 고정 포트를 사용하는 직접 루프백 콜백의 경우 두 값이 일치하도록 구성합니다.

{
  "callbackUrl": "http://127.0.0.1:4321/callback/registered",
  "callbackPort": 4321
}

원격 인그레스나 다른 프록시가 구성된 리스너로 전달하는 경우, 콜백 URL 포트와 로컬 리스너 포트를 의도적으로 다르게 설정할 수 있습니다.

유용한 MCP server 예시

MCP server 목록은 계속 늘어나고 있습니다. 다음은 자주 사용되는 몇 가지 예시입니다.

• OpenAI Docs MCP: OpenAI 개발자 문서를 검색하고 읽습니다.
• Context7: 최신 개발자 문서에 연결합니다.
• Figma 로컬 및 원격: Figma 디자인에 액세스합니다.
• Playwright: Playwright를 사용하여 브라우저를 제어하고 검사합니다.
• Chrome Developer Tools: Chrome을 제어하고 검사합니다.
• Sentry: Sentry 로그에 액세스합니다.
• GitHub: git에서 지원하는 범위를 넘어 GitHub를 관리합니다(예: pull request 및 issue).