Helm으로 MCP 터널 배포하기

Anthropic Helm 차트는 터널 스택을 단일 Deployment로 설치하고 이를 터널에 연결합니다. 터널은 차트의 setup 훅이 생성해 주는 것이거나, Console에서 직접 생성한 기존 터널일 수 있습니다.

시작하기 전에

다음이 필요합니다:

• 터널. 프로그래매틱 액세스를 사용하는 경우, 터널 ID를 제공하지 않으면 차트의 setup 훅이 터널을 생성해 줍니다. 대신 기존 터널에 연결하려면 Console에서 터널을 생성하고 터널 ID(tnl_...)를 기록해 두세요. 수동 프로비저닝은 항상 Console에서 생성한 터널에서 시작하며, 해당 터널의 터널 토큰과 터널 도메인도 필요합니다.
• 차트가 Tunnels API에 인증할 수 있는 방법.
  • 프로그래매틱 액세스(권장). setup 컴포넌트가 Workload Identity Federation을 통해 인증하고, 터널 토큰을 가져오고, CA를 생성하여 Anthropic에 등록한 뒤, 모든 것을 Secret에 저장합니다. workspace:manage_tunnels 범위로 지정된 페더레이션 규칙이 필요합니다.
  • 수동. 프로그래매틱 액세스를 건너뜁니다. Console에서 터널 토큰을 가져오고, CA와 서버 인증서를 직접 생성하고, Console에 CA를 등록한 다음, 자격 증명을 Secret으로 클러스터에 제공합니다.
• helm과 kubectl로 배포할 수 있는 Kubernetes 클러스터. 프로그래매틱 액세스 없이 탭에서는 openssl(1.1.1 이상)도 사용합니다.
• 클러스터에서 api.anthropic.com(443 TCP) 및 터널 엣지(7844 TCP 및 UDP)로의 아웃바운드 네트워크 연결. 전체 네트워크 요구 사항을 참조하세요.
• gateway.config.routes 아래에 구성할 주소에서 클러스터로부터 접근 가능하며 실행 중인 하나 이상의 MCP 서버. 아직 없다면 샘플 서버를 사용하세요.

선택 사항: 샘플 MCP 서버 사용하기

테스트에 사용할 수 있는 MCP 서버가 없다면 다음의 최소 서버를 사용하세요:

kubectl create namespace mcp-tunnel --dry-run=client -o yaml | kubectl apply -f -
kubectl -n mcp-tunnel apply -f - <<'EOF'
apiVersion: v1
kind: ConfigMap
metadata:
  name: hello-mcp-src
data:
  hello_server.py: |
    from mcp.server.fastmcp import FastMCP

    mcp = FastMCP("hello-server", host="0.0.0.0", port=9000)


    @mcp.tool()
    def hello(name: str = "world") -> str:
        """Say hello to someone."""
        return f"Hello, {name}!"


    if __name__ == "__main__":
        mcp.run(transport="streamable-http")
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello-mcp
spec:
  replicas: 1
  selector:
    matchLabels: { app: hello-mcp }
  template:
    metadata:
      labels: { app: hello-mcp }
    spec:
      containers:
        - name: hello-mcp
          image: python:3.13-slim
          command: ["sh", "-c", "pip install --quiet mcp && python /app/hello_server.py"]
          volumeMounts:
            - { name: src, mountPath: /app }
          ports:
            - { containerPort: 9000 }
      volumes:
        - name: src
          configMap: { name: hello-mcp-src }
---
apiVersion: v1
kind: Service
metadata:
  name: hello-mcp
spec:
  selector: { app: hello-mcp }
  ports:
    - { port: 9000, targetPort: 9000 }
EOF

이어지는 설치 단계에서 해당 라우트를 어디에 추가해야 하는지 안내합니다.

설치

배포 검증하기

Anthropic 측에서 엔드 투 엔드로 검증하세요. Managed Agent 세션 또는 Messages API 요청에서 https://<route>.<your-tunnel-domain>/<path>를 사용하세요. 여기서 <route>는 gateway.config.routes의 키이고 <path>는 업스트림 MCP 서버가 서비스하는 경로입니다. 샘플 MCP 서버의 경우 https://echo.<your-tunnel-domain>/mcp입니다. 요청 형식은 터널링된 MCP 서버 사용하기를 참조하세요.

실패하면 파드 로그(kubectl -n mcp-tunnel logs deploy/mcp-tunnel -c mcp-proxy 및 -c cloudflared)를 확인하고 문제 해결을 참조하세요.

선택적 구성

NetworkPolicy로 이그레스 제한하기

프록시 파드로의 인그레스는 기본적으로 거부됩니다(networkPolicy.ingress.enabled: true). 파드 이그레스를 추가로 제한하려면 networkPolicy.egress.enabled: true를 설정하고 networkPolicy.egress.mcpServers에 업스트림 MCP 서버를 포함하는 파드 레이블 셀렉터 또는 CIDR 범위를 채우세요. cloudflared에서 터널 엣지로의 이그레스는 networkPolicy.egress.cloudflaredEgressCIDRs를 통해 별도로 허용됩니다.

프록시 튜닝하기

gateway.config.* 아래의 필드는 프록시 구성 파일로 그대로 전달됩니다. 일반적인 조정 항목으로는 upstream.allowed_ips, log_level, upstream.tls가 있습니다. 전체 필드 목록은 프록시 구성 레퍼런스를 참조하세요. 차트는 항상 listen_addr, tls.cert_file, tls.key_file을 설정하므로, gateway.config에서 이를 설정해도 효과가 없습니다.

자체 OIDC 토큰 제공하기

기본적으로 차트는 setup 컴포넌트를 위해 Kubernetes ServiceAccount 토큰을 프로젝션합니다. 다른 ID 공급자(예: SPIFFE, Vault 또는 클라우드 SDK 사이드카)의 토큰을 사용하려면 setup.extraVolumes 및 setup.extraVolumeMounts로 마운트하세요. 그런 다음 api.wif.tokenFile을 마운트 경로로 지정하세요. 차트는 ANTHROPIC_IDENTITY_TOKEN_FILE을 해당 경로로 설정하고, setup 컴포넌트는 거기서 토큰을 읽습니다.

업그레이드

예기치 않게 더 새로운 차트를 가져오지 않도록 helm upgrade에 항상 --version을 전달하세요.

차트 1.x에서 업그레이드하기

차트 2.0.0은 터널 ID를 api.wif.tunnelId에서 tunnel.id로 옮깁니다. 업그레이드하기 전에 values.yaml을 편집하세요. tnl_... 값을 tunnel.id로 옮기고 api.wif.tunnelId를 제거하세요. tunnel.id를 설정하지 않은 채로 두어도 안전하지만(setup 컴포넌트는 재실행 시 mcp-tunnel Secret에 이미 저장된 터널 ID를 재사용합니다), 명시적으로 옮기면 values.yaml이 정확하게 유지됩니다. 또한 Console에서 페더레이션 규칙의 범위를 org:manage_tunnels에서 workspace:manage_tunnels로 업데이트하세요.

구성 변경하기

라우트, 레플리카 수 또는 NetworkPolicy와 같은 일상적인 변경의 경우:

helm upgrade mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 2.0.2 \
  -n mcp-tunnel \
  -f values.yaml

터널 토큰 교체하기

프로그래매틱 액세스를 사용하는 경우, values.yaml에서 tunnel.tokenVersion을 증가시키고 --set setup.force=true로 업그레이드하세요. setup 컴포넌트는 강제된 경우에만 업그레이드 시 다시 실행됩니다:

helm upgrade mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 2.0.2 \
  -n mcp-tunnel \
  -f values.yaml \
  --set setup.force=true

setup 컴포넌트는 Workload Identity Federation으로 인증하므로, 폐기할 API 토큰이 없습니다.

프로그래매틱 액세스를 사용하지 않는 경우, Console의 터널 상세 페이지에서 Rotate token을 클릭한 다음 mcp-tunnel-token Secret을 업데이트하세요:

kubectl -n mcp-tunnel create secret generic mcp-tunnel-token \
  --from-literal=tunnel-token='eyJ...' --dry-run=client -o yaml | kubectl apply -f -
kubectl -n mcp-tunnel rollout restart deploy/mcp-tunnel

인증서 갱신

차트는 자동화를 제공하지만, 만료를 모니터링하고 갱신이 완료되었는지 확인하는 책임은 여전히 사용자에게 있습니다.

프로그래매틱 액세스를 사용하는 경우 인증서 갱신은 자동입니다. 차트는 setup renew-cert를 매일(serverCert.cronSchedule, 기본값 0 0 * * * UTC) 실행하는 CronJob(Helm fullname을 따라 이름이 지정되고 -cert-renew 접미사가 붙음)을 배포합니다. 인증서가 만료까지 serverCert.renewBefore(기본값 30일) 이내가 아니면 이 작업은 아무것도 하지 않습니다. 갱신은 로컬에서 이루어집니다. 작업은 Secret에 이미 저장된 CA로 새 인증서에 서명하고, API 호출을 하지 않으며, 차트가 부여하는 Kubernetes RBAC만 필요합니다. 프록시는 Secret 마운트에서 인증서를 핫 리로드하므로 Deployment 재시작이 필요하지 않습니다.

프로그래매틱 액세스를 사용하지 않는 경우 CronJob이 없습니다. 설치 후 보관해 둔 mcp-tunnel/ 디렉터리 안에서 기존 CA로 새 서버 인증서에 서명하세요(CA를 다시 생성하지 마세요):

export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE
openssl req -new -key 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

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

프록시는 Secret 마운트에서 인증서를 핫 리로드합니다.

다음 단계