Helm으로 MCP 터널 배포하기

설정 컴포넌트는 페더레이션 규칙을 통해 클러스터의 projected ServiceAccount 토큰을 교환하고, 터널 토큰을 가져오고, CA와 서버 인증서를 생성하고, CA를 Anthropic에 등록합니다. 매일 실행되는 CronJob이 필요에 따라 서버 인증서를 갱신하므로 시크릿을 직접 다룰 필요가 없습니다.

1. 1

   클러스터에 대한 Workload Identity Federation 설정

   Kubernetes에서 WIF 사용을 따라 클러스터의 OIDC 발급자를 등록하고 페더레이션 규칙을 생성하세요. 설정 컴포넌트는 릴리스 네임스페이스에서 자체 ServiceAccount로 실행됩니다. 정확한 이름은 Helm의 fullname 규칙을 따르므로, 릴리스 이름이 mcp-tunnel이 아닌 경우 규칙을 생성하기 전에 helm template <release> ... | grep -A2 'kind: ServiceAccount'를 실행하여 이름을 확인하세요. 이 가이드의 나머지 부분에서는 네임스페이스 mcp-tunnel의 릴리스 이름 mcp-tunnel을 가정하며, 이때 ServiceAccount는 mcp-tunnel-setup입니다.

   필드	값
   Subject	system:serviceaccount:mcp-tunnel:mcp-tunnel-setup
   Audience	api.anthropic.com(차트의 기본값, 스킴 없음)
   Scope	workspace:manage_tunnels

   터널이 조직의 기본 워크스페이스가 아닌 다른 워크스페이스에 있는 경우, 규칙의 서비스 계정을 해당 워크스페이스에도 추가하세요(Tunnels API는 서비스 계정의 워크스페이스 멤버십을 기준으로 권한을 부여합니다).

   규칙의 ID(fdrl_...)를 기록해 두세요. 이 값을 api.wif.federationRuleId로 설정합니다.

2. 2

   기본값 가져오기

   helm show values \
     oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
     --version 2.1.0 > values.yaml

   
3. 3

   터널 연결 및 라우트 구성

   values.yaml을 편집하여 페더레이션 규칙 ID와 조직 ID로 api.wif.* 키를 설정하고, 각 업스트림 MCP 서버에 대한 routes 항목을 추가하세요:

   values.yaml

   

   api:
     wif:
       federationRuleId: "fdrl_..."
       organizationId: "00000000-0000-0000-0000-000000000000"
       # Set when the tunnel is in a non-default workspace and the
       # rule's service account is a member of that workspace.
       # workspaceId: "wrkspc_..."
   
   tunnel:
     # Leave empty to have the setup hook create a tunnel during install.
     # Set to attach to an existing tunnel from the Console.
     id: ""
     # Increment to rotate the tunnel token on the next upgrade.
     # See the "Rotate the tunnel token" section.
     tokenVersion: "1"
   
   gateway:
     config:
       routes:
         docs: http://docs-mcp.internal:8080
         search: http://search-mcp.internal:8080

   이 라우트를 사용하면 Claude는 docs.<your-tunnel-domain> 및 search.<your-tunnel-domain>에서 서버에 접근합니다. 일부 관리형 Kubernetes 배포판은 Service CIDR을 표준 사설 대역 밖에 할당합니다. 라우트가 클러스터 내부 Service를 대상으로 하는 경우, 업스트림 IP 검증에 설명된 대로 여기에 gateway.config.upstream.allowed_ips를 추가하세요.

4. 4

   렌더링된 매니페스트 검토

   차트를 렌더링하고 조직의 검증 관행에 따라 출력을 검토하세요:

   helm template mcp-tunnel \
     oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
     --version 2.1.0 \
     -n mcp-tunnel \
     -f values.yaml > rendered.yaml

   
5. 5

   설치

   helm install mcp-tunnel \
     oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
     --version 2.1.0 \
     --namespace mcp-tunnel --create-namespace \
     -f values.yaml

   

   설정 컴포넌트는 Helm pre-install 훅 Job으로 실행되므로 helm install은 완료될 때까지 대기합니다. 성공하면 Helm이 Job을 자동으로 삭제합니다. helm install이 훅 오류로 실패하면 설정 컴포넌트 인증 실패를 참조하세요.

   tunnel.id가 비어 있으면 설정 컴포넌트는 페더레이션 규칙이 대상으로 하는 워크스페이스(api.wif.workspaceId를 설정하지 않은 경우 조직의 기본 워크스페이스)에 터널을 생성하고, 그 ID와 도메인을 mcp-tunnel Secret에 저장합니다. 검증에 필요한 도메인은 터널의 상세 페이지에서 확인할 수 있으며, 이 페이지는 Console의 MCP 터널 페이지(platform.claude.com/settings/workspaces/default/mcp-tunnels)에서 열 수 있습니다. 사이드바의 워크스페이스 선택기에서 터널이 있는 워크스페이스를 선택하세요. Secret에서 도메인을 읽을 수도 있습니다:

   kubectl -n mcp-tunnel get secret mcp-tunnel \
     -o jsonpath='{.data.tunnel-domain}' | base64 -d

   

   설정 컴포넌트를 다시 실행하면(업그레이드 또는 토큰 교체 중) 이 Secret에 저장된 터널 ID를 재사용하며, 두 번째 터널을 생성하지 않습니다.

이 모드(setup.enabled: false)에서는 차트가 API 호출을 하지 않습니다. 설정 컴포넌트가 실행되지 않으며 cert-renew CronJob도 없습니다. Workload Identity Federation을 설정하지 않으려면 이 방법을 사용하세요.

1. 1

   터널 토큰 및 도메인 가져오기

   터널을 생성하고 Console에서 터널 토큰을 가져오세요.

2. 2

   CA 및 서버 인증서 생성

   프록시는 일반 WebSocket에서 수신 대기하며, 여기서 생성하는 인증서를 사용하는 내부 TLS가 해당 스트림 안에서 전달됩니다. 서버 인증서의 SAN은 인증서 요구 사항에 설명된 대로 *.<tunnel-domain>을 포함해야 합니다.

   export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE
   mkdir -p mcp-tunnel/data
   cd mcp-tunnel
   
   # 자체 서명 CA입니다. 확장을 명시적으로 지정하여 인증서
   # 요구 사항을 배포판의 openssl.cnf 기본값과 관계없이 충족합니다.
   openssl req -x509 -newkey rsa:2048 -nodes \
     -keyout data/ca.key -out data/ca.crt \
     -days 3650 -subj "/CN=mcp-tunnel-ca" \
     -addext "basicConstraints=critical,CA:TRUE" \
     -addext "keyUsage=critical,keyCertSign,cRLSign" \
     -addext "subjectKeyIdentifier=hash"
   
   # 서버 인증서용 확장 파일입니다. -extfile을 사용하면(OpenSSL 3.0+ 전용인
   # -copy_extensions 대신) 다음 버전에서도 계속 동작합니다:
   # OpenSSL 1.1.x.
   cat > data/tls.ext <<EOF
   subjectAltName = DNS:${TUNNEL_DOMAIN},DNS:*.${TUNNEL_DOMAIN}
   authorityKeyIdentifier = keyid,issuer
   extendedKeyUsage = serverAuth
   EOF
   
   # CA가 서명한 서버 인증서
   openssl req -newkey rsa:2048 -nodes \
     -keyout data/tls.key -out /tmp/server.csr \
     -subj "/CN=${TUNNEL_DOMAIN}"
   openssl x509 -req -in /tmp/server.csr \
     -CA data/ca.crt -CAkey data/ca.key -CAcreateserial \
     -out data/tls.crt -days 90 \
     -extfile data/tls.ext

   

   Console에 data/ca.crt를 등록하세요. data/ca.key는 영구적이고 안전한 곳에 보관하세요. 갱신 시 새 서버 인증서에 서명하는 데 필요합니다.

3. 3

   두 개의 Secret 생성

   차트는 특정 키를 읽습니다. Secret 이름은 구성할 수 있지만 키는 구성할 수 없습니다. 다음 네임스페이스 생성 명령은 네임스페이스가 이미 존재하는 경우(예: 샘플 MCP 서버 단계에서 생성한 경우) 아무 작업도 하지 않습니다.

   kubectl create namespace mcp-tunnel --dry-run=client -o yaml | kubectl apply -f -
   kubectl -n mcp-tunnel create secret generic mcp-tunnel-token \
     --from-literal=tunnel-token='eyJ...'
   kubectl -n mcp-tunnel create secret generic mcp-tunnel-cert \
     --from-file=tls.crt=data/tls.crt \
     --from-file=tls.key=data/tls.key

   
4. 4

   기본값 가져오기

   helm show values \
     oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
     --version 2.1.0 > values.yaml

   
5. 5

   수동 프로비저닝을 위한 값 구성

   values.yaml을 편집하여 다음 키를 설정하세요:

   values.yaml

   

   setup:
     enabled: false
   
   external:
     tunnelTokenSecretName: mcp-tunnel-token   # must contain key: tunnel-token
     serverCertSecretName: mcp-tunnel-cert     # must contain keys: tls.crt, tls.key
   
   gateway:
     config:
       # Required when setup.enabled is false. Replace the placeholder with
       # the $TUNNEL_DOMAIN value you exported earlier. When setup.enabled
       # is true the chart injects this from the Secret as a -tunnel-domain
       # flag instead.
       tunnel_domain: YOUR_TUNNEL_DOMAIN_HERE
       routes:
         docs: http://docs-mcp.internal:8080
         search: http://search-mcp.internal:8080

   일부 관리형 Kubernetes 배포판은 Service CIDR을 표준 사설 대역 밖에 할당합니다. 라우트가 클러스터 내부 Service를 대상으로 하는 경우, 업스트림 IP 검증에 설명된 대로 여기에 gateway.config.upstream.allowed_ips를 추가하세요.

6. 6

   렌더링된 매니페스트 검토

   helm template mcp-tunnel \
     oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
     --version 2.1.0 \
     -n mcp-tunnel \
     -f values.yaml > rendered.yaml

   
7. 7

   설치

   helm install mcp-tunnel \
     oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
     --version 2.1.0 \
     --namespace mcp-tunnel --create-namespace \
     -f values.yaml

   