MessagesMCP 터널

MCP 터널 참조

프록시 구성 필드, Tunnels REST API, 인증서 요구 사항 및 설정 컴포넌트.

MCP 터널은 리서치 프리뷰 단계입니다. 사용해 보시려면 액세스를 요청하세요.

프록시 구성

프록시는 /etc/mcp-gateway/config.yaml(Compose) 또는 렌더링된 ConfigMap(Helm, gateway.config.*에서 채워짐)에서 구성을 읽습니다.

필드	설명	기본값
`listen_addr`	수신할 주소 및 포트.	필수
`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 중 하나 이상을 설정하세요. 그렇지 않으면 프록시가 업스트림 인증서에 대한 신뢰 앵커를 갖지 못합니다.

라우트 매칭

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

각 업스트림 값은 정확히 scheme://host:port 형식이어야 합니다. 포트는 필수입니다. 경로를 포함하면 구성 로드 시 invalid upstream (must be scheme://host:port) 오류와 함께 거부됩니다.

Tunnels API

모든 엔드포인트, 요청 및 응답 스키마, 언어별 예제는 MCP 터널 Admin API 참조를 참조하세요.

모든 MCP 터널 엔드포인트는 Workload Identity Federation을 통해 획득한 org:manage_tunnels 스코프를 가진 bearer 토큰이 필요합니다. Admin API 키는 허용되지 않습니다.

모든 요청에 필요한 헤더:

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

인증서 요구 사항

설정 컴포넌트는 규격에 맞는 인증서를 자동으로 생성합니다. 이 요구 사항은 자체 PKI를 통해 인증서를 발급하는 경우에만 적용됩니다.

CA 인증서

POST /v1/organizations/tunnels/{tunnel_id}/certificates로 업로드합니다. 터널은 한 번에 최대 두 개의 활성 CA 인증서를 보유할 수 있으며, 이를 통해 무중단 교체가 가능합니다.

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

서버 인증서

내부 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비트 서버 인증서를 생성합니다.

설정 컴포넌트

설정 컴포넌트는 mcp-proxy 이미지 내부에 setup 바이너리로 포함되어 있습니다. docker compose run --rm setup <subcommand>로 실행하거나(Compose), 차트의 훅 및 CronJob에 의존하세요(Helm).

`setup init`

Console에서 생성한 터널에 연결하고, CA 및 서버 인증서를 생성하고, CA를 등록하고, 터널 토큰을 가져오고, 모든 출력을 대상 위치에 씁니다.

플래그	설명	기본값
`--api-url`	Claude API 기본 URL. `API_URL`에서도 읽습니다.	필수
`--tunnel-id`	연결할 터널 ID(`tnl_...`). `TUNNEL_ID`에서도 읽습니다.	필수
`--output`	출력 대상: `dir:/path` 또는 `k8s-secret:NAME`. Helm 차트는 `k8s-secret:<release>`를 전달합니다.	`k8s-secret:mcp-tunnel` (Kubernetes 파드에서 실행 시 자동 감지됨, 그 외에는 필수)
`--cert-duration`	서버 인증서 유효 기간.

이 명령은 Workload Identity Federation을 통해 인증합니다. ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_WORKSPACE_ID(선택 사항), 그리고 ANTHROPIC_IDENTITY_TOKEN_FILE 또는 ANTHROPIC_IDENTITY_TOKEN 중 정확히 하나를 읽습니다. 이러한 변수의 현재 의미는 WIF 참조를 참조하세요. 설정 컴포넌트는 federation rule에서 서비스 계정을 도출하므로 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일 이상 남아 있을 때 명령이 아무 작업도 수행하지 않으므로, 고정된 일정으로 실행해도 안전합니다.

Was this page helpful?

MessagesMCP 터널

MCP 터널 참조

프록시 구성 필드, Tunnels REST API, 인증서 요구 사항 및 설정 컴포넌트.

MCP 터널은 리서치 프리뷰 단계입니다. 사용해 보시려면 액세스를 요청하세요.

프록시 구성

프록시는 /etc/mcp-gateway/config.yaml(Compose) 또는 렌더링된 ConfigMap(Helm, gateway.config.*에서 채워짐)에서 구성을 읽습니다.

필드	설명	기본값
`listen_addr`	수신할 주소 및 포트.	필수
`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`

라우트 매칭

Tunnels API

모든 엔드포인트, 요청 및 응답 스키마, 언어별 예제는 MCP 터널 Admin API 참조를 참조하세요.

모든 요청에 필요한 헤더:

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

인증서 요구 사항

설정 컴포넌트는 규격에 맞는 인증서를 자동으로 생성합니다. 이 요구 사항은 자체 PKI를 통해 인증서를 발급하는 경우에만 적용됩니다.

CA 인증서

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

서버 인증서

내부 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 init`

Console에서 생성한 터널에 연결하고, CA 및 서버 인증서를 생성하고, CA를 등록하고, 터널 토큰을 가져오고, 모든 출력을 대상 위치에 씁니다.

플래그	설명	기본값
`--api-url`	Claude API 기본 URL. `API_URL`에서도 읽습니다.	필수
`--tunnel-id`	연결할 터널 ID(`tnl_...`). `TUNNEL_ID`에서도 읽습니다.	필수
`--output`	출력 대상: `dir:/path` 또는 `k8s-secret:NAME`. Helm 차트는 `k8s-secret:<release>`를 전달합니다.	`k8s-secret:mcp-tunnel` (Kubernetes 파드에서 실행 시 자동 감지됨, 그 외에는 필수)
`--cert-duration`	서버 인증서 유효 기간.

`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일 이상 남아 있을 때 명령이 아무 작업도 수행하지 않으므로, 고정된 일정으로 실행해도 안전합니다.

Was this page helpful?