Deploy tunnel MCP dengan Helm

Helm chart Anthropic menginstal tunnel stack sebagai satu Deployment dan menghubungkannya ke tunnel yang Anda buat di Console.

Sebelum Anda mulai

Anda memerlukan:

• Tunnel yang dibuat di Console. Selesaikan Membuat tunnel terlebih dahulu dan catat ID tunnel (tnl_...). Untuk penyediaan manual, Anda juga memerlukan token tunnel dan domain tunnel dari langkah tersebut.
• Cara bagi chart untuk mengautentikasi ke Tunnels API.
  • Akses terprogram (direkomendasikan). Komponen setup mengautentikasi melalui Workload Identity Federation, mengambil token tunnel, menghasilkan CA, mendaftarkannya ke Anthropic, dan menyimpan semuanya dalam sebuah Secret. Anda memerlukan aturan federasi dengan cakupan org:manage_tunnels.
  • Manual. Lewati akses terprogram. Anda akan mendapatkan token tunnel dari Console, menghasilkan CA dan sertifikat server sendiri, mendaftarkan CA di Console, dan menyediakan kredensial ke klaster sebagai Secret.
• Klaster Kubernetes yang dapat Anda deploy dengan helm dan kubectl. Tab Tanpa akses terprogram juga menggunakan openssl (1.1.1 atau lebih baru).
• Konektivitas jaringan keluar dari klaster ke api.anthropic.com (443 TCP) dan tunnel edge (7844 TCP dan UDP). Lihat persyaratan jaringan lengkap.
• Satu atau lebih server MCP yang berjalan dan dapat dijangkau dari klaster pada alamat yang akan Anda konfigurasikan di bawah gateway.config.routes. Jika Anda belum memilikinya, gunakan server sampel.

Opsional: Gunakan server MCP sampel

Jika Anda tidak memiliki server MCP yang tersedia untuk pengujian, gunakan server minimal ini:

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

Langkah-langkah Instal berikut mencatat di mana harus menambahkan route yang sesuai.

Instal

Verifikasi deployment

Verifikasi secara end-to-end dari sisi Anthropic: gunakan https://<route>.<your-tunnel-domain>/<path> dalam sesi Managed Agent atau permintaan Messages API, di mana <route> adalah kunci dari gateway.config.routes dan <path> adalah apa pun yang dilayani oleh server MCP upstream. Dengan server MCP sampel, itu adalah https://echo.<your-tunnel-domain>/mcp. Lihat Menggunakan server MCP yang di-tunnel untuk bentuk permintaannya.

Jika gagal, periksa log pod (kubectl -n mcp-tunnel logs deploy/mcp-tunnel -c mcp-proxy dan -c cloudflared) dan lihat Pemecahan masalah.

Konfigurasi opsional

Batasi egress dengan NetworkPolicy

Ingress ke pod proxy ditolak secara default (networkPolicy.ingress.enabled: true). Untuk juga membatasi egress pod, atur networkPolicy.egress.enabled: true dan isi networkPolicy.egress.mcpServers dengan selektor label pod atau rentang CIDR yang mencakup server MCP upstream Anda. Egress dari cloudflared ke tunnel edge diizinkan secara terpisah melalui networkPolicy.egress.cloudflaredEgressCIDRs.

Sesuaikan proxy

Field di bawah gateway.config.* diteruskan ke file konfigurasi proxy. Penyesuaian umum mencakup upstream.allowed_ips, log_level, dan upstream.tls. Lihat referensi konfigurasi proxy untuk daftar field lengkap. Chart selalu mengatur listen_addr, tls.cert_file, dan tls.key_file; mengaturnya di gateway.config tidak berpengaruh.

Sediakan token OIDC Anda sendiri

Secara default, chart memproyeksikan token ServiceAccount Kubernetes untuk komponen setup. Untuk menggunakan token dari penyedia identitas yang berbeda (seperti SPIFFE, Vault, atau sidecar cloud-SDK), mount token tersebut dengan setup.extraVolumes dan setup.extraVolumeMounts. Kemudian arahkan api.wif.tokenFile ke path mount. Chart mengatur ANTHROPIC_IDENTITY_TOKEN_FILE ke path tersebut, dan komponen setup membaca token dari sana.

Upgrade

Selalu sertakan --version pada helm upgrade agar Anda tidak menarik chart yang lebih baru secara tidak terduga.

Ubah konfigurasi

Untuk perubahan rutin seperti route, jumlah replika, atau 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

Rotasi token tunnel

Dengan akses terprogram, tingkatkan tunnel.tokenVersion di values.yaml dan upgrade dengan --set setup.force=true. Komponen setup hanya berjalan ulang pada upgrade ketika dipaksa:

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

Komponen setup mengautentikasi dengan Workload Identity Federation; tidak ada token API yang perlu dicabut.

Tanpa akses terprogram, klik Rotate token pada halaman detail tunnel di Console, lalu perbarui Secret mcp-tunnel-token:

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

Pembaruan sertifikat

Chart menyediakan otomatisasi, tetapi Anda tetap bertanggung jawab untuk memantau masa berlaku dan mengonfirmasi bahwa pembaruan selesai.

Dengan akses terprogram, pembaruan sertifikat bersifat otomatis. Chart men-deploy CronJob (dinamai berdasarkan fullname Helm, dengan akhiran -cert-renew) yang menjalankan setup renew-cert setiap hari (pada serverCert.cronSchedule, default 0 0 * * * UTC). Job ini tidak melakukan apa-apa kecuali sertifikat berada dalam serverCert.renewBefore dari masa berlaku (default 30 hari). Pembaruan bersifat lokal: job menandatangani sertifikat baru dengan CA yang sudah disimpan di Secret, tidak melakukan panggilan API, dan hanya memerlukan RBAC Kubernetes yang diberikan oleh chart. Proxy melakukan hot-reload sertifikat dari mount Secret, sehingga tidak diperlukan restart Deployment.

Tanpa akses terprogram, tidak ada CronJob. Dari dalam direktori mcp-tunnel/ yang Anda simpan setelah instalasi, tandatangani sertifikat server baru dengan CA yang ada (jangan regenerasi 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 -

Proxy melakukan hot-reload sertifikat dari mount Secret.

Langkah selanjutnya