Deploy tunnel MCP dengan Helm

Helm chart Anthropic menginstal tunnel stack sebagai satu Deployment dan melampirkannya ke tunnel Anda: tunnel yang dibuat oleh setup hook chart untuk Anda, atau tunnel yang sudah ada yang Anda buat di Console.

Sebelum Anda memulai

Anda memerlukan:

• Sebuah tunnel. Dengan akses programatik, setup hook chart membuatkannya untuk Anda ketika Anda tidak menyediakan ID tunnel; untuk melampirkan ke tunnel yang sudah ada, buat tunnel tersebut di Console dan catat ID tunnel-nya (tnl_...). Penyediaan manual selalu dimulai dari tunnel yang dibuat di Console; Anda juga memerlukan token tunnel dan domain tunnel-nya.
• Cara bagi chart untuk melakukan autentikasi ke Tunnels API.
  • Akses programatik (direkomendasikan). Komponen setup melakukan autentikasi melalui Workload Identity Federation, mengambil token tunnel, menghasilkan CA, mendaftarkannya ke Anthropic, dan menyimpan semuanya dalam sebuah Secret. Anda memerlukan federation rule dengan cakupan workspace:manage_tunnels.
  • Manual. Lewati akses programatik. Anda akan mendapatkan token tunnel dari Console, menghasilkan CA dan sertifikat server sendiri, mendaftarkan CA di Console, dan menyediakan kredensial ke cluster sebagai Secret.
• Sebuah cluster Kubernetes yang dapat Anda deploy menggunakan helm dan kubectl. Tab Tanpa akses programatik juga menggunakan openssl (1.1.1 atau lebih baru).
• Konektivitas jaringan keluar dari cluster ke api.anthropic.com (443 TCP) dan tunnel edge (7844 TCP dan UDP). Lihat persyaratan jaringan selengkapnya.
• Satu atau lebih server MCP yang berjalan dan dapat dijangkau dari cluster pada alamat yang akan Anda konfigurasikan di bawah gateway.config.routes. Jika Anda belum memilikinya, gunakan server contoh.

Opsional: Gunakan server MCP contoh

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 ini mencatat di mana 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 path apa pun yang dilayani server MCP upstream. Dengan server MCP contoh, itu adalah https://echo.<your-tunnel-domain>/mcp. Lihat Gunakan 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 membatasi egress pod lebih lanjut, atur networkPolicy.egress.enabled: true dan isi networkPolicy.egress.mcpServers dengan pod label selector 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 selengkapnya. 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 lain (seperti SPIFFE, Vault, atau sidecar cloud-SDK), mount token tersebut dengan setup.extraVolumes dan setup.extraVolumeMounts. Kemudian arahkan api.wif.tokenFile ke path mount tersebut. Chart mengatur ANTHROPIC_IDENTITY_TOKEN_FILE ke path itu, dan komponen setup membaca token dari sana.

Upgrade

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

Upgrade dari chart 1.x

Chart 2.0.0 memindahkan ID tunnel dari api.wif.tunnelId ke tunnel.id. Sebelum melakukan upgrade, edit values.yaml Anda: pindahkan nilai tnl_... ke tunnel.id dan hapus api.wif.tunnelId. Membiarkan tunnel.id tidak diatur aman (komponen setup menggunakan kembali ID tunnel yang sudah tersimpan di Secret mcp-tunnel saat dijalankan ulang), tetapi pemindahan eksplisit menjaga values.yaml Anda tetap akurat. Perbarui juga cakupan federation rule Anda dari org:manage_tunnels ke workspace:manage_tunnels di Console.

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 2.0.2 \
  -n mcp-tunnel \
  -f values.yaml

Rotasi token tunnel

Dengan akses programatik, naikkan tunnel.tokenVersion di values.yaml dan lakukan 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 2.0.2 \
  -n mcp-tunnel \
  -f values.yaml \
  --set setup.force=true

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

Tanpa akses programatik, klik Rotate token di 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 memastikan pembaruan selesai.

Dengan akses programatik, pembaruan sertifikat berlangsung 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 pun kecuali sertifikat berada dalam rentang serverCert.renewBefore dari masa kedaluwarsa (default 30 hari). Pembaruan bersifat lokal: job menandatangani sertifikat baru dengan CA yang sudah tersimpan di Secret, tidak melakukan panggilan API, dan hanya memerlukan RBAC Kubernetes yang diberikan chart. Proxy melakukan hot-reload sertifikat dari mount Secret, sehingga tidak diperlukan restart Deployment.

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