ChatGPT 문서
한국어
문의 goolvyouyou@gmail.com

Model Context Protocol

Model Context Protocol

Codex가 서드 파티 도구와 컨텍스트에 액세스할 수 있도록 지원

Model Context Protocol(MCP)은 모델을 도구 및 컨텍스트와 연결합니다. 이를 사용해 ChatGPT 또는 Codex가 서드 파티 문서에 액세스하거나 브라우저 또는 Figma 같은 개발자 도구와 상호 작용하도록 할 수 있습니다.

ChatGPT 웹은 플러그인이 제공하는 원격 MCP 기반 도구를 사용할 수 있습니다. 플러그인을 설치하면 Chat과 Work에서 번들로 제공되는 커넥터와 원격 MCP 도구를 사용할 수 있습니다. Plugins 탭을 열어 사용 가능한 도구를 둘러보고 관리하세요. 로컬 Codex 클라이언트도 MCP 서버에 직접 연결하고 구성을 공유할 수 있습니다.

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

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

지원되는 MCP 기능

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

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

Codex를 MCP 서버에 연결하기

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

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

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

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

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

config.toml로 구성하기

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

구성 파일에서 각 MCP 서버를 [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 서버를 기다리는 시간을 제어합니다. 기본값은 1000 밀리초입니다. 각 서버의 startup_timeout_sec만큼 기다리려면 0으로 설정합니다. 필수 서버에는 계속 해당 서버의 시작 제한 시간이 적용됩니다.

OAuth 클라이언트 등록 및 콜백

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

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

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 구성과 인증 서버 메타데이터에 따라 달라집니다.

OAuth 구성 발급자 지원 사용되는 콜백
callback_url(client_id 없음) 지원됨 구성된 콜백이 클라이언트 등록에 사용됩니다.
callback_url(client_id 없음) 지원되지 않음 구성된 콜백에 서버별 콜백 ID를 추가하여 클라이언트 등록에 사용합니다.
client_id 및 callback_url 지원됨 구성된 콜백을 재사용하며, 인증 응답에 일치하는 iss가 포함되어야 합니다.
client_id 및 올바른 콜백 ID로 끝나는 callback_url 지원되지 않음 구성된 콜백을 변경 없이 재사용합니다.
client_id 및 올바른 콜백 ID가 없는 callback_url 지원되지 않음 구성된 콜백을 무시합니다. Codex는 mcp_oauth_callback_url 설정을 사용하며, 설정되지 않은 경우 http://127.0.0.1/callback에 콜백 ID를 추가하여 사용합니다.
client_id(구성된 callback_url 없음) 지원 여부 무관 Codex는 전역 또는 기본 콜백에 서버별 콜백 ID를 추가하여 사용합니다.

대체 동작은 저장된 콜백 URL을 수정하지 않습니다. Codex는 경로와 쿼리 문자열을 포함한 MCP 서버 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의 형식이 잘못되었거나 메타데이터 발급자 없이 발급자 지원만 알려진 경우에도 복구 불가능한 실패로 처리됩니다. 자세한 내용은 사용자 인증을 참조하세요.

MCP 서버가 scopes_supported 값을 알리면 Codex는 OAuth 로그인 중 서버가 알린 해당 범위를 우선합니다. 그렇지 않으면 Codex는 config.toml에 구성된 범위를 대체 수단으로 사용합니다.

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는 MCP 서버별로 ChatGPT에서 호스팅되는 메타데이터 문서를 사용합니다:

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

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

안정적인 공유 CIMD 문서에 대한 지원은 현재 개발 중이며 곧 제공될 예정입니다:

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

권한 부여 서버가 authorization_response_iss_parameter_supported: true로 알리고, 메타데이터에 유효한 issuer를 제공하며, 권한 부여 응답에 일치하는 iss를 포함하는 경우 Codex는 공유 /callback 경로가 있는 안정적인 문서를 사용합니다. 발급자에 바인딩된 응답을 지원하지 않는 서버에서는 계속 콜백별 문서를 사용합니다.

한 번의 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 서버

설치된 플러그인은 플러그인 매니페스트에 MCP 서버를 포함할 수 있습니다. 이러한 서버는 플러그인에서 시작되므로 사용자 구성에서 전송 명령을 설정하지 않습니다. 사용자 구성에서는 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 서버도 .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 서버에는 다른 MCP 서버와 동일한 콜백 선택 규칙이 적용됩니다. 플러그인이 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 서버 예시

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

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