Tunnel MCP sedang dalam pratinjau riset. Minta akses untuk mencobanya.
Panduan ini men-deploy tunnel stack sebagai container yang diperkuat (hardened) pada satu host. Konfigurasi yang sama dapat direplikasi di beberapa host untuk ketersediaan.
Anda memerlukan:
tnl_...). Provisioning manual selalu dimulai dari tunnel yang dibuat di Console.fdrl_...) dan ID organisasi Anda.openssl (1.1.1 atau lebih baru).api.anthropic.com (443 TCP) dan tunnel edge (7844 TCP dan UDP). Lihat persyaratan jaringan lengkapnya.routes. Jika Anda belum memilikinya, gunakan server contoh.Jika Anda tidak memiliki server MCP yang tersedia untuk pengujian, gunakan yang minimal ini:
mkdir -p mcp-tunnel
cat > mcp-tunnel/hello_server.py <<'EOF'
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")
EOFLangkah-langkah Instal berikut melakukan cd ke dalam mcp-tunnel/ dan mencatat di mana harus menambahkan service dan route yang sesuai.
Panduan ini menyediakan satu pendekatan referensi menggunakan Docker Compose. Anda bertanggung jawab untuk mengadaptasinya agar memenuhi persyaratan keamanan organisasi Anda.
Jalur ini mengharuskan host memiliki penyedia identitas OIDC (seperti server metadata VM cloud atau SPIFFE). Jika tidak, gunakan tab Tanpa akses programatik sebagai gantinya.
Komponen setup menggunakan Workload Identity Federation untuk mengambil token tunnel, membuat CA dan sertifikat server, dan mendaftarkan CA ke Anthropic.
Siapkan direktori deployment
mkdir -p mcp-tunnel/{config,data}
cd mcp-tunnel
sudo chown 65532:65532 dataContainer berjalan sebagai UID non-root 65532 dan memerlukan akses tulis ke data/.
Tulis docker-compose.yaml
File compose menyematkan (pin) image berdasarkan digest SHA-256, menjalankan setiap container sebagai non-root dengan filesystem hanya-baca, menghapus semua kapabilitas Linux, dan menonaktifkan eskalasi hak istimewa.
cat > docker-compose.yaml <<'EOF'
services:
setup:
image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:9d4c80593b559fc3ca3814866418744fa94858b02a4d4a4cc52d423e732ccc81
entrypoint: ["/setup"]
command:
- init
- --api-url=https://api.anthropic.com
- --output=dir:/data
- --token-version=1
environment:
- TUNNEL_ID
- ANTHROPIC_FEDERATION_RULE_ID
- ANTHROPIC_ORGANIZATION_ID
- ANTHROPIC_WORKSPACE_ID
- ANTHROPIC_IDENTITY_TOKEN
volumes:
- ./data:/data
user: "65532:65532"
read_only: true
security_opt:
- no-new-privileges:true
cap_drop:
- ALL
profiles: ["setup"]
cloudflared:
image: cloudflare/cloudflared@sha256:6b599ca3e974349ead3286d178da61d291961182ec3fe9c505e1dd02c8ac31b0
command: tunnel --no-autoupdate run --url http://localhost:8080
environment:
- TUNNEL_TOKEN
# Bagikan netns proxy agar localhost:8080 dapat menjangkaunya.
network_mode: "service:mcp-proxy"
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-proxy:
image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:9d4c80593b559fc3ca3814866418744fa94858b02a4d4a4cc52d423e732ccc81
volumes:
- ./config/mcp-proxy.yaml:/etc/mcp-gateway/config.yaml:ro
- ./data:/data: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"
EOFJika Anda menggunakan server MCP contoh, tambahkan sebagai service:
cat >> docker-compose.yaml <<'EOF'
hello-mcp:
image: python:3.13-slim
working_dir: /app
volumes:
- ./hello_server.py:/app/hello_server.py:ro
command: sh -c "pip install --quiet mcp && python hello_server.py"
restart: unless-stopped
EOFProvisikan tunnel
Atur pengidentifikasinya. Biarkan TUNNEL_ID tidak diatur agar komponen setup membuat tunnel; atur untuk melampirkan ke tunnel yang sudah ada dari Console:
# export TUNNEL_ID=tnl_... # atur untuk menyambung ke tunnel yang sudah ada
export ANTHROPIC_FEDERATION_RULE_ID=fdrl_...
export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000Jika aturan federasi Anda dicakup ke workspace selain default organisasi Anda, atur juga ANTHROPIC_WORKSPACE_ID=wrkspc_...; jika tidak, komponen setup menggunakan workspace default. Tunnel yang dibuat otomatis akan dibuat di workspace tersebut.
Atur ANTHROPIC_IDENTITY_TOKEN ke JWT OIDC dari penyedia identitas host ini. Ikuti panduan WIF untuk penyedia Anda untuk mendaftarkan issuer, mengatur subject aturan, dan menerbitkan token; audience aturan harus cocok dengan audience yang Anda minta saat menerbitkan token.
Jalankan komponen setup:
docker compose run --rm setupsetup init bersifat idempoten terhadap data/: menjalankannya kembali akan menggunakan kembali ID tunnel dan CA yang sudah tersimpan di sana dan tidak pernah membuat tunnel kedua. CA baru dibuat dan didaftarkan hanya ketika data/ kosong atau TUNNEL_ID telah berubah; dalam kasus itu batas dua sertifikat aktif berlaku, jadi cabut salah satunya di Console terlebih dahulu jika kedua slot terisi.
Lihat Kegagalan autentikasi komponen setup jika terjadi error.
Ambil domain tunnel Anda dan ekspor untuk langkah-langkah selanjutnya:
export TUNNEL_DOMAIN=$(sudo cat data/tunnel-domain)
echo "$TUNNEL_DOMAIN"Token Workload Identity Federation berumur pendek (1 jam secara default) dan kedaluwarsa secara otomatis; tidak ada yang perlu dicabut setelah setup selesai.
Tulis konfigurasi proxy
tunnel_domain wajib: proxy menggunakannya untuk menghapus sufiks domain dari hostname yang masuk sebelum mencari subdomain di routes. routes adalah map datar dari subdomain ke URL upstream, bukan list.
cat > config/mcp-proxy.yaml <<EOF
listen_addr: ":8080"
log_level: info
shutdown_timeout: 30s
tunnel_domain: ${TUNNEL_DOMAIN}
tls:
cert_file: /data/tls.crt
key_file: /data/tls.key
routes:
echo: http://hello-mcp:9000
EOFRoute echo: menargetkan server MCP contoh; ganti dengan (atau tambahkan) route Anda sendiri. Lihat referensi konfigurasi proxy untuk semua field yang tersedia.
Mulai deployment
export TUNNEL_TOKEN=$(sudo cat data/tunnel-token)
docker compose up -dFile compose membaca TUNNEL_TOKEN dari environment host tanpa nilai default, sehingga export harus diulang di setiap shell baru dan setelah reboot.
Untuk deployment multi-VM, salin direktori mcp-tunnel/ ke setiap host, atur TUNNEL_TOKEN, dan jalankan docker compose up -d. Dalam alur programatik TUNNEL_TOKEN adalah $(sudo cat data/tunnel-token); dalam alur manual nilainya adalah yang Anda salin dari Console. Token tunnel dan sertifikat yang sama berfungsi di semua replika.
Verifikasi secara end-to-end dengan memanggil server MCP upstream dari sisi Anthropic: lihat Gunakan server MCP yang di-tunnel. Dengan server MCP contoh, URL yang dirutekan adalah https://echo.<your-tunnel-domain>/mcp. Jika verifikasi gagal, lihat Pemecahan Masalah.
Jalankan perintah di bagian ini dari dalam direktori deployment mcp-tunnel/.
Dengan akses programatik, naikkan --token-version pada command service setup, atur pengidentifikasi Workload Identity Federation, terbitkan JWT OIDC baru, dan jalankan kembali komponen setup:
# Edit docker-compose.yaml: naikkan bilangan bulat pada argumen
# --token-version di layanan setup (misalnya, --token-version=1 menjadi
# --token-version=2). Binary setup menolak melakukan rotasi jika nilainya
# tidak berubah.
# export TUNNEL_ID=tnl_... # atur hanya jika Anda mengaturnya saat instalasi
export ANTHROPIC_FEDERATION_RULE_ID=fdrl_...
export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
# export ANTHROPIC_WORKSPACE_ID=wrkspc_... # jika aturan Anda dibatasi pada workspace
# Terbitkan ulang ANTHROPIC_IDENTITY_TOKEN sesuai panduan penyedia WIF untuk
# lingkungan Anda (token tersebut sudah kedaluwarsa sejak instalasi).
export ANTHROPIC_IDENTITY_TOKEN=...
docker compose run --rm setup
export TUNNEL_TOKEN=$(sudo cat data/tunnel-token)
docker compose up -d cloudflaredArgumen --token-version diedit di docker-compose.yaml alih-alih diteruskan pada baris perintah sehingga nilai baru tetap tersimpan untuk eksekusi komponen setup di masa mendatang. Komponen setup mengautentikasi dengan Workload Identity Federation; tidak ada token API yang perlu dicabut.
Tanpa akses programatik, klik Rotate token pada halaman detail tunnel di Console, lalu perbarui variabel environment TUNNEL_TOKEN di setiap host dan mulai ulang cloudflared (docker compose up -d cloudflared).
Mengklik Rotate token langsung membatalkan token saat ini. Antara momen tersebut dan pembaruan TUNNEL_TOKEN di setiap host serta memulai ulang cloudflared, host mana pun yang cloudflared-nya dimulai ulang (crash, reboot host) tidak dapat terhubung kembali. Perbarui setiap host segera setelah rotasi.
Anda bertanggung jawab untuk memantau masa berlaku dan memperbarui sertifikat server sebelum kedaluwarsa.
Dengan akses programatik:
docker compose run --rm setup renew-cert --output=dir:/dataArgumen CLI menggantikan command service setup (argumen init) tetapi mempertahankan entrypoint-nya, sehingga ini menjalankan /setup renew-cert --output=dir:/data.
Teruskan --renew-before=720h untuk membuat perintah tidak melakukan apa-apa (no-op) ketika masa berlaku yang tersisa lebih dari 30 hari. Ini membuatnya aman untuk dijalankan pada jadwal tetap.
Tanpa akses programatik, tanda tangani sertifikat server baru dengan CA yang sudah ada (CA yang terdaftar di Console tidak berubah) dan ganti data/tls.crt. Atur TUNNEL_DOMAIN terlebih dahulu jika Anda menjalankan ini dari shell baru.
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.extDalam kedua alur tersebut, proxy melakukan polling tls.cert_file dan memuat ulangnya secara otomatis, sehingga tidak diperlukan restart.
Lampirkan server MCP upstream ke Managed Agent atau Messages API.
Panduan hardening, rotasi kredensial, dan respons pelanggaran.
Diagnosis masalah konektivitas, TLS, dan routing.
Was this page helpful?