Terowongan MCP | Anthropic Help Center

Apa itu?

Hubungkan Claude dengan aman ke server MCP yang berjalan di jaringan pribadi Anda tanpa membuka port masuk atau mengekspos layanan ke internet. MCP Tunnels saat ini dalam beta pribadi dan mengandalkan layanan Tunnel Cloudflare.

Cara kerjanya

MCP Tunnels membuat koneksi antara Claude dan server MCP internal Anda yang dienkripsi dalam transit dengan beberapa lapisan keamanan.

Ketika Claude perlu menjangkau server MCP di jaringan pribadi Anda, permintaan berjalan melalui terowongan yang aman. Anda menerapkan dua komponen di sisi Anda:

cloudflared (agen terowongan Cloudflare)
MCP Gateway (disediakan oleh Anthropic)

Cloudflared memulai koneksi hanya keluar ke tepi Cloudflare. Tidak perlu membuka port masuk di firewall Anda. MCP Gateway menghentikan lapisan TLS dalam, memvalidasi IP hulu untuk mencegah SSRF, dan merutekan setiap permintaan ke server MCP yang benar berdasarkan subdomain.

Koneksi diamankan dengan tiga lapisan independen: mTLS luar antara Anthropic dan Cloudflare (dengan validasi IP), TLS dalam yang mengenkripsi muatan end-to-end dari backend Anthropic ke gateway Anda (dirancang sehingga Cloudflare tidak memiliki akses ke muatan MCP), dan autentikasi OAuth di lapisan aplikasi pada setiap server MCP.

Apa yang Anda terapkan

cloudflared

Agen terowongan Cloudflare. Memulai koneksi hanya keluar — tidak perlu port masuk.

MCP Gateway

Komponen yang disediakan Anthropic yang menghentikan TLS dalam, memvalidasi IP, dan merutekan permintaan ke server MCP Anda.

Properti keamanan utama

Tidak ada port masuk yang diperlukan. cloudflared memulai koneksi hanya keluar — firewall Anda tetap tertutup.
Enkripsi end-to-end. Lalu lintas dienkripsi dalam transit dari backend Anthropic ke gateway Anda. Muatan MCP tidak dapat dibaca oleh Cloudflare.
Pertahanan berlapis. Beberapa lapisan autentikasi: mTLS, TLS dalam, dan OAuth di lapisan aplikasi.
Perlindungan SSRF. Gateway memvalidasi IP hulu untuk membantu mencegah serangan pemalsuan permintaan.

Panduan ini menyediakan penyebaran referensi melalui Helm (untuk Kubernetes) dan Docker Compose. Anda bertanggung jawab untuk menyesuaikannya dengan persyaratan keamanan organisasi Anda.

Tanggung jawab bersama

Menjaga sistem ini tetap aman adalah tanggung jawab bersama antara Anthropic dan organisasi Anda.

Anthropic bertanggung jawab untuk:

Memastikan hanya Anthropic yang dapat mengakses terowongan
Memvalidasi sertifikat CA Anda sebelum terhubung ke gateway Anda
Memastikan Claude hanya mengirim permintaan ke terowongan yang dimiliki oleh organisasi Anda

Anda bertanggung jawab untuk:

Mengikuti panduan dalam dokumen ini dan panduan berikutnya
Mengamankan token terowongan dan kunci pribadi TLS
Mengonfigurasi server MCP Anda untuk menggunakan autentikasi OAuth seperti yang dijelaskan dalam spesifikasi MCP
Membatasi akses ke host gateway dan server MCP Anda ke personel yang sesuai
Memberi tahu Anthropic jika Anda mencurigai sistem telah dikompromikan (lihat Merespons pelanggaran yang dicurigai)

⚠️ Risiko kredensial. Jika penyerang memperoleh token terowongan Anda dan salah satu kunci pribadi TLS Anda, mereka dapat menyamar sebagai gateway Anda dan membaca muatan permintaan MCP, termasuk token OAuth. Lindungi kredensial ini sesuai dengan persyaratan keamanan organisasi Anda—termasuk izin file, enkripsi saat istirahat, dan manajemen rahasia.

Prasyarat

Target penyebaran — kluster Kubernetes (untuk Helm) atau VM dengan Docker dan Docker Compose.
Token API Anthropic untuk API Tunnels — buat satu dari claude.ai → Organization Settings → Connectors → Tunnels API. Setup menggunakan token ini untuk menyediakan terowongan dan mendaftarkan sertifikat CA Anda. Gateway tidak membutuhkannya saat runtime. Cabut setelah Anda menyelesaikan setup.
Akses jaringan — konektivitas keluar sesuai tabel di bawah.
Server MCP — satu atau lebih server MCP yang berjalan di jaringan pribadi Anda yang dapat dijangkau gateway.

Persyaratan jaringan

Komponen	Tujuan	Tujuan
Setup (satu kali)	`api.anthropic.com:443` (port 443)	Penyediaan terowongan
cloudflared	Tepi Cloudflare, port 7844 TCP/UDP (`198.41.192.0/19`, `2606:4700:a0::/44`)	Koneksi terowongan
Gateway MCP	Server MCP Anda	Lalu lintas hulu

Lihat dokumentasi firewall terowongan Cloudflare untuk daftar IP yang berwenang. Pengguna Helm dapat memberlakukan pembatasan egress ini dengan mengaktifkan nilai networkPolicy chart.

Pilih metode penyebaran Anda

Terowongan MCP dapat disebarkan melalui Helm (Kubernetes) atau Docker Compose. Pilih metode yang sesuai dengan infrastruktur Anda.

⎈ Helm / Kubernetes

Direkomendasikan untuk sebagian besar pelanggan. Mengotomatisasi penyediaan terowongan dan pembaruan sertifikat. Menyimpan kredensial sebagai Rahasia.

🐳 Docker Compose

Untuk penyebaran host tunggal atau VM.

Penyebaran Helm / Kubernetes

1. Ambil nilai chart

Unduh file nilai default. Ini mencakup komentar yang menjelaskan setiap bidang.

Shell

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

2. Konfigurasikan rute Anda

Edit values.yaml dan tambahkan setidaknya satu rute di bawah gateway.config.routes. Setiap rute memetakan awalan subdomain ke URL server MCP hulu.

3. Tinjau manifes yang dirender

Render chart dengan token placeholder untuk memeriksa sumber daya Kubernetes sebelum menginstal. Chart memerlukan api.token untuk dirender, tetapi helm template tidak memanggil API.

Shell

helm template mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 0.1.0 \
  -n mcp-tunnel \
  -f values.yaml \
  --set api.token=placeholder > rendered.yaml

Tinjau rendered.yaml sesuai dengan praktik organisasi Anda untuk memeriksa manifes pihak ketiga.

4. Instal chart

Simpan token API Anda dalam variabel lingkungan, lalu instal. Namespace khusus direkomendasikan untuk isolasi.

Shell

# Paste your API token (input is hidden)
read -rs API_TOKEN && export API_TOKEN

helm install mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 0.1.0 \
  --namespace mcp-tunnel --create-namespace \
  -f values.yaml \
  --set api.token="$API_TOKEN"

⚠️ Penting: Cabut token API setelah instalasi selesai. Melewatkan token melalui --set membuatnya tetap keluar dari file nilai Anda, tetapi Helm masih mencatatnya dalam riwayat rilis (sh.helm.release.v1.* Rahasia). Rahasia Kubernetes tidak dienkripsi saat istirahat secara default, jadi token tetap dapat dipulihkan dari cluster sampai Anda mencabut.

5. Ambil domain terowongan Anda

Pekerjaan setup menulis domain terowongan ke Rahasia. Anda memerlukan ini untuk mengonfigurasi server MCP di Claude.

Shell

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

Setelah terowongan aktif dan berjalan, hubungkan ke Claude.

Opsional: Aktifkan NetworkPolicy

Atur networkPolicy.enabled: true dalam file nilai Anda untuk membatasi egress pod terowongan di tingkat jaringan. Konfigurasikan networkPolicy.mcpServers dengan pemilih label pod atau rentang CIDR untuk server MCP hulu Anda. Kebijakan sudah mencakup aturan egress untuk cloudflared untuk menjangkau edge Cloudflare. CNI cluster Anda harus mendukung NetworkPolicy—lihat file nilai untuk contoh.

Opsional: Konfigurasi gateway

Bidang di bawah gateway.config.* diteruskan ke file konfigurasi gateway. Lihat Lampiran: Konfigurasi gateway untuk daftar lengkap. Penyesuaian umum mencakup upstream.allowed_ips, log_level, dan upstream.tls untuk rute https://. Untuk memasang file tambahan yang direferensikan konfigurasi (seperti bundel CA untuk upstream.tls.ca_file), gunakan gateway.extraVolumes dan gateway.extraVolumeMounts.

Peningkatan

Selalu tentukan --version pada helm upgrade. Tanpanya, Helm menarik versi chart terbaru dari registri, yang mungkin bukan yang Anda tinjau.

Untuk perubahan konfigurasi (rute, replika, NetworkPolicy, dll.), tidak ada token API yang diperlukan. Pekerjaan setup dilewati pada peningkatan kecuali Anda melewatkan api.token:

Shell

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

Untuk rotasi token terowongan, tingkatkan tunnel.tokenVersion dalam file nilai Anda, buat token API segar, dan tingkatkan:

Shell

# Paste your API token (input is hidden)
read -rs API_TOKEN && export API_TOKEN

helm upgrade mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 0.1.0 \
  -n mcp-tunnel \
  -f values.yaml \
  --set api.token="$API_TOKEN"

Cabut token API setelah peningkatan selesai.

Pertahankan file nilai lengkap daripada mengandalkan --reuse-values. Helm deep-merge bidang peta, jadi menghapus rute dengan --reuse-values gagal diam-diam.

Menggunakan helm template dengan kubectl atau kustomize

Jika Anda lebih suka merender manifes dan menerapkannya sendiri (melalui kubectl apply atau overlay kustomize), gunakan mode eksternal (setup.enabled: false). Sediakan terowongan secara terpisah (lihat Lampiran: API Terowongan) dan berikan kredensial sebagai Rahasia yang telah dibuat sebelumnya yang direferensikan oleh external.tunnelTokenSecretName dan external.serverCertSecretName. Jika Anda mengeluarkan sertifikat Anda sendiri daripada menggunakan biner setup, lihat Lampiran: Persyaratan sertifikat.

Penyebaran Docker Compose

1. Siapkan direktori penyebaran

Shell

mkdir -p mcp-gateway/{config,tunnel-data}
cd mcp-gateway
sudo chown 65532:65532 tunnel-data

chown memungkinkan kontainer (yang berjalan sebagai UID 65532) menulis ke direktori yang dipasang bind.

2. Buat docker-compose.yaml

YAML

services:
  # One-time provisioning. Run with: docker compose run --rm setup
  setup:
    image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-gateway@sha256:62ddf0897778c80997ca789189a8a0bd63df241659d661ff9d5b0e06b5ee1dcd
    entrypoint: ["/setup"]
    command:
      - init
      - --api-url=https://api.anthropic.com
      - --output=dir:/data
      - --token-version=1
    environment:
      - API_TOKEN
    volumes:
      - ./tunnel-data:/data
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    profiles: ["setup"]

  cloudflared:
    # Verify digest at https://hub.docker.com/r/cloudflare/cloudflared/tags
    image: cloudflare/cloudflared@sha256:6b599ca3e974349ead3286d178da61d291961182ec3fe9c505e1dd02c8ac31b0
    command: tunnel --no-autoupdate --config /etc/cloudflared/config.yaml run
    environment:
      - TUNNEL_TOKEN
    volumes:
      - ./config/cloudflared-config.yaml:/etc/cloudflared/config.yaml:ro
    restart: unless-stopped
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    stop_grace_period: 30s
    logging:
      options:
        max-size: "10m"
        max-file: "3"

  mcp-gateway:
    image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-gateway@sha256:62ddf0897778c80997ca789189a8a0bd63df241659d661ff9d5b0e06b5ee1dcd
    volumes:
      - ./config/mcp-gateway.yaml:/etc/mcp-gateway/config.yaml:ro
      - ./tunnel-data:/data:ro
    restart: unless-stopped
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    # Should match shutdown_timeout in mcp-gateway config
    stop_grace_period: 30s
    logging:
      options:
        max-size: "10m"
        max-file: "3"

Langkah-langkah keamanan: eksekusi non-root (UID 65532), sistem file read-only, tidak ada eskalasi hak istimewa, semua kemampuan Linux dijatuhkan, pengikat gambar oleh digest SHA256.

3. Sediakan terowongan

Shell

# Paste your API token (input is hidden)
read -rs API_TOKEN && export API_TOKEN

docker compose run --rm setup

Perintah setup membuat terowongan melalui Tunnels API, menghasilkan sertifikat CA dan server, mendaftarkan CA dengan Anthropic, dan menulis semua output ke ./tunnel-data/.

Ambil domain terowongan Anda untuk langkah berikutnya:

Shell

sudo cat tunnel-data/tunnel-domain

⚠️ Penting: Cabut token API sebelum melanjutkan.

4. Konfigurasi gateway

Buat config/mcp-gateway.yaml:

YAML

listen_addr: ":8080"
log_level: info
shutdown_timeout: 30s

# Your tunnel domain from Step 3
tunnel_domain: abcd1234.tunnel.anthropic.com

tls:
  cert_file: /data/tls.crt
  key_file: /data/tls.key

routes:
  # Replace with your actual MCP servers.
  # With tunnel_domain set, keys are subdomain prefixes.
  docs: http://docs-mcp.internal:8080
  search: http://search-mcp.internal:8080

upstream:
  allowed_ips:
    - 10.0.0.0/8

Lihat Lampiran: Konfigurasi gateway untuk semua bidang yang tersedia.

Buat config/cloudflared-config.yaml:

YAML

ingress:
  - service: http://mcp-gateway:8080

5. Terapkan

Shell

export TUNNEL_TOKEN=$(sudo cat tunnel-data/tunnel-token)
docker compose up -d
docker compose logs -f

Struktur direktori:

mcp-gateway/
├── docker-compose.yaml
├── config/
│   ├── cloudflared-config.yaml
│   └── mcp-gateway.yaml
└── tunnel-data/
    ├── tunnel-id
    ├── tunnel-domain
    ├── tunnel-token
    ├── token-version
    ├── ca.crt
    ├── ca.key
    ├── tls.crt
    └── tls.key

Pertimbangkan untuk memindahkan kunci privat CA dan token terowongan ke penyimpanan aman.

Untuk penyebaran multi-VM: salin direktori mcp-gateway/ ke setiap host. Token terowongan dan sertifikat yang sama berfungsi di semua replika.

Setelah terowongan aktif dan berjalan, hubungkan ke Claude.

Pembaruan sertifikat (Compose)

Sertifikat server memiliki validitas 90 hari. Perbarui sebelum kadaluarsa:

Shell

docker compose run --rm setup renew-cert --output=dir:/data

Gateway menyelidik file sertifikat setiap 30 detik dan memuat ulang secara otomatis saat berubah. Lihat Lampiran: Referensi CLI Setup untuk flag yang membuat perintah ini aman untuk dijalankan sesuai jadwal.

Rotasi token terowongan (Compose)

Edit docker-compose.yaml untuk menambah --token-version, kemudian jalankan kembali setup dengan token API baru:

# Paste your API token (input is hidden)
read -rs API_TOKEN && export API_TOKEN

docker compose run --rm setup

export TUNNEL_TOKEN=$(sudo cat tunnel-data/tunnel-token)
docker compose up -d cloudflared

Cabut token API setelah rotasi selesai.

Hubungkan ke Claude

Setelah terowongan berjalan, daftarkan server MCP Anda di Claude agar tersedia untuk pengguna.

1. Tambahkan server MCP

Admin organisasi menavigasi ke Organization Settings → Connectors → Add → Custom → Web di claude.ai.

Masukkan setiap server MCP menggunakan nama host terowongannya. Misalnya, docs.abcd1234.tunnel.anthropic.com. Awalan subdomain cocok dengan kunci rute dari konfigurasi gateway Anda.

2. Pengguna terhubung

Pengguna individual menavigasi ke Settings → Connectors dan klik Connect untuk setiap server MCP yang ingin mereka gunakan.

Menambahkan lebih banyak server nanti? Tambahkan rute baru ke konfigurasi Anda, terapkan perubahan (helm upgrade, atau docker compose restart mcp-gateway), dan daftarkan nama host baru di Claude. Tidak perlu perubahan sertifikat atau cloudflared. Sertifikat wildcard mencakup semua subdomain.

Praktik terbaik keamanan

Wajibkan OAuth di server MCP Anda. Lapisan terowongan dan TLS melindungi transportasi, tetapi jika pernah dikompromikan, OAuth di lapisan aplikasi masih mencegah invokasi alat yang tidak sah. Konfigurasi setiap server MCP untuk memerlukan autentikasi OAuth seperti yang dijelaskan dalam spesifikasi MCP.
Aktifkan SSO untuk organisasi claude.ai Anda. Token terowongan dihasilkan dari Konsol claude.ai. Dengan SSO diterapkan, kontrol sesi penyedia identitas Anda mengatur sesi admin.
Batasi allowed_ips. Gunakan rentang CIDR terkecil yang mencakup server MCP Anda.
Pantau log. Atur peringatan pada peringatan, kesalahan, dan pola yang tidak biasa.
Rotasi kredensial. Rotasi sertifikat sesuai jadwal reguler, atau segera jika kompromi dicurigai.
Jaga gambar tetap diperbarui. Terapkan pembaruan gateway dengan cepat. Sematkan gambar berdasarkan digest SHA256.
Batasi akses jaringan. Gateway dan cloudflared hanya harus memiliki akses jaringan yang diperlukan.
Batasi cakupan server MCP. Server MCP hanya harus mengekspos fungsionalitas yang diperlukan.
Lindungi kredensial saat istirahat. Terapkan izin file yang sesuai, enkripsi saat istirahat, dan manajemen rahasia ke direktori tunnel-data/ (Compose) atau Rahasia kredensial (Helm).

Merespons pelanggaran yang dicurigai

Jika Anda mencurigai kredensial terowongan, kunci TLS, atau beberapa aspek lain dari sistem telah dikompromikan:

Hentikan penyebaran segera (helm uninstall atau docker compose down --timeout 0)
Hapus server MCP dari Claude (Organization Settings → Connectors)
Arsipkan terowongan melalui API (lihat Teardown, langkah 3)
Hubungi Anthropic agar mereka dapat menyelidiki
Rotasi kredensial — sediakan terowongan baru, rotasi token OAuth di server MCP Anda
Tinjau log sebelum memulihkan layanan

Pemecahan masalah

Kegagalan validasi IP

"IP validation failed" dalam log gateway berarti upstream terselesaikan ke IP di luar allowed_ips. Periksa IP yang terselesaikan:

Shell

dig +short docs-mcp.internal

Jika IP tersebut sah, perbarui allowed_ips dalam konfigurasi gateway Anda untuk menyertakan rentang CIDR yang benar.

Tunnel tidak terhubung

Periksa log cloudflared untuk kesalahan. Penyebab umum:

Token tunnel tidak valid
Firewall memblokir port keluar 7844 TCP/UDP ke edge Cloudflare

Verifikasi konektivitas keluar ke rentang IP Cloudflare: 198.41.192.0/19 dan 2606:4700:a0::/44.

Peringatan ukuran buffer UDP

cloudflared mungkin mencatat failed to sufficiently increase receive buffer size. Ini adalah masalah penyetelan transport QUIC — lihat dokumentasi buffer UDP quic-go untuk menyesuaikan.

Kesalahan sertifikat

Jika jabat tangan TLS gagal, periksa bahwa:

Sertifikat server belum kedaluwarsa (validitas 90 hari)
SAN sertifikat cocok dengan *.<tunnel-domain>
Sertifikat CA terdaftar dengan Anthropic melalui API
Untuk Compose, file sertifikat dapat dibaca oleh UID 65532

Merutekan OAuth melalui tunnel (server auth di belakang daftar izin IP)

Masalah: Server auth Anda berada di belakang daftar izin IP sumber. Backend Claude perlu menjangkaunya untuk penemuan OAuth, pendaftaran klien, dan pertukaran token, tetapi Anda lebih suka tidak memasukkan rentang IP keluar Anthropic ke daftar putih.

Solusi: konfigurasi split-endpoint. Rutekan panggilan OAuth backend-ke-backend melalui tunnel. Pertahankan endpoint /authorize yang menghadap browser pada nama host yang sudah ada di daftar putih. Ini berfungsi karena Claude membaca authorization_endpoint dari metadata penemuan Anda dan mengarahkan ulang browser pengguna ke sana. Itu tidak perlu menjangkau URL itu sendiri.

Langkah 1: Tambahkan rute gateway untuk server auth Anda

YAML — mcp-gateway.yaml

routes:
  mcp: http://your-mcp-server:8080
  auth: http://your-auth-server:8080

Langkah 2: Sajikan metadata penemuan split-endpoint

Endpoint /.well-known/oauth-authorization-server server auth Anda harus mengembalikan:

JSON

{
  "issuer": "https://auth.<tunnel-id>.tunnel.anthropic.com",
  "authorization_endpoint": "https://<your-allowlisted-host>/authorize",
  "token_endpoint": "https://auth.<tunnel-id>.tunnel.anthropic.com/token",
  "registration_endpoint": "https://auth.<tunnel-id>.tunnel.anthropic.com/register",
  "code_challenge_methods_supported": ["S256"]
}

Hanya authorization_endpoint yang menunjuk ke nama host yang sudah ada. Semuanya yang lain menggunakan URL tunnel.

Langkah 3: Arahkan server MCP Anda ke penerbit tunnel

Endpoint /.well-known/oauth-protected-resource server MCP Anda:

JSON

{
  "resource": "https://mcp.<tunnel-id>.tunnel.anthropic.com",
  "authorization_servers": [
    "https://auth.<tunnel-id>.tunnel.anthropic.com"
  ]
}

Pembongkaran

Cara membongkar tunnel ketika tidak lagi diperlukan.

1. Dapatkan ID Tunnel

Helm

TUNNEL_ID=$(kubectl get secret mcp-tunnel -n mcp-tunnel \
  -o jsonpath='{.data.tunnel-id}' | base64 -d)

Compose

TUNNEL_ID=$(sudo cat tunnel-data/tunnel-id)

2. Hentikan deployment

Helm: helm uninstall mcp-tunnel -n mcp-tunnel (catatan: Secret kredensial dibuat oleh Job setup, bukan Helm, jadi bertahan setelah uninstall)
Compose: docker compose down

3. Arsipkan tunnel

Buat token API baru terlebih dahulu dan cabut saat selesai.

Shell

read -rs API_TOKEN && export API_TOKEN

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/archive" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

4. Hapus kredensial yang disimpan

Helm: kubectl delete secret mcp-tunnel -n mcp-tunnel
Compose: sudo rm -rf tunnel-data

Mendapatkan bantuan

Hubungi tim akun Anthropic Anda untuk bantuan.

Lampiran: Konfigurasi gateway

Gateway membaca konfigurasinya dari file YAML. Di Docker Compose, Anda menulis file ini langsung sebagai config/mcp-gateway.yaml. Di Helm, atur bidang ini di bawah gateway.config.* dalam file nilai Anda—chart mengelola listen_addr, tls, dan tunnel_domain untuk Anda.

Bidang	Deskripsi	Default
`listen_addr`	Alamat dan port untuk didengarkan	Diperlukan
`log_level`	Tingkat verbositas logging: `debug`, `info`, `warn`, `error`	`info`
`shutdown_timeout`	Waktu tunggu untuk permintaan yang sedang berlangsung selama shutdown yang elegan	`30s`
`tunnel_domain`	Domain dasar untuk resolusi rute awalan	Tidak ada
`tls.cert_file`	Jalur ke sertifikat TLS	Diperlukan
`tls.key_file`	Jalur ke kunci privat TLS	Diperlukan
`routes`	Pemetaan nama host (atau awalan) ke URL upstream	Diperlukan
`upstream.allowed_ips`	Rentang CIDR yang dapat dihubungi gateway	Rentang privat RFC 1918
`upstream.disable_ip_validation`	Nonaktifkan validasi IP sepenuhnya	`false`
`upstream.tls.ca_file`	Bundel CA untuk memvalidasi TLS upstream	Tidak ada
`upstream.tls.include_system_cas`	Percayai bundel CA sistem untuk TLS upstream	`false`

Untuk rute https://, atur setidaknya salah satu dari upstream.tls.ca_file atau upstream.tls.include_system_cas.

Lampiran: API Tunnel

Untuk alur kerja penyediaan khusus, Anda dapat memanggil API Tunnel secara langsung. Semua permintaan memerlukan header ini:

Shell

-H "Authorization: Bearer $API_TOKEN"
-H "anthropic-version: 2023-06-01"
-H "anthropic-beta: mcp-tunnels-2026-02-24"

Buat tunnel:

curl -X POST https://api.anthropic.com/v1/tunnels \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24" \
  -H "Content-Type: application/json" \
  -d '{}'

Daftar tunnel:

curl https://api.anthropic.com/v1/tunnels \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

Daftarkan sertifikat CA:

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/certificates" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24" \
  -H "Content-Type: application/json" \
  -d "{\"ca_certificate_pem\": $(jq -Rs . < ca.crt)}"

Lihat Lampiran: Persyaratan sertifikat untuk mengetahui apa yang harus dimuat oleh sertifikat CA dan server.

Daftar sertifikat CA:

curl "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/certificates" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

Cabut sertifikat CA:

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/certificates/${CERT_ID}/revoke" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

Ungkapkan token tunnel:

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/reveal_token" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

Putar token tunnel:

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/rotate_token" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

Arsipkan tunnel:

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/archive" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

Lampiran: Persyaratan sertifikat

Jika Anda menggunakan biner setup (setup init / setup renew-cert), biner tersebut menghasilkan sertifikat yang sesuai secara otomatis dan Anda dapat melewati bagian ini. Persyaratan ini berlaku jika Anda mengeluarkan sertifikat melalui PKI Anda sendiri.

Sertifikat CA — unggah melalui POST /v1/tunnels/{id}/certificates. Tunnel menyimpan paling banyak dua sertifikat CA aktif sekaligus, memungkinkan rotasi tanpa downtime.

Dikodekan PEM, sertifikat tunggal, paling banyak 8 KB
Ekstensi BasicConstraints dengan CA:TRUE, ditandai sebagai kritis
Ekstensi SubjectKeyIdentifier ada
KeyUsage mencakup keyCertSign
Dalam periode validitas
RSA 2048-bit atau lebih besar, atau ECDSA P-256 atau lebih besar; tanda tangan SHA-256 atau lebih kuat

Sertifikat server — disajikan oleh gateway selama jabat tangan TLS internal. Tidak diunggah ke Anthropic.

Ditandatangani langsung oleh CA yang terdaftar di terowongan
Ekstensi AuthorityKeyIdentifier ada, cocok dengan SubjectKeyIdentifier CA
SAN mencakup nama DNS yang cocok dengan <route>.<tunnel-domain> (wildcard *.<tunnel-domain> mencakup semua rute)
Jika ekstensi ExtendedKeyUsage ada, mencakup serverAuth
Dalam periode validitas
RSA 2048-bit atau lebih besar, atau ECDSA P-256 atau lebih besar; tanda tangan SHA-256 atau lebih kuat

Referensi: biner setup menghasilkan CA ECDSA P-256 (validitas 5 tahun) dan sertifikat server RSA 4096-bit dengan SAN wildcard (validitas 90 hari).

Lampiran: Referensi CLI Setup

Biner setup berjalan di dalam kontainer gateway melalui docker compose run --rm setup <subcommand> (Compose) atau sebagai hook Helm dan CronJob (Kubernetes).

setup init — membuat terowongan melalui API Tunnels, menghasilkan CA dan sertifikat server, mendaftarkan CA, dan menulis semua output.

Bendera	Deskripsi	Default
`--api-url`	URL dasar API Anthropic. Juga dibaca dari `API_URL`.	diperlukan
`--api-token`	Token API dengan cakupan terowongan. Juga dibaca dari `API_TOKEN`.	diperlukan
`--output`	Tujuan output: `dir:/path` atau `k8s-secret:NAME`	`k8s-secret:mcp-gateway`
`--cert-duration`	Periode validitas sertifikat server	`2160h` (90 hari)
`--token-version`	String deteksi perubahan; nilai baru memicu rotasi token terowongan	tidak ada

setup renew-cert — mengeluarkan sertifikat server baru yang ditandatangani oleh CA yang disimpan. Tidak ada panggilan API yang diperlukan.

Bendera	Deskripsi	Default
`--output`	Tujuan output: `dir:/path` atau `k8s-secret:NAME`	`k8s-secret:mcp-gateway`
`--cert-duration`	Periode validitas sertifikat baru	`2160h` (90 hari)
`--renew-before`	Lewati jika sertifikat yang ada memiliki lebih dari waktu ini hingga kedaluwarsa	`0` (selalu perbarui)

Pengaturan --renew-before=720h membuat perintah menjadi no-op ketika lebih dari 30 hari tersisa, cocok untuk dijalankan sesuai jadwal.