openai/tunnel-client
Customer-run client for Secure MCP Tunnel: connect private or localhost MCP servers to ChatGPT, Codex, the Responses API, and AgentKit without exposing them to the public internet.
tunnel‑client란 무엇인가요?
tunnel-client는 OpenAI의 ChatGPT, Codex 및 기타 제품이 사용하는 API인 MCP(Model Context Protocol) 서버를 안전한 OpenAI 호스팅 터널 뒤에서 실행할 수 있게 해주는 명령줄 데몬입니다. 이 터널을 사용하면 비공개 서버를 공용 인터넷에 노출하지 않고도 OpenAI 서비스에서 접근할 수 있습니다.
사용 이유
- 로컬, VM, Kubernetes 클러스터 또는 기타 비공개 네트워크에서 MCP 서버를 실행 중인 경우.
- 조직의 보안 정책상 인바운드 방화벽 포트를 여는 것이 금지된 경우.
- 다른 구성 요소(예: ChatGPT 커넥터)가 안전하게 의존할 수 있도록 상태(
/healthz), 준비 상태(/readyz), 메트릭 및 UI를 보고하는 프로덕션급 데몬이 필요한 경우.
핵심 기능
| 기능 | 설명 |
|---|---|
| 보안 터널 | OpenAI 호스팅 터널 엔드포인트를 통해 비공개 MCP 서버를 OpenAI의 제어 평면 엔드포인트(ChatGPT, Codex, Responses API, AgentKit)에 연결합니다. |
| 내장 데모 모드 | 빠른 테스트를 위해 클라이언트 내에서 작은 상태 비저장 MCP 스텁을 실행합니다 (--embedded-stateless-mcp-stub). |
| Go SDK 통합 | 클라이언트를 Go MCP 서버와 프로세스 내에서 인스턴스화하고 메모리 내 전송을 사용하여 터널 로직을 Go 애플리케이션에 직접 포함할 수 있습니다. |
| 관측 가능성 | /healthz, /readyz, /metrics 및 모니터링을 위한 웹 UI를 노출합니다. |
| 배포 유연성 | Homebrew, Docker, Kubernetes를 통해 설치하거나 일반 바이너리로 실행할 수 있습니다. |
| 권한 모델 | 역할 기반 터널 권한(읽기, 사용, 관리)을 지원하며 OpenAI 런타임/관리 API 키와 함께 작동합니다. |
| 프로토콜 및 OpenAPI | 다른 언어로 호환되는 클라이언트를 구축하기 위한 전체 와이어 프로토콜 문서(docs/protocol.md)와 OpenAPI 계약(docs/openapi.json)을 제공합니다. |
일반적인 워크플로우
- OpenAI Platform에서(또는
tunnel-client admin tunnels create를 통해) 터널을 생성합니다. - 터널 ID와 런타임 API 키를
CONTROL_PLANE_TUNNEL_ID및CONTROL_PLANE_API_KEY로 내보냅니다. - 로컬 MCP 서버를 가리키거나 내장 스텁을 사용하여 클라이언트를 실행합니다. 예:
export CONTROL_PLANE_API_KEY="sk-..." export CONTROL_PLANE_TUNNEL_ID="tunnel_0123..." tunnel-client run --embedded-stateless-mcp-stub --health.listen-addr 127.0.0.1:0 - 클라이언트가 OpenAI에 대한 보안 터널을 설정합니다. 이제 ChatGPT나 Codex가 마치 OpenAI에서 호스팅되는 것처럼 비공개 MCP 엔드포인트를 호출할 수 있습니다.
AI 스택에서의 역할
- **Model Context Protocol (MCP)**은 OpenAI의 LLM 기반 서비스에서 사용하는 저수준 요청/응답 형식입니다.
tunnel-client는 사용자 고유의 MCP 구현(사용자 지정 도구, 데이터 저장소 또는 정책 엔진 등)이 보안 경계 내에 머물면서 OpenAI 호스팅 제품에 참여할 수 있도록 하는 브리지입니다.- 이는 엔터프라이즈급 구성 요소입니다. 서명된 릴리스, SBOM, 출처 증명 및 엄격한 권한 처리를 통해 규제 환경에 적합합니다.
빠른 시작 체크리스트
- 설치 –
brew install openai/tools/tunnel-client(또는 Docker/K8s 사용). - 터널 및 키 생성 – OpenAI Platform UI 또는
tunnel-client admin …을 통해 수행. - 실행 –
tunnel-client help quickstart후tunnel-client run …실행. - 확인 – 상태 엔드포인트를 확인한 다음 커넥터가 ChatGPT 설정에 나타나는지 확인합니다.
추가 정보
- 공용 가이드 – https://developers.openai.com/api/docs/guides/secure-mcp-tunnels
- 온보딩 문서 –
docs/onboarding.md - 아키텍처 및 권한 –
docs/architecture.md,docs/permissions.md - 프로토콜 사양 및 OpenAPI –
docs/protocol.md,docs/openapi.json - 예제 –
examples/go-sdk-inmemory(Go 프로세스에 포함).
요약
tunnel-client는 비공개 MCP 서버를 OpenAI의 LLM 기반 서비스에 안전하게 노출하는 공식 OpenAI 도구입니다. 인바운드 네트워크 포트를 열지 않고도 관측 가능성, 역할 기반 액세스 제어 및 다양한 배포 옵션을 제공합니다.
관련
- 프로젝트
- 프로젝트
- 프로젝트
- 프로젝트
- 프로젝트