보안 MCP 터널

보안 MCP 터널을 사용하면 방화벽에서 인바운드 포트를 열거나 서버를 인터넷에 공개하지 않고도 비공개 MCP 서버를 지원되는 OpenAI 제품에 연결할 수 있습니다. MCP 서버에 이미 접근할 수 있는 네트워크에서 tunnel-client를 실행하세요. 클라이언트가 OpenAI에 아웃바운드 HTTPS 연결을 열고 대기열에서 MCP 작업을 가져와 로컬 서버로 요청을 전달한 뒤 같은 터널로 응답을 반환합니다.

MCP 터널이란?

MCP 터널은 네트워크 내부 호스트에서 OpenAI가 호스팅하는 MCP 엔드포인트로 여는 아웃바운드 전용 연결입니다. 비공개, 온프레미스 또는 방화벽 뒤에 있는 MCP 서버를 ChatGPT, Codex, Responses API 등 지원되는 OpenAI 제품에서 호출해야 할 때 사용하세요.

보안 MCP 터널은 MCP 서버를 비공개로 유지하면서 지원되는 OpenAI 제품이 일반적인 방식으로 MCP 요청을 보낼 수 있게 합니다. tunnel-client는 OpenAI를 폴링해 작업을 가져오고 MCP 요청을 로컬 서버에 전달한 뒤 같은 터널로 응답을 반환합니다.

보안 MCP 터널을 사용할 때

• MCP 서버가 사설 네트워크, 온프레미스 환경 또는 개발자 컴퓨터에서 실행되거나 기존 접근 제어로 보호되는 경우입니다.
• MCP 서버를 공개하지 않고도 ChatGPT, Codex, Responses API 등 지원되는 OpenAI 제품에서 해당 서버를 사용하려는 경우입니다.
• 네트워크에서 tunnel-client를 실행하는 호스트가 기본적으로 api.openai.com:443으로, 제어 영역 mTLS를 구성한 경우에는 mtls.api.openai.com:443으로 아웃바운드 HTTPS 요청을 보낼 수 있고 비공개 MCP 서버에도 접근할 수 있어야 합니다.
• MCP의 기본 개념은 MCP 서버 가이드부터 살펴보세요.

작동 방식

1. 플랫폼 터널 설정에서 OpenAI가 호스팅하는 MCP 터널 엔드포인트를 만들거나 관리합니다.
2. 비공개 MCP 서버에 접근할 수 있는 네트워크에서 tunnel-client를 실행합니다.
3. tunnel-client에 터널 식별 정보와 비공개 MCP 서버 주소를 설정합니다.
4. OpenAI 제품이 OpenAI에서 호스팅하는 터널 엔드포인트로 MCP 요청을 보냅니다.
5. tunnel-client가 롱 폴링으로 대기 중인 작업을 가져와 각 JSON-RPC 요청을 비공개 MCP 서버에 전달하고 터널로 응답을 다시 보냅니다.

비공개 MCP 서버에는 공개 리스너가 필요하지 않습니다. OpenAI가 호스팅하는 엔드포인트 덕분에 지원되는 제품은 일반적인 방식으로 MCP 요청을 보낼 수 있고, 네트워크 연결은 고객 네트워크 내부에서 시작됩니다. 커넥터가 스트리밍 결과를 요청하면 최종 응답에 앞서 서버 전송 이벤트를 터널로 전달할 수 있습니다.

시작하기 전에

다음 항목이 필요합니다.

• 터널 식별자 tunnel_id. 플랫폼 터널 설정에서 확인할 수 있습니다.
• tunnel-client용 런타임 API 키.
• tunnel-client가 네트워크 내부에서 stdio 또는 HTTP로 접근할 수 있는 MCP 서버.

권한 및 접근 제어

플랫폼 터널 권한과 ChatGPT의 사용자 지정 MCP 서버 접근 권한은 별도로 관리됩니다.

• 터널을 만들거나 편집하려면 Tunnels Read + Manage 권한이 필요합니다.
• tunnel-client를 실행하거나 앱을 만드는 중에 터널을 선택하려면 Tunnels Read + Use 권한이 필요합니다.
• 터널 권한은 플랫폼 조직 단위로 적용됩니다. 플랫폼 조직 소유자나 RBAC 관리자가 터널 역할을 부여합니다.
• ChatGPT에서 사용자 지정 MCP 서버를 추가하고 사용할 때는 워크스페이스 권한과 보안 제한이 그대로 적용됩니다. 사용자 지정 MCP 서버 추가를 참고하세요.

사용자 지정 MCP 서버를 추가하고 사용할 권한은 대상 ChatGPT 워크스페이스 관리자에게 요청하고, 터널 권한은 대상 플랫폼 조직의 소유자나 RBAC 관리자에게 요청하세요.

터널을 사용할 조직 및 워크스페이스 연결

하나의 터널에 하나 이상의 플랫폼 조직이나 ChatGPT 워크스페이스를 연결할 수 있습니다. 터널을 찾거나 사용할 수 있어야 하는 모든 조직과 워크스페이스를 연결하세요.

• 터널을 소유하거나 관리하는 플랫폼 조직을 포함하세요.
• 앱을 만들 때 터널이 목록에 표시되어야 하는 ChatGPT 워크스페이스를 포함하세요.
• Codex, Responses API 등 지원되는 제품이 다른 플랫폼 조직에서 비공개 MCP 서버를 호출한다면 해당 조직도 포함하세요.
• 같은 tunnel_id를 tunnel-client에 사용하세요. 조직이나 워크스페이스를 추가해도 새 터널이 생성되거나 비공개 MCP 서버 엔드포인트가 변경되지 않습니다.

개인 계정이라면 해당 계정의 개인 플랫폼 조직을 사용하세요. ChatGPT와 Codex에서 테스트하려면 터널에 대상 ChatGPT 워크스페이스와 Codex가 사용할 플랫폼 조직을 연결하세요. 개인 플랫폼 조직에만 연결된 터널은 Enterprise/Edu 워크스페이스에 자동으로 표시되지 않습니다.

플랫폼 조직과 ChatGPT 워크스페이스가 이미 서로 연결되어 있다면 플랫폼 터널 설정에서 터널에 누락된 조직이나 워크스페이스를 추가할 수 있습니다. 플랫폼 조직에 대응하는 ChatGPT 워크스페이스가 없는 경우처럼 엔터프라이즈 설정을 자동으로 확인할 수 없다면 OpenAI 계정 담당 팀에 문의하세요. 터널을 사용할 엔터프라이즈 계정 매핑을 검토한 후 수동으로 연결하도록 예외 처리를 요청하세요.

네트워크 요구 사항

tunnel-client에는 인터넷에서 들어오는 인바운드 연결이 필요하지 않습니다. OpenAI로 아웃바운드 HTTPS 연결을 할 수 있고 로컬에서 비공개 MCP 서버에 접근할 수 있어야 합니다.

한도

보안 MCP 터널은 터널 생성 및 커넥터의 MCP 트래픽에 다음 기본 한도를 적용합니다.

이 한도는 서비스 보호를 위한 것으로 처리량이나 지연 시간을 보장하지 않습니다. 정리 작업을 위해 대기열 기록을 보관하더라도 요청 제한 시간인 120초는 연장되지 않습니다. 터널 수 또는 트래픽 한도 상향을 요청하려면 OpenAI 지원팀에 문의하세요.

tunnel-client 설정

플랫폼 터널 설정을 열고 다운로드 링크를 사용하세요. 최신 공개 버전의 tunnel-client는 openai/tunnel-client에서도 다운로드할 수 있습니다. 운영 절차서에는 특정 버전의 URL을 고정하지 말고 항상 최신 릴리스를 가리키는 URL을 사용하세요.

바이너리가 이미 있다면 tunnel-client help quickstart부터 실행하세요. 이름을 지정한 로컬 stdio 프로필은 다음과 같이 설정합니다.

12345678910export CONTROL_PLANE_API_KEY="sk-..."

tunnel-client init \
  --sample sample_mcp_stdio_local \
  --profile local-stdio \
  --tunnel-id tunnel_0123456789abcdef0123456789abcdef \
  --mcp-command "python /path/to/server.py"

tunnel-client doctor --profile local-stdio --explain
tunnel-client run --profile local-stdio

HTTP MCP 서버라면 --mcp-server-url https://mcp.internal.example.com/mcp를 사용하세요. 이 옵션이 --mcp-command를 대체합니다.

앱을 만들거나 테스트하는 동안 tunnel-client run ...이 정상적으로 실행되도록 유지하세요. 앱 탐색과 MCP 도구 호출에는 실행 중인 클라이언트가 필요합니다.

tunnel-client 실행 위치 선택

비공개 MCP 서버에 이미 접근할 수 있는 신뢰 경계 안에서 tunnel-client를 실행하세요. 일반적인 배포 방식은 다음과 같습니다.

• Kubernetes 사이드카: 같은 Pod에서 MCP 서버와 함께 tunnel-client를 실행하고 localhost로 연결하세요.
• 전용 Kubernetes 배포: 비공개 Service를 통해 MCP 서버에 이미 접근할 수 있다면 tunnel-client를 별도로 실행하세요.
• VM 또는 systemd 서비스: 사설 네트워크를 통해 MCP 서버에 접근할 수 있는 호스트에서 tunnel-client를 실행하세요.

ChatGPT에서 연결

ChatGPT 플러그인에서 더하기 버튼을 누른 뒤 사용자 지정 MCP 서버 추가를 선택하세요. 이어서 터널을 선택하세요. 이 옵션은 연결 항목에 있습니다. ChatGPT에 사용 가능한 터널이 표시되면 선택하거나, 유효한 tunnel_id가 있다면 붙여넣으세요. 인증을 설정하고 위험 안내를 검토한 뒤 내용을 이해했으며 계속 진행합니다를 선택하고 플러그인으로 만들기를 선택하세요.

ChatGPT에 터널이 표시되지 않는다면 플랫폼 조직뿐 아니라 대상 ChatGPT 워크스페이스에도 터널이 연결되어 있는지, 앱 생성자에게 Tunnels Read + Use 권한이 있는지 확인하세요.

Codex로 설정 및 검증

Codex의 안내에 따라 설정하려면 Codex에 브라우저로 플랫폼과 ChatGPT에 접근할 권한을 부여하세요. 비공개 MCP 서버에 접근할 수 있는 호스트의 터미널도 Codex가 사용할 수 있도록 하세요. 다음 프롬프트를 Codex에 붙여넣으세요.

내부 MCP 서버와 ChatGPT를 연결하는 비공개 보안 MCP 터널을 설정하고 전체 연결 과정을 검증할 수 있도록 도와주세요. 브라우저와 컴퓨터를 조작하고 터미널을 사용해 다음 두 문서의 지침을 따라 주세요.
https://developers.openai.com/api/docs/guides/secure-mcp-tunnels
https://github.com/openai/tunnel-client/blob/master/docs/onboarding.md
각 단계에서 현재 UI와 CLI 도움말도 확인해 주세요.

먼저 사용할 플랫폼 조직과 ChatGPT 워크스페이스, MCP 서버의 HTTP URL 또는 stdio 명령어, 클라이언트를 실행할 호스트를 확인해 주세요. 기존 터널, 키, ChatGPT 사용자 지정 MCP 플러그인을 살펴보고 적합한 리소스는 재사용해 주세요. 터널에 대상 조직과 워크스페이스가 연결되어 있는지 확인하고 권한도 점검해 주세요. 터널을 만드는 사용자에게는 Tunnels Read + Manage 권한이 필요하고, 권한이 제한된 런타임 키와 플러그인 운영자에게는 각각 Tunnels Read + Use 권한이 필요합니다.

채팅, 명령어 인수, 로그, 스크린샷, 설정 파일에 실제 비밀 값이 노출되지 않도록 해 주세요. 안전한 입력 방식이나 환경 변수 참조를 사용해 제가 로컬에서 직접 값을 제공할 수 있도록 안내해 주세요. 지원되는 tunnel-client를 설치하고 `tunnel-client help quickstart`를 실행한 뒤 서버를 설정해 주세요. 이어서 `tunnel-client doctor --profile <name> --explain`을 실행하고 클라이언트를 시작한 뒤, 요청을 처리할 준비가 되었는지와 실제로 폴링 중인지 확인해 주세요. 탐색과 도구 호출을 위해 클라이언트를 계속 실행해 두세요.

ChatGPT 플러그인에서 비공개 사용자 지정 MCP 서버를 추가하거나 진행 중인 설정을 마무리해 주세요. 연결 방식을 터널(Connection: Tunnel)로 설정하고 앞에서 확인한 터널을 선택한 뒤 필요한 인증을 구성해 주세요. 그런 다음 대표적인 사용 사례에 해당하는 도구를 안전하게 호출해 주세요. 각 점검 단계에서 무엇을 확인했는지 관찰한 근거와 함께 보고해 주세요. 진행이 막히면 정확한 오류와 다음에 취할 조치를 알려 주세요. ChatGPT에서 도구 호출이 성공한 뒤에만 설정이 완료되었다고 보고해 주세요.

Responses API에서 연결

MCP 도구 정의의 tunnel_id에 터널 식별자를 전달하세요. OpenAI가 호스팅하는 터널 엔드포인트를 server_url로 전달하지 마세요. server_url은 Responses API가 직접 접근할 수 있는 MCP 서버에만 사용하세요.

1
2
3
4
5
6
7
8
9
10
11
12
13
14curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6-astra",
    "input": "Use the private MCP server to answer my request.",
    "tools": [
      {
        "type": "mcp",
        "server_label": "private_mcp",
        "tunnel_id": "tunnel_0123456789abcdef0123456789abcdef"
      }
    ]
  }'

보안 및 네트워킹

• MCP 서버 주소는 비공개로 유지되며 tunnel-client가 실행되는 환경 안에서만 사용됩니다.
• tunnel-client는 OpenAI 터널 제어 영역에서 인증을 받으며, 지원되는 OpenAI 제품은 OpenAI가 호스팅하는 터널 엔드포인트를 사용합니다.
• 터널 접근은 기존 조직 및 워크스페이스 컨텍스트를 따르므로 별도의 공개 인바운드 경로가 필요하지 않습니다.
• tunnel-client는 아웃바운드 프록시, 사용자 지정 CA 번들, 제어 영역 클라이언트 인증서, MCP 측 mTLS 등 엔터프라이즈 네트워킹 요구 사항을 지원합니다.

로깅 범위

보안 MCP 터널에서는 터널 전송과 제품의 앱 수준 로깅을 구분합니다.

• 터널 경로에서는 터널 제어 영역 인증, 롱 폴링 및 응답 트래픽, 개별 터널 전송 요청을 ChatGPT 컴플라이언스 플랫폼의 앱 이벤트로 기록하지 않습니다.
• 터널 메타데이터 변경 사항은 API 플랫폼의 감사 로그에서 tunnel.created, tunnel.updated, tunnel.deleted 이벤트로 확인할 수 있습니다.
• ChatGPT가 보안 MCP 터널을 통해 사용자 지정 앱에 접근할 때 터널은 전송 경로 역할만 합니다. 앱 경로에는 일반적인 앱 수준 컴플라이언스 로깅이 그대로 적용됩니다. 여기에는 앱 호출 로그와 앱 연결 또는 연결 해제 시 기록되는 APP_AUTH_LOG 등의 앱 인증 수명 주기 로그가 포함됩니다.

고급 설정: 허용 목록에 있는 대상으로 HTTP 호출

보안 MCP 터널을 사용하면 지원되는 에이전트나 API 플로우에서 고객 네트워크 내부로 제한된 범위의 HTTP 호출을 보낼 수도 있습니다. tunnel-client에는 Harpoon이라는 MCP 서버가 내장되어 있습니다. Harpoon은 설정된 HTTP 대상을 레이블로 제공하며, 호출자는 정해진 요청 및 응답 한도 내에서 터널을 통해 해당 대상을 호출할 수 있습니다.

소수의 비공개 REST 엔드포인트를 인터넷에 공개하지 않고 접근해야 할 때 사용하세요. Harpoon은 범용 프록시가 아니므로 호출자가 임의로 호스트를 선택할 수 없습니다. 요청에는 고객이 설정한 대상과 메서드만 사용할 수 있습니다.

문제 해결

• 플랫폼 터널 설정에 “Tunnels access required”가 표시되는 경우: 터널 권한은 프로젝트 단위가 아니라 조직 단위로 부여됩니다. 대상 플랫폼 조직을 선택한 뒤 조직 소유자나 RBAC 관리자에게 필요한 권한이 있는 역할이나 그룹에 추가해 달라고 요청하세요. 터널을 조회하려면 Read 권한이, 생성·편집·삭제하려면 Read + Manage 권한이 필요합니다. 적합한 역할이 없다면 관리자가 역할을 만들어 그룹에 할당하고 사용자를 해당 그룹에 추가할 수 있습니다. 추가로 Use 권한이 있어야 tunnel-client를 실행하거나 커넥터 설정에서 터널을 선택할 수 있습니다. 새 역할 할당이 반영되기까지 최대 30분이 걸릴 수 있습니다.
• ChatGPT에 터널이 표시되지 않는 경우: 터널에 플랫폼 조직뿐 아니라 대상 ChatGPT 워크스페이스도 연결되어 있는지 확인한 뒤 커넥터 운영자에게 Tunnels Use 권한이 있는지 확인하세요. 엔터프라이즈 계정의 워크스페이스를 자동으로 연결할 수 없다면 OpenAI 계정 담당 팀에 검토 후 수동 연결을 허용해 달라고 요청하세요.
• 커넥터 탐색이나 도구 호출이 실패하는 경우: tunnel-client run ...이 계속 실행 중인지 확인한 뒤 tunnel-client doctor --profile <name> --explain을 다시 실행하세요.
• 터널을 조회할 수 있지만 편집할 수 없는 경우: 운영자에게 Tunnels Read 권한은 있지만 Tunnels Manage 권한이 없을 가능성이 큽니다.
• tunnel-client는 /healthz, /readyz, /metrics를 제공하며 /ui에서 로컬 관리 UI를 제공합니다.
• 기본적으로 관리 UI에는 루프백 주소로만 접근할 수 있습니다. 운영자 네트워크에서 접근해야 할 때만 원격 접근을 허용하세요.
• ChatGPT, Codex 또는 API 플로우에서 테스트하기 전에 이 엔드포인트와 관리 UI에서 클라이언트가 정상 작동하고 요청을 처리할 준비가 되었으며 폴링 중인지 확인하세요.
• 클라이언트의 연결이 끊기면 tunnel-client가 다시 연결될 때까지 터널을 통한 요청이 실패합니다.
• 원시 HTTP 로깅은 기본적으로 비활성화되어 있으며, 지원용으로 내보낸 데이터에서는 민감한 정보가 가려집니다.

OAuth

• OAuth 검색은 터널을 통해 수행할 수 있으므로 MCP 서버 자체는 비공개로 유지할 수 있습니다.
• 터널은 브라우저에서 진행되는 OAuth 플로우에 필요한 업스트림 인가 서버의 메타데이터를 보존합니다.
• 인가 서버 자체가 자동으로 터널에 연결되지는 않습니다. 인터넷에서도 tunnel-client 호스트에서도 인가 서버에 접근할 수 없다면 MCP 서버에 접근할 수 있더라도 OAuth 플로우가 실패할 수 있습니다.

설정 위치

• OpenAI가 호스팅하는 MCP 터널 엔드포인트는 플랫폼 터널 설정에서 관리하세요.
• 사용자 지정 MCP 서버를 추가할 때는 ChatGPT 플러그인에서 터널을 선택하세요.
• Codex 또는 API 플로우에서는 해당 제품이 제공하는 터널 연결 MCP 대상을 사용하세요.

다음 단계

• 플랫폼 터널 설정에서 터널을 만들거나 관리하세요.
• tunnel-client 프로필을 검증하려면 tunnel-client doctor --profile <profile> --explain을 실행하세요.
• ChatGPT 플러그인이나 사용 중인 터널 지원 OpenAI 제품에서 터널을 연결하세요.