Claude Platform Docs
MessagesTunnel MCP

Menerapkan MCP tunnel dengan Helm

Instal tunnel stack pada klaster Kubernetes menggunakan Helm chart Anthropic.

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

Sebelum Anda mulai

Anda memerlukan:

  • Sebuah tunnel. Dengan akses terprogram, setup hook chart membuatkan tunnel untuk Anda ketika Anda tidak memberikan 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 tunnel token dan tunnel domain-nya.
  • Cara bagi chart untuk mengautentikasi ke Tunnels API.
    • Akses terprogram (direkomendasikan). Komponen setup melakukan autentikasi melalui Workload Identity Federation, mengambil tunnel token, menghasilkan CA, mendaftarkannya ke Anthropic, dan menyimpan semuanya dalam sebuah Secret. Anda memerlukan federation rule dengan cakupan workspace:manage_tunnels.
    • Manual. Lewati akses terprogram. Anda akan mendapatkan tunnel token dari Console, membuat CA dan sertifikat server sendiri, mendaftarkan CA di Console, dan menyediakan kredensial ke klaster sebagai Secret.
  • Sebuah klaster Kubernetes yang dapat Anda gunakan untuk 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 selengkapnya.
  • 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 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 Instalasi berikut menunjukkan di mana menambahkan route yang sesuai.

Instalasi

Komponen setup menukarkan token ServiceAccount terproyeksi milik klaster melalui federation rule Anda, mengambil tunnel token, membuat CA dan sertifikat server, serta mendaftarkan CA ke Anthropic. CronJob harian memperbarui sertifikat server sesuai kebutuhan, sehingga Anda tidak perlu menangani secret apa pun secara manual.

  1. Siapkan Workload Identity Federation untuk klaster

    Ikuti Menggunakan WIF dengan Kubernetes untuk mendaftarkan OIDC issuer klaster Anda dan membuat federation rule. Komponen setup berjalan di bawah ServiceAccount-nya sendiri di namespace rilis; nama persisnya mengikuti konvensi fullname Helm, jadi untuk nama rilis apa pun selain mcp-tunnel, jalankan helm template <release> ... | grep -A2 'kind: ServiceAccount' untuk memastikannya sebelum membuat rule. Bagian selanjutnya dari panduan ini mengasumsikan nama rilis mcp-tunnel di namespace mcp-tunnel, dengan ServiceAccount mcp-tunnel-setup.

    BidangNilai
    Subjectsystem:serviceaccount:mcp-tunnel:mcp-tunnel-setup
    Audienceapi.anthropic.com (default chart; tanpa skema)
    Scopeworkspace:manage_tunnels

    Jika tunnel berada di workspace selain workspace default organisasi, tambahkan juga service account rule tersebut ke workspace itu (Tunnels API melakukan otorisasi berdasarkan keanggotaan workspace service account).

    Catat ID rule (fdrl_...); Anda akan mengaturnya sebagai api.wif.federationRuleId.

  2. Ambil nilai default

    helm show values \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 2.1.0 > values.yaml

  3. Konfigurasikan lampiran tunnel dan route

    Edit values.yaml dan atur kunci api.wif.* dengan ID federation rule dan ID organisasi, ditambah entri routes untuk setiap server MCP upstream:

    values.yaml
    api:
  wif:
    federationRuleId: "fdrl_..."
    organizationId: "00000000-0000-0000-0000-000000000000"
    # Set when the tunnel is in a non-default workspace and the
    # rule's service account is a member of that workspace.
    # workspaceId: "wrkspc_..."

tunnel:
  # Leave empty to have the setup hook create a tunnel during install.
  # Set to attach to an existing tunnel from the Console.
  id: ""
  # Increment to rotate the tunnel token on the next upgrade.
  # See the "Rotate the tunnel token" section.
  tokenVersion: "1"

gateway:
  config:
    routes:
      docs: http://docs-mcp.internal:8080
      search: http://search-mcp.internal:8080

    Dengan route ini, Claude menjangkau server di docs.<your-tunnel-domain> dan search.<your-tunnel-domain>. Beberapa distribusi Kubernetes terkelola mengalokasikan Service CIDR di luar rentang privat standar; jika route Anda menargetkan Service di dalam klaster, tambahkan gateway.config.upstream.allowed_ips di sini seperti dijelaskan dalam Validasi IP upstream.

  4. Tinjau manifest yang dirender

    Render chart dan tinjau output-nya sesuai dengan praktik pemeriksaan organisasi Anda:

    helm template mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 2.1.0 \
  -n mcp-tunnel \
  -f values.yaml > rendered.yaml

  5. Instal

    helm install mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 2.1.0 \
  --namespace mcp-tunnel --create-namespace \
  -f values.yaml

    Komponen setup berjalan sebagai Job hook pre-install Helm, sehingga helm install akan menunggu hingga Job selesai. Jika berhasil, Helm menghapus Job secara otomatis. Jika helm install gagal dengan error hook, lihat Kegagalan autentikasi komponen setup.

    Ketika tunnel.id kosong, komponen setup membuat tunnel di workspace yang ditargetkan oleh federation rule Anda (workspace default organisasi kecuali Anda mengatur api.wif.workspaceId) dan menyimpan ID serta domain-nya di Secret mcp-tunnel. Temukan domain yang Anda perlukan untuk verifikasi di halaman detail tunnel, yang Anda buka dari halaman MCP tunnels (platform.claude.com/settings/workspaces/default/mcp-tunnels) di Console. Di pemilih workspace pada sidebar, pilih workspace yang berisi tunnel tersebut. Anda juga dapat membaca domain dari Secret:

    kubectl -n mcp-tunnel get secret mcp-tunnel \
  -o jsonpath='{.data.tunnel-domain}' | base64 -d

    Menjalankan ulang komponen setup (selama upgrade atau rotasi token) menggunakan kembali ID tunnel yang tersimpan di Secret ini; komponen ini tidak pernah membuat tunnel kedua.

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, dengan <route> adalah kunci dari gateway.config.routes dan <path> adalah path apa pun yang dilayani oleh server MCP upstream. Dengan server MCP contoh, 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

Membatasi egress dengan NetworkPolicy

Ingress ke pod proxy ditolak secara default (networkPolicy.ingress.enabled: true). Untuk membatasi egress pod juga, 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.

Menyetel proxy

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

Menyediakan 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 tetap 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.

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

Merotasi tunnel token

Dengan akses terprogram, naikkan tunnel.tokenVersion di values.yaml dan lakukan upgrade dengan --set setup.force=true. Komponen setup hanya dijalankan ulang saat upgrade jika dipaksa:

helm upgrade mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 2.1.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 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 terprogram, 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 sebelum 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 oleh chart. Proxy memuat ulang sertifikat secara langsung (hot-reload) dari mount Secret, sehingga tidak perlu me-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 sudah ada (jangan membuat 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 memuat ulang sertifikat secara langsung (hot-reload) dari mount Secret.

Langkah selanjutnya

Menggunakan server MCP yang di-tunnel

Lampirkan server MCP upstream ke Managed Agent atau Messages API.

Keamanan

Panduan hardening, rotasi kredensial, dan respons terhadap pelanggaran.

Pemecahan masalah

Diagnosis masalah konektivitas, TLS, dan routing.

Was this page helpful?