MCP 터널 레퍼런스

MCP 터널 레퍼런스 (MCP tunnels reference)

이 페이지는 MCP 터널의 참조 자료예요. 프록시 설정 필드, Tunnels REST API, 인증서 요구 사항, 설정 구성 요소를 담고 있어요.

출처: 문서

본문

참고 (Note) MCP 터널은 연구 프리뷰(research preview) 상태예요. 사용해보려면 액세스를 요청하세요.

프록시 설정 (Proxy configuration)

프록시는 /etc/mcp-gateway/config.yaml(Compose) 또는 렌더링된 ConfigMap(Helm, gateway.config.*에서 채움)에서 설정을 읽어요.

필드 설명 기본값
listen_addr 듣기(listen)할 주소와 포트. 필수
log_level 로깅 상세도: debug, info, warn, 또는 error. info
shutdown_timeout 정상 종료 중 진행 중인 요청을 기다리는 시간. 30s
tunnel_domain 터널에 할당된 기본 도메인. 설정하면 라우트 조회가 들어오는 호스트 이름에서 이 접미사를 제거해서 routes 키가 순수 하위 도메인(wiki)이 되게 해요. 비어 있으면 routes 키는 정확한 전체 호스트 이름이어야 해요. routes 키가 순수 하위 도메인일 때 필수
tls.cert_file 서버 TLS 인증서 경로. 필수
tls.key_file 서버 TLS 개인 키 경로. 필수
routes 하위 도메인 또는 전체 호스트 이름을 업스트림 URL에 매핑하는 맵. 라우트 매칭을 참고하세요. 필수
upstream.allowed_ips 프록시가 연결할 수 있는 IPv4 CIDR 범위 또는 개별 주소. disable_ip_validation과 상호 배타적이에요. RFC1918 사설 범위
upstream.disable_ip_validation 업스트림 IP 검증을 완전히 비활성화. allowed_ips와 상호 배타적이에요. false
upstream.tls.ca_file 업스트림 TLS 검증용 CA 번들. 없음
upstream.tls.include_system_cas 업스트림 TLS에 시스템 CA 번들도 신뢰. false

https:// 업스트림 라우트의 경우 upstream.tls.ca_file 또는 upstream.tls.include_system_cas 중 적어도 하나를 설정하세요. 그렇지 않으면 프록시가 업스트림 인증서에 대한 신뢰 앵커가 없어요.

라우트 매칭 (Route matching)

routes는 평면 문자열 맵(map[string]string)이지, 리스트가 아니에요. 프록시는 들어오는 호스트 이름을 먼저 정확히 일치시킨 다음, tunnel_domain 접미사를 제거하고 남은 하위 도메인을 일치시켜요. 매칭은 호스트 이름만 고려하며, 요청 경로와 쿼리 문자열은 변경 없이 업스트림 MCP 서버로 전달돼요.

각 업스트림 값은 정확히 scheme://host:port여야 해요. 포트는 필수예요. 경로를 포함하면 설정 로드 시 invalid upstream (must be scheme://host:port)로 거부돼요.

Tunnels API

Tunnels REST API는 /v1/tunnels에 있으며 터널 생성, 나열, 아카이브, CA 인증서 등록, 터널 토큰 공개·순환을 지원해요. 모든 엔드포인트, 요청·응답 스키마, 예시는 Tunnels API 레퍼런스를 참고하세요.

참고 (Note) 이전 Admin API 표면 /v1/organizations/tunnels(베타 헤더 mcp-tunnels-2026-05-19, 스코프 org:manage_tunnels)는 마이그레이션 기간 동안 계속 동작하며 폐지 공지와 함께 Admin API 레퍼런스에 문서화되어 있어요. 마이그레이션하려면 경로를 /v1/tunnels로, 베타 헤더를 mcp-tunnels-2026-06-22로, WIF 토큰 스코프를 workspace:manage_tunnels로 바꾸세요.

경고 (Warning) 모든 MCP 터널 엔드포인트는 Workload Identity Federation을 통해 얻은 workspace:manage_tunnels 스코프의 베어러 토큰이 필요해요. Admin API 키는 허용되지 않아요.

모든 요청에 필요한 헤더:

헤더 값
Authorization Bearer <token> (WIF로 교환된 토큰)
anthropic-version 2023-06-01
anthropic-beta mcp-tunnels-2026-06-22

인증서 요구 사항 (Certificate requirements)

설정 구성 요소는 규정을 준수하는 인증서를 자동으로 생성해요. 이 요구 사항은 여러분이 직접 PKI를 통해 인증서를 발급할 때만 적용돼요.

CA 인증서 (CA certificate)

POST /v1/tunnels/{tunnel_id}/certificates로 업로드해요. 터널은 한 번에 최대 두 개의 활성 CA 인증서를 보유할 수 있어서 무중단 순환이 가능해요.

  • PEM 인코딩, 단일 인증서, 최대 8 kB.
  • BasicConstraints 확장이 CA:TRUE로 critical 표시되어 있음.
  • SubjectKeyIdentifier 확장이 있음.
  • KeyUsage에 keyCertSign이 포함됨.
  • 유효 기간 내에 있음.
  • RSA 2048비트 이상 또는 ECDSA P-256 이상이며, SHA-256 이상의 서명을 사용.

서버 인증서 (Server certificate)

내부 TLS 동안 프록시가 제시해요.

  • 등록된 CA가 직접 서명(중간체 없음).
  • AuthorityKeyIdentifier 확장이 있고 CA의 SubjectKeyIdentifier와 일치.
  • Subject Alternative Name에 <route>.<tunnel-domain>과 일치하는 DNS 이름 포함. 와일드카드 *.<tunnel-domain>이 모든 라우트를 포함해요.
  • ExtendedKeyUsage 확장이 있으면 serverAuth를 포함.
  • 유효 기간 내에 있음.
  • RSA 2048비트 이상 또는 ECDSA P-256 이상이며, SHA-256 이상의 서명을 사용.

설정 구성 요소는 5년 유효 기간의 ECDSA P-256 CA와 와일드카드 SAN을 가진 90일 유효 기간의 RSA 4096비트 서버 인증서를 생성해요.

설정 구성 요소 (Setup component)

설정 구성 요소는 mcp-proxy 이미지 안에 setup 바이너리로 들어 있어요. docker compose run --rm setup <subcommand>(Compose)로 실행하거나 차트의 훅과 CronJob을 사용해요(Helm).

setup init

기존 터널에 연결하고(터널 ID가 없으면 새로 만들고), CA와 서버 인증서를 생성하고, CA를 등록하고, 터널 토큰을 가져와 모든 출력을 대상에 써요.

플래그 설명 기본값
--api-url Claude API 기본 URL. API_URL에서도 읽음. 필수
--tunnel-id 연결할 터널 ID (tnl_...). TUNNEL_ID에서도 읽음. 생략하면 새 터널 생성. 이미 출력에 저장된 터널 ID는 재실행 시 재사용. 없음 (터널 생성)
--output 출력 대상: dir:/path 또는 k8s-secret:NAME. Helm 차트는 k8s-secret:<release>를 전달. k8s-secret:mcp-tunnel (Kubernetes 팟에서 실행 시 자동 감지, 그 외 필수)
--cert-duration 서버 인증서 유효 기간. 2160h (90일)
--token-version 변경 감지 문자열. 새 값이 재실행 시 토큰 순환을 촉발. Helm 차트와 Compose 예시 모두 초기 값으로 1을 전달. 없음

이 명령은 Workload Identity Federation을 통해 인증해요. ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_WORKSPACE_ID(선택), 그리고 ANTHROPIC_IDENTITY_TOKEN_FILE 또는 ANTHROPIC_IDENTITY_TOKEN 중 정확히 하나를 읽어요. 이 변수들의 현재 의미는 WIF 레퍼런스를 참고하세요. 설정 구성 요소는 서비스 계정을 페더레이션 규칙에서 파생하므로 ANTHROPIC_SERVICE_ACCOUNT_ID를 따로 요구하지 않아요.

setup renew-cert

저장된 CA가 서명한 새 서버 인증서를 발급해요. API 호출은 하지 않아요.

플래그 설명 기본값
--output 출력 대상: dir:/path 또는 k8s-secret:NAME. Helm 차트는 k8s-secret:<release>를 전달. k8s-secret:mcp-tunnel (Kubernetes 팟에서 실행 시 자동 감지, 그 외 필수)
--cert-duration 새 인증서 유효 기간. 2160h (90일)
--renew-before 기존 인증서에 이 시간보다 많은 기간이 남아 있으면 갱신 건너뜀. 0 (항상 갱신)

--renew-before=720h를 설정하면 유효 기간이 30일 이상 남았을 때 명령이 아무것도 하지 않게 되므로 고정 일정으로 안전하게 실행할 수 있어요.

더 알아보기 (Learn more)