--- title: MCP 터널 레퍼런스 url: https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/reference description: 프록시 구성 필드, Tunnels REST API, 인증서 요구 사항 및 setup 컴포넌트에 대한 설명입니다. --- MCP tunnels(MCP 터널)는 연구 프리뷰 단계입니다. 사용해 보려면 [액세스를 요청](https://claude.com/form/mcp-tunnels)하세요. ## 프록시 구성 [프록시](https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/concepts#components)는 `/etc/mcp-gateway/config.yaml`(Compose) 또는 렌더링된 ConfigMap(Helm, `gateway.config.*`에서 채워짐)에서 구성을 읽습니다. | 필드 | 설명 | 기본값 | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | | `listen_addr` | 수신할 주소 및 포트입니다. | 필수 | | `log_level` | 로깅 상세 수준: `debug`, `info`, `warn` 또는 `error`. | `info` | | `shutdown_timeout` | 정상 종료(graceful shutdown) 중 진행 중인 요청을 기다리는 시간입니다. | `30s` | | `tunnel_domain` | 터널에 할당된 기본 도메인입니다. 설정된 경우, 라우트 조회 시 수신 호스트 이름에서 이 접미사를 제거하므로 `routes` 키를 단순 서브도메인(`wiki`)으로 지정할 수 있습니다. 비어 있는 경우, `routes` 키는 정확한 전체 호스트 이름이어야 합니다. | `routes` 키가 단순 서브도메인인 경우 필수 | | `tls.cert_file` | 서버 TLS 인증서 경로입니다. | 필수 | | `tls.key_file` | 서버 TLS 개인 키 경로입니다. | 필수 | | `routes` | 서브도메인 또는 전체 호스트 이름을 업스트림 URL에 매핑하는 맵입니다. [라우트 매칭](https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/reference#route-matching)을 참조하세요. | 필수 | | `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` 중 하나 이상을 설정하세요. 그렇지 않으면 프록시에 업스트림 인증서에 대한 신뢰 앵커가 없게 됩니다. ### 라우트 매칭 `routes`는 리스트가 아닌 평면 문자열 맵(`map[string]string`)입니다. 프록시는 먼저 수신 호스트 이름을 정확히 일치하는 항목으로 조회한 다음, `tunnel_domain` 접미사를 제거하고 남은 서브도메인으로 매칭합니다. 매칭은 호스트 이름만 고려하며, 요청 경로와 쿼리 문자열은 변경 없이 [업스트림 MCP 서버](https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/concepts#components)로 전달됩니다. 각 업스트림 값은 정확히 `scheme://host:port` 형식이어야 합니다. 포트는 필수입니다. 경로를 포함하면 구성 로드 시 `invalid upstream (must be scheme://host:port)` 오류와 함께 거부됩니다. ## Tunnels API Tunnels REST API는 `/v1/tunnels`에 위치하며 터널 생성, 목록 조회 및 보관, CA 인증서 등록, 터널 토큰 조회 또는 교체를 지원합니다. 모든 엔드포인트, 요청 및 응답 스키마, 예제는 [Tunnels API 레퍼런스](https://platform.claude.com/docs/ko/api/beta/tunnels/list)를 참조하세요. `/v1/organizations/tunnels`의 이전 Admin API 인터페이스(베타 헤더 `mcp-tunnels-2026-05-19`, 스코프 `org:manage_tunnels`)는 마이그레이션 기간 동안 계속 작동하며, 지원 중단 안내와 함께 [Admin API 레퍼런스](https://platform.claude.com/docs/ko/api/beta/organization/mcp_tunnels)에 계속 문서화되어 있습니다. 마이그레이션하려면 경로를 `/v1/tunnels`로, 베타 헤더를 `mcp-tunnels-2026-06-22`로, WIF 토큰 스코프를 `workspace:manage_tunnels`로 업데이트하세요. 모든 MCP 터널 엔드포인트에는 [Workload Identity Federation](https://platform.claude.com/docs/ko/manage-claude/workload-identity-federation)을 통해 획득한 `workspace:manage_tunnels` 스코프의 bearer 토큰이 필요합니다. Admin API 키는 허용되지 않습니다. 모든 요청에 필요한 헤더: | 헤더 | 값 | | ------------------- | ------------------------------ | | `Authorization` | `Bearer ` (WIF로 교환된 토큰) | | `anthropic-version` | `2023-06-01` | | `anthropic-beta` | `mcp-tunnels-2026-06-22` | ## 인증서 요구 사항 [setup 컴포넌트](https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/concepts#components)는 요구 사항을 준수하는 인증서를 자동으로 생성합니다. 이 요구 사항은 자체 PKI를 통해 인증서를 발급하는 경우에만 적용됩니다. ### CA 인증서 `POST /v1/tunnels/{tunnel_id}/certificates`로 업로드합니다. 터널은 동시에 최대 두 개의 활성 CA 인증서를 보유할 수 있으며, 이를 통해 무중단 교체가 가능합니다. * PEM 인코딩, 단일 인증서, 최대 8 kB. * `BasicConstraints` 확장이 `CA:TRUE`로 존재하며 critical로 표시되어야 합니다. * `SubjectKeyIdentifier` 확장이 존재해야 합니다. * `KeyUsage`에 `keyCertSign`이 포함되어야 합니다. * 유효 기간 내에 있어야 합니다. * RSA 2048비트 이상 또는 ECDSA P-256 이상이며, SHA-256 이상의 서명을 사용해야 합니다. ### 서버 인증서 [내부 TLS](https://platform.claude.com/docs/ko/agents-and-tools/mcp-tunnels/concepts#components) 중에 프록시가 제시합니다. * 등록된 CA가 직접 서명해야 합니다(중간 인증서 없음). * `AuthorityKeyIdentifier` 확장이 존재하며 CA의 `SubjectKeyIdentifier`와 일치해야 합니다. * Subject Alternative Name에 `.`과 일치하는 DNS 이름이 포함되어야 합니다. 와일드카드 `*.`은 모든 라우트를 포함합니다. * `ExtendedKeyUsage` 확장이 존재하는 경우 `serverAuth`를 포함해야 합니다. * 유효 기간 내에 있어야 합니다. * RSA 2048비트 이상 또는 ECDSA P-256 이상이며, SHA-256 이상의 서명을 사용해야 합니다. setup 컴포넌트는 5년 유효 기간의 ECDSA P-256 CA와 와일드카드 SAN 및 90일 유효 기간의 RSA 4096비트 서버 인증서를 생성합니다. ## setup 컴포넌트 setup 컴포넌트는 `mcp-proxy` 이미지 내에 `setup` 바이너리로 포함되어 제공됩니다. `docker compose run --rm setup `(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:`를 전달합니다. | `k8s-secret:mcp-tunnel` (Kubernetes 파드에서 실행 시 자동 감지, 그 외에는 필수) | | `--cert-duration` | 서버 인증서 유효 기간입니다. | `2160h` (90일) | | `--token-version` | 변경 감지 문자열입니다. 새 값을 지정하면 재실행 시 토큰 교체가 트리거됩니다. Helm 차트와 Compose 예제 모두 초기값으로 `1`을 전달합니다. | 없음 | 이 명령은 [Workload Identity Federation](https://platform.claude.com/docs/ko/manage-claude/workload-identity-federation)을 통해 인증합니다. `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_WORKSPACE_ID`(선택 사항), 그리고 `ANTHROPIC_IDENTITY_TOKEN_FILE` 또는 `ANTHROPIC_IDENTITY_TOKEN` 중 정확히 하나를 읽습니다. 이러한 변수의 현재 의미는 [WIF 레퍼런스](https://platform.claude.com/docs/ko/manage-claude/wif-reference)를 참조하세요. setup 컴포넌트는 페더레이션 규칙에서 서비스 계정을 도출하므로 `ANTHROPIC_SERVICE_ACCOUNT_ID`를 별도로 요구하지 않습니다. ### `setup renew-cert` 저장된 CA로 서명된 새 서버 인증서를 발급합니다. API 호출을 하지 않습니다. | 플래그 | 설명 | 기본값 | | ----------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------- | | `--output` | 출력 대상: `dir:/path` 또는 `k8s-secret:NAME`. Helm 차트는 `k8s-secret:`를 전달합니다. | `k8s-secret:mcp-tunnel` (Kubernetes 파드에서 실행 시 자동 감지, 그 외에는 필수) | | `--cert-duration` | 새 인증서 유효 기간입니다. | `2160h` (90일) | | `--renew-before` | 기존 인증서의 남은 유효 기간이 이 값보다 길면 갱신을 건너뜁니다. | `0` (항상 갱신) | `--renew-before=720h`로 설정하면 유효 기간이 30일 넘게 남아 있을 때 명령이 아무 작업도 수행하지 않으므로, 고정된 일정으로 실행해도 안전합니다.