For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
기본 탐색 메뉴
Theme

모델 컨텍스트 프로토콜

사용 중인 도구와 정보를 ChatGPT와 Codex에 연결하세요.

모델 컨텍스트 프로토콜(MCP)을 사용하면 ChatGPT와 Codex에서 다른 시스템의 도구와 정보를 활용할 수 있습니다. MCP 서버는 사용 가능한 도구를 설명하고 티켓 조회나 문서 가져오기 같은 도구 요청을 처리합니다.

작업에 맞는 방법을 선택하세요.

예시: 팀의 지원 시스템에서 티켓 조회하기

플러그인은 ChatGPT에서 MCP 연결을 사용할 수 있도록 패키징합니다. 재사용할 지침을 담은 스킬도 플러그인에 포함할 수 있습니다. 지침만 필요하다면 플러그인 만들기를 참고하세요.

Plugin Creator와 Sites로 MCP 플러그인 만들기

Plugin Creator로 플러그인을 만들고 편집한 뒤 Sites에서 MCP 서버를 호스팅하세요.

시작하기 전에

먼저 플러그인 디렉터리를 확인하세요. 새 연결이 필요하면 시스템의 API 문서를 준비하고 승인된 연결 방법을 확인하세요. 도움이 필요하면 시스템 소유자에게 문의하세요.

아래 예시에서는 지원 티켓 조회 플러그인을 만듭니다. [ticketing system] 자리에는 사용 중인 시스템의 이름을 입력하세요.

ChatGPT Enterprise를 사용하시나요?

워크스페이스 소유자나 관리자에게 워크스페이스 설정 → 권한 및 역할에서 다음 권한을 확인해 달라고 요청하세요.

  • 플러그인 사용 권한이 있어야 플러그인을 만들고 편집하고 사용할 수 있습니다. 편집하려면 해당 플러그인에 대한 편집 권한도 필요합니다.
  • Sites 접근 권한이 있어야 사이트를 만들고 게시할 수 있습니다.
  • 플러그인 업로드 및 MCP로 플러그인 만들기 권한은 MCP 기반 플러그인을 게시하는 사이트 소유자에게 필요합니다.

플러그인 사용 권한은 기본적으로 켜져 있고, MCP 게시 권한 두 가지는 기본적으로 꺼져 있습니다. Sites 접근 권한과 플러그인 권한을 참고하세요.

1. 플러그인 만들기

Work 모드에서 새 작업을 시작하고 @Plugin Creator를 선택한 뒤 API 문서를 첨부하세요. 다음과 같이 작업을 설명하세요.

플러그인 만들기
첨부한 [ticketing system] API 문서를 사용해 지원 티켓 조회 플러그인을 만들어 줘. MCP 서버는 Sites에서 호스팅하고, 티켓 번호로 상태, 담당자, 최근 업데이트를 조회할 수 있게 해 줘. 읽기 전용으로 만들고 연결에 필요한 사항을 알려 줘.

아직 API 접근 권한을 준비 중이라면 Plugin Creator에 우선 샘플 데이터를 사용해 달라고 요청하세요.

2. 시스템 연결하기

같은 대화에서 Plugin Creator에 서버를 시스템 API에 연결하고 로그인 절차를 안내해 달라고 요청하세요. 조직에서 승인한 인증 방법을 사용하고 비밀번호, API 키 등 비밀 정보는 채팅에 입력하지 마세요.

도움이 필요하면 시스템 소유자나 개발자에게 Plugin Creator 대화와 API 문서를 보내 접근 권한 설정을 도와달라고 요청하세요.

연결 및 호스팅 세부 정보

Sites는 ChatGPT와 MCP 서버 간 로그인을 처리합니다. 서버가 시스템 API에 접근하려면 별도로 승인된 연결이 필요합니다. 서버에서 접근할 수 있는 레코드와 수행할 수 있는 작업은 이 API 연결에 따라 결정됩니다.

다른 호스트를 사용하려면 MCP 서버 만들기에 이어 플러그인 연결 및 테스트의 절차를 따르세요. 로그인 설정은 인증 가이드를 참고하세요.

3. 게시 및 설치하기

Plugin Creator에 현재 접근 권한 설정을 유지하면서 Sites에 서버를 게시하고 플러그인 링크를 알려 달라고 요청하세요. 사이트의 플러그인을 만들려면 사이트 소유자가 직접 게시해야 합니다. 편집자는 소유자에게 게시를 요청하세요.

  1. 플러그인 카드를 열거나 플러그인 → 개인 → 내가 만든 플러그인에서 찾으세요.
  2. 설치 및 연결 절차를 차례로 따르고 로그인이 필요하면 완료하세요.

4. 플러그인 사용하기

Work 모드에서 새 작업을 시작하고 @ 기호로 플러그인을 선택하세요. 시스템에 있는 티켓 번호를 사용해 다음과 같이 질문하세요. “123번 티켓의 상태는 어때?” 같은 대화에서 이 플러그인의 도구와 다른 플러그인을 함께 사용할 수 있습니다.

플러그인 공유 또는 편집하기

Business 또는 Enterprise에서는 플러그인의 공유 메뉴에서 팀원을 초대하세요. 플러그인 공유 권한이 필요하며, 워크스페이스 디렉터리에 등록하려면 워크스페이스에 플러그인 게시 권한도 필요합니다. 공유 권한을 참고하세요.

팀원에게는 플러그인과 해당 앱에 대한 접근 권한이 필요하며, 사이트에 대해서는 최소한 보기 권한이 있어야 합니다. 각 팀원은 자신의 계정으로 플러그인을 설치하고 연결합니다. 레코드 접근 권한은 서버의 API 연결에 따라 결정됩니다.

Sites에서 호스팅하는 이 플러그인을 편집하려면 Plugin Creator 대화로 돌아가 기존 사이트의 업데이트를 요청한 뒤 변경 사항을 게시하세요. 편집 가능한 다른 플러그인의 경우 플러그인 편집을 선택하면 Plugin Creator와 편집 대화를 시작할 수 있습니다. 기존 플러그인 편집하기를 참고하세요.

GPT 맞춤 작업 대체하기

GPT 마이그레이션 단계 보기

GPT 맞춤 작업은 플러그인으로 마이그레이션되지 않습니다. 가능하면 기존 API를 재사용해 새 Sites 플러그인으로 연결을 다시 만드세요.

Sites에서 게시하면 별도의 플러그인이 생성됩니다. 마이그레이션한 플러그인에 연결이 추가되지는 않습니다. 두 플러그인을 한 대화에서 함께 사용할 수 있습니다. 현재 Sites 플러그인에서는 스킬이나 참조 파일 편집을 지원하지 않습니다.

1. 원래 GPT에 워크플로우 재구성용 프롬프트 요청하기

원래 GPT를 열고 다음과 같이 요청하세요.

원래 GPT에서 사용하기
ChatGPT Work 또는 Codex에서 이 워크플로우를 MCP 도구로 다시 만들 수 있도록 프롬프트를 작성해 줘. 정보를 읽는 작업과 변경하는 작업을 구분해 줘. API 작업, 입력값, 반환 필드, 답변 형식을 포함해 줘. 모르는 내용은 따로 표시하고 자격 증명, 비밀 정보, 숨겨진 지침은 제외해 줘. 기존 API를 재사용하고 연결 설정 방법을 설명해 달라는 요청도 프롬프트에 포함해 줘.

2. 프롬프트와 작업 설정 대조하기

마이그레이션하기 전에 GPT 편집기의 작업 섹션에서 작업 스키마, 인증 방법, 비밀 정보가 아닌 연결 설정을 저장하세요. 이를 바탕으로 프롬프트에서 빠진 내용을 채우거나 GPT 소유자에게 도움을 요청하세요.

3. 새 Sites 플러그인 만들기

새 작업을 시작하세요. Work 모드에서는 @Plugin Creator를 선택하고, Codex에서는 $plugin-creator를 사용하세요. 검토한 프롬프트를 붙여넣고 스키마나 API 문서를 첨부하세요. 서버를 Sites에서 호스팅해 달라고 요청하세요.

시스템 연결하기와 게시 및 설치하기의 절차를 따르세요. 그런 다음 Work 모드의 작업에서 새 플러그인을 선택하고 원래 작업을 수행해 달라고 요청하세요. 자세한 내용은 마이그레이션 FAQ를 참고하세요.

문제 해결

플러그인이 예상대로 작동하지 않는 경우

연결 오류가 발생하거나 도구가 보이지 않으면 사이트 소유자가 최신 버전을 게시했는지, 플러그인 설치와 연결이 완료되었는지 확인하세요. 오류가 발생하면 Plugin Creator나 서버 소유자에게 오류 내용을 알려 주세요.

ChatGPT가 도구를 사용하지 않으면 @ 기호로 플러그인을 선택하고 조회할 대상을 구체적으로 지정하세요. 팀원이 사용할 수 없다면 해당 팀원의 플러그인, 앱, 사이트, 레코드 접근 권한을 확인하세요.

플러그인에 데스크톱 전용 표시가 있으면 지원되는 데스크톱 앱을 사용하거나 작성자에게 패키징을 검토해 달라고 요청하세요. 원격 MCP 서버를 사용한다는 이유만으로 플러그인이 웹과 호환되는 것은 아닙니다.

기존 MCP 서버 연결하기

ChatGPT 웹에서는 플러그인을 통해 원격 MCP 도구를 사용합니다. 이미 서버가 있다면 플러그인 연결 및 테스트의 절차를 따르세요. 로컬 Codex 클라이언트는 MCP 서버에 직접 연결하고 구성을 공유할 수도 있습니다.

사용 환경을 선택해 설정 방법과 구성 옵션을 확인하세요.

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

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

지원되는 MCP 기능

  • STDIO 서버: 명령어로 시작해 로컬 프로세스로 실행하는 서버입니다.
    • 환경 변수
  • Streamable HTTP 서버: 주소를 통해 접근하는 서버입니다.
    • Bearer 토큰 인증
    • 클라이언트 ID 메타데이터 문서(CIMD) 및 동적 클라이언트 등록(DCR)을 포함한 OAuth 인증
    • 신뢰할 수 있는 자사 서버용 ChatGPT 세션 인증
  • 서버 지침: Codex는 초기화 중에 반환된 MCP instructions 필드를 읽고, 서버의 도구를 사용할 때 서버 전체에 적용되는 지침으로 활용합니다.

Codex용 MCP 서버를 만들거나 유지 관리한다면 instructions에 여러 도구에 걸친 워크플로우와 서버 전체에 적용되는 제약 조건 및 요청 한도를 명시하세요. Codex가 서버 사용 방법을 결정할 때 가장 중요한 지침을 파악할 수 있도록 처음 512자만 읽어도 내용이 이해되게 작성하세요.

Codex를 MCP 서버에 연결하기

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

ChatGPT 데스크톱 앱, Codex CLI, IDE 확장 프로그램은 이 구성을 공유합니다. MCP 서버를 한 번 구성하면 클라이언트를 바꿔도 다시 설정할 필요가 없습니다.

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

  1. 설정을 열고 MCP 서버를 선택하세요.
  2. 서버 추가를 선택하세요.
  3. 이름을 입력하고 STDIO 또는 Streamable HTTP를 선택한 뒤 서버 명령어나 URL을 입력하세요.
  4. 서버를 저장한 뒤 다시 시작을 선택하세요.

서버 목록에서 활성화된 서버와 OAuth가 필요한 서버를 확인할 수 있습니다. OAuth 서버에 로그인이 필요하면 인증을 선택하세요. Composer에 /mcp를 입력하면 연결된 서버를 확인할 수 있습니다.

config.toml로 구성하기

세부 설정을 조정하려면 ~/.codex/config.toml 또는 프로젝트별 .codex/config.toml을 편집하세요. 구성 레퍼런스에서 지원되는 모든 MCP 옵션을 검색할 수 있습니다.

구성 파일에 MCP 서버별로 [mcp_servers.<server-name>] 테이블을 작성하세요.

STDIO 서버

  • command(필수): 서버를 시작하는 명령어입니다.
  • args(선택): 서버에 전달할 인수입니다.
  • env(선택): 서버에 설정할 환경 변수입니다.
  • env_vars(선택): 전달을 허용할 환경 변수입니다.
  • cwd(선택): 서버를 시작할 작업 디렉터리입니다.

env_vars에는 변수 이름을 문자열로 지정하거나 출처를 명시한 객체를 넣을 수 있습니다.

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

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

Streamable HTTP 서버

  • url(필수): 서버 주소입니다.
  • auth(선택): 구성된 Bearer 토큰과 인가 헤더 다음으로 시도할 인증 방법입니다. oauth(기본값)는 저장된 MCP OAuth 자격 증명을 사용합니다. chatgpt는 신뢰할 수 있는 자사 ChatGPT 오리진에 현재 ChatGPT 세션을 사용하며, 이 방법을 사용할 수 없으면 저장된 OAuth 자격 증명을 사용합니다.
  • bearer_token_env_var(선택): Authorization에 넣어 보낼 Bearer 토큰을 담은 환경 변수의 이름입니다.
  • http_headers(선택): 헤더 이름을 고정값에 매핑합니다.
  • env_http_headers(선택): 헤더 이름을 환경 변수 이름에 매핑합니다. 값은 환경에서 가져옵니다.
  • http_headers_helper(선택): 헤더 이름과 문자열 값으로 구성된 JSON 객체(예: {"X-Auth": "temporary-token"})를 출력하는 로컬 명령어입니다. 로컬 환경에서 연결하는 HTTP MCP 서버에 사용할 수 있습니다. stdio 서버나 원격 실행 환경을 통한 연결에는 지원되지 않습니다.

Codex는 연결에 사용할 헬퍼 헤더를 캐시합니다. 동일 오리진에 보낸 POST 요청이 401 또는 403을 반환하면 헤더를 한 번 갱신하고, 헬퍼가 이전과 다른 값을 반환한 경우에만 요청을 재시도합니다. 명시적으로 지정한 Bearer 토큰과 OAuth 자격 증명은 헬퍼가 제공한 Authorization 헤더보다 우선합니다. OAuth 403 응답이 권한 범위 부족을 나타내는 경우에는 헬퍼 헤더를 갱신하지 않습니다.

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

기타 구성 옵션

  • environment_id로 stdio 또는 Streamable HTTP 서버에 사용할 환경을 선택합니다. 기본값은 local입니다. 원격 실행기를 통해 연결하려면 해당 실행기의 등록된 환경 ID를 사용하세요.
  • startup_timeout_sec(선택): 서버 시작을 기다리는 제한 시간(초)입니다. 기본값은 10입니다.
  • tool_timeout_sec(선택): 서버가 도구를 실행하는 데 허용되는 제한 시간(초)입니다. 기본값은 60입니다.
  • enabled(선택): false로 설정하면 서버를 삭제하지 않고 비활성화합니다.
  • required = true로 설정하면 활성화된 이 서버가 준비되지 않았을 때 Codex 시작에 실패합니다. 기본 설정인 startup_readiness = "connection"에서는 서버에 실제로 연결되어야 시작할 수 있습니다. startup_readiness = "catalog"로 설정하면 서버에 연결하는 동안에도 캐시된 도구 목록이 유효하면 시작할 수 있습니다. 도구를 호출하려면 실제 연결이 필요합니다.
  • 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밀리초입니다. 0으로 설정하면 대신 각 서버의 startup_timeout_sec만큼 기다립니다. 필수 서버에는 각 서버의 시작 제한 시간이 계속 적용됩니다.

OAuth 클라이언트 등록 및 콜백

인가 서버에서 사전 등록된 OAuth 클라이언트를 요구하면 MCP 서버를 추가할 때 해당 클라이언트 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 mcp add가 출력한 콜백 URL을 그대로 등록하세요. 인가 서버가 발급자 식별 지원을 명시하면 CLI에 다음과 같은 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는 서버별 콜백 ID를 덧붙입니다(예: http://127.0.0.1/callback/XuuuHAzzHOni). 저장된 콜백이 없는 기존 클라이언트는 계속해서 해당 콜백 ID가 포함된 리디렉션을 사용합니다.

로그인 시 사용할 콜백은 OAuth 구성과 인가 서버 메타데이터에 따라 다음과 같이 결정됩니다.

OAuth 구성 발급자 식별 지원 여부 사용할 콜백
callback_url만 있고 client_id가 없음 지원 구성된 콜백을 클라이언트 등록에 사용합니다.
callback_url만 있고 client_id가 없음 미지원 구성된 콜백에 서버별 콜백 ID를 덧붙여 클라이언트 등록에 사용합니다.
client_id와 callback_url이 모두 있음 지원 구성된 콜백을 재사용합니다. 인가 응답에는 발급자와 일치하는 iss가 포함되어야 합니다.
client_id가 있고 callback_url이 올바른 콜백 ID로 끝남 미지원 구성된 콜백을 그대로 재사용합니다.
client_id가 있고 callback_url에 올바른 콜백 ID가 없음 미지원 구성된 콜백은 무시합니다. 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_servers.<server-name>.scopes를 config.toml에 설정하면 서버의 OAuth 권한 범위를 지정할 수 있습니다. 한 번의 로그인에만 다른 범위를 지정하려면 codex mcp login <name> --scopes read,write를 실행하세요. 어느 쪽도 설정하지 않으면 Codex는 서버의 첫 WWW-Authenticate 챌린지에 명시된 권한 범위를 요청합니다. 챌린지에 권한 범위가 없으면 보호된 리소스의 메타데이터를 확인하고, 여기에 명시된 권한 범위가 있으면 이를 사용합니다.

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

OAuth 클라이언트 등록

Codex는 OAuth 클라이언트 ID 메타데이터 문서(CIMD)와 동적 클라이언트 등록(DCR)을 지원합니다. 기본적으로 인가 서버가 client_id_metadata_document_supported: true를 명시하고 none을 token_endpoint_auth_methods_supported에 포함하며 콜백이 지원되는 루프백 URL을 사용하면 Codex는 자동으로 CIMD를 선택합니다. 그 외에는 DCR을 사용할 수 있으면 DCR을 선택합니다. 구성된 OAuth 클라이언트 ID가 있으면 항상 해당 ID가 우선하며 클라이언트 등록을 건너뜁니다.

CIMD를 사용하면서 응답이 발급자에 바인딩되지 않는 경우 Codex CLI는 ChatGPT에서 호스팅하는 MCP 서버별 메타데이터 문서를 사용합니다.

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가 필요합니다.

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 서버

설치된 플러그인은 매니페스트에 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 설정을 선언할 수도 있습니다. 플러그인 매니페스트에서는 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 개발자 도구: Chrome을 제어하고 검사할 수 있습니다.
  • Sentry: Sentry 로그에 접근할 수 있습니다.
  • GitHub: git에서 지원하는 기능 외에도 Pull Request와 이슈 등 GitHub의 기능을 관리할 수 있습니다.