Deploy MCP tunnel dengan Helm

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



Sebelum Anda mulai

Anda memerlukan:

• Sebuah tunnel. Dengan akses terprogram, setup hook chart akan membuatnya untuk Anda ketika Anda tidak menyediakan ID tunnel; untuk menghubungkan ke tunnel yang sudah ada, buat di Console dan catat ID tunnel (tnl_...). Provisioning manual selalu dimulai dari tunnel yang dibuat di Console; Anda juga akan memerlukan token tunnel dan domain tunnel-nya.
• 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 akan memerlukan aturan federasi dengan scope workspace: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 key dari gateway.config.routes dan <path> adalah apa pun yang disajikan 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 selector 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.



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 adalah 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 scope aturan federasi 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 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 2.0.2 \
  -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 kedaluwarsa dan memastikan 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 adalah no-op kecuali sertifikat berada dalam serverCert.renewBefore dari 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 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