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

Model Context Protocol

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

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

ChatGPT 웹은 플러그인이 제공하는 원격 MCP 기반 도구를 사용할 수 있습니다. 로컬 Codex 클라이언트도 MCP 서버에 직접 연결하고 구성을 공유할 수 있습니다.

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

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

지원되는 MCP 기능

  • STDIO 서버: 로컬 프로세스로 실행되는 서버입니다(명령으로 시작).
    • 환경 변수
  • Streamable HTTP 서버: 주소를 통해 액세스하는 서버입니다.
    • Bearer 토큰 인증
    • 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(선택 사항): 구성된 Bearer 토큰과 권한 부여 헤더 다음에 시도할 인증입니다. 저장된 MCP OAuth 자격 증명을 사용하려면 oauth(기본값)을 사용합니다. 신뢰할 수 있는 자사 ChatGPT 출처에 현재 ChatGPT 세션을 사용하고 저장된 OAuth를 대체 수단으로 사용하려면 chatgpt을 사용합니다.
  • bearer_token_env_var(선택 사항): Authorization으로 전송할 Bearer 토큰의 환경 변수 이름입니다.
  • http_headers(선택 사항): 헤더 이름과 정적 값의 매핑입니다.
  • env_http_headers(선택 사항): 헤더 이름과 환경 변수 이름의 매핑입니다(값은 환경에서 가져옴).

확인되는 자격 증명 소스가 없으면 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(선택 사항): 도구별 승인 동작 재정의입니다.

OAuth 공급자가 고정 콜백 포트를 요구하는 경우 config.toml에서 최상위 mcp_oauth_callback_port을 설정합니다. 설정하지 않으면 Codex는 임시 포트에 바인딩합니다.

MCP OAuth 흐름에서 특정 콜백 URL(예: 원격 Devbox 인그레스 URL 또는 사용자 지정 콜백 경로)을 사용해야 한다면 mcp_oauth_callback_url을 설정합니다. Codex는 이 값을 기본 콜백 URL로 사용한 다음 서버별 콜백 ID를 추가하여 로그인 중 전송할 OAuth redirect_uri을 생성합니다. 기본 호스트나 경로만 접미사 없이 등록하지 말고, 추가된 콜백 ID와 구성된 경로, 쿼리 또는 포트를 포함한 전체 파생 redirect_uri을 OAuth 공급자에 등록하세요. 로컬 콜백 URL(예: localhost)은 로컬 인터페이스에 바인딩되고, 로컬이 아닌 콜백 URL은 콜백이 호스트에 도달할 수 있도록 0.0.0.0에 바인딩됩니다.

MCP 서버가 scopes_supported을 알리면 Codex는 OAuth 로그인 중 서버가 알린 해당 범위를 우선합니다. 그렇지 않으면 Codex는 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"

플러그인이 제공하는 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"

유용한 MCP 서버 예시

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

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