MessagesMCP 터널

Helm으로 MCP 터널 배포하기

Anthropic Helm 차트를 사용하여 Kubernetes 클러스터에 터널 스택을 설치합니다.

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

Anthropic Helm 차트는 터널 스택을 단일 Deployment로 설치하고 Console에서 생성한 터널에 연결합니다.

시작하기 전에

다음이 필요합니다:

Console에서 생성한 터널. 먼저 터널 생성을 완료하고 터널 ID(tnl_...)를 기록하세요. 수동 프로비저닝의 경우 해당 단계에서 터널 토큰과 터널 도메인도 필요합니다.
차트가 Tunnels API에 인증할 수 있는 방법.
- 프로그래매틱 액세스(권장). setup 컴포넌트가 Workload Identity Federation을 통해 인증하고, 터널 토큰을 가져오고, CA를 생성하고, Anthropic에 등록하고, 모든 것을 Secret에 저장합니다. org:manage_tunnels 범위로 지정된 federation rule이 필요합니다.
- 수동. 프로그래매틱 액세스를 건너뜁니다. 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로 egress 제한

프록시 파드로의 ingress는 기본적으로 거부됩니다(networkPolicy.ingress.enabled: true). 추가로 파드 egress를 제한하려면 networkPolicy.egress.enabled: true를 설정하고 업스트림 MCP 서버를 포함하는 파드 레이블 셀렉터 또는 CIDR 범위로 networkPolicy.egress.mcpServers를 채우세요. cloudflared에서 터널 엣지로의 egress는 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 토큰을 project합니다. 다른 ID 공급자(예: SPIFFE, Vault, 또는 cloud-SDK 사이드카)의 토큰을 사용하려면 setup.extraVolumes 및 setup.extraVolumeMounts로 마운트하세요. 그런 다음 api.wif.tokenFile을 마운트 경로로 지정하세요. 차트는 ANTHROPIC_IDENTITY_TOKEN_FILE을 해당 경로로 설정하고, setup 컴포넌트는 거기서 토큰을 읽습니다.

업그레이드

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

구성 변경

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

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

--reuse-values에 의존하기보다는 완전한 values.yaml을 유지하세요. Helm의 deep-merge 동작은 삭제된 라우트를 제거하지 못하고 조용히 실패할 수 있습니다.

터널 토큰 교체

프로그래매틱 액세스를 사용하는 경우, 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 1.0.0 \
  -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

Rotate token을 클릭하면 현재 토큰이 즉시 무효화됩니다. Secret이 업데이트되고 롤아웃이 완료될 때까지, 이전 토큰으로 재시작하는 모든 파드(eviction, node drain, OOM)는 다시 연결할 수 없습니다. 교체 후 즉시 Secret을 업데이트하세요. 더 엄격한 가용성 요구 사항이 있는 경우 차트가 교체를 원자적으로 처리하도록 프로그래매틱 액세스를 사용하세요.

인증서 갱신

차트는 자동화를 제공하지만, 만료 모니터링과 갱신 완료 확인은 여전히 사용자의 책임입니다.

프로그래매틱 액세스를 사용하는 경우 인증서 갱신은 자동입니다. 차트는 매일(serverCert.cronSchedule에서, 기본값 0 0 * * * UTC) setup renew-cert를 실행하는 CronJob(Helm fullname을 따라 이름이 지정되고 -cert-renew 접미사가 붙음)을 배포합니다. 인증서가 만료까지 serverCert.renewBefore(기본값 30일) 이내가 아니면 job은 아무 작업도 수행하지 않습니다. 갱신은 로컬에서 이루어집니다: job은 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 마운트에서 인증서를 핫 리로드합니다.

다음 단계

터널링된 MCP 서버 사용

업스트림 MCP 서버를 Managed Agent 또는 Messages API에 연결합니다.

보안

강화 지침, 자격 증명 교체 및 침해 대응.

문제 해결

연결, TLS 및 라우팅 문제를 진단합니다.

Was this page helpful?

MessagesMCP 터널

Helm으로 MCP 터널 배포하기

Anthropic Helm 차트를 사용하여 Kubernetes 클러스터에 터널 스택을 설치합니다.

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

Anthropic Helm 차트는 터널 스택을 단일 Deployment로 설치하고 Console에서 생성한 터널에 연결합니다.

시작하기 전에

다음이 필요합니다:

Console에서 생성한 터널. 먼저 터널 생성을 완료하고 터널 ID(tnl_...)를 기록하세요. 수동 프로비저닝의 경우 해당 단계에서 터널 토큰과 터널 도메인도 필요합니다.
차트가 Tunnels API에 인증할 수 있는 방법.
- 프로그래매틱 액세스(권장). setup 컴포넌트가 Workload Identity Federation을 통해 인증하고, 터널 토큰을 가져오고, CA를 생성하고, Anthropic에 등록하고, 모든 것을 Secret에 저장합니다. org:manage_tunnels 범위로 지정된 federation rule이 필요합니다.
- 수동. 프로그래매틱 액세스를 건너뜁니다. 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

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

설치

배포 확인

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

선택적 구성

NetworkPolicy로 egress 제한

프록시 튜닝

자체 OIDC 토큰 제공

업그레이드

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

구성 변경

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

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

--reuse-values에 의존하기보다는 완전한 values.yaml을 유지하세요. Helm의 deep-merge 동작은 삭제된 라우트를 제거하지 못하고 조용히 실패할 수 있습니다.

터널 토큰 교체

helm upgrade mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 1.0.0 \
  -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

인증서 갱신

차트는 자동화를 제공하지만, 만료 모니터링과 갱신 완료 확인은 여전히 사용자의 책임입니다.

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 마운트에서 인증서를 핫 리로드합니다.

다음 단계

터널링된 MCP 서버 사용

업스트림 MCP 서버를 Managed Agent 또는 Messages API에 연결합니다.

보안

강화 지침, 자격 증명 교체 및 침해 대응.

문제 해결

연결, TLS 및 라우팅 문제를 진단합니다.

Was this page helpful?