Men-deploy MCP tunnel dengan Docker Compose

Panduan ini men-deploy tunnel stack sebagai container yang diperkuat (hardened) pada satu host. Konfigurasi yang sama dapat direplikasi di beberapa host untuk ketersediaan (availability).

Sebelum Anda mulai

Anda memerlukan:

• Tunnel yang dibuat di Console. Ikuti Membuat tunnel dan catat ID tunnel (tnl_...).
• Cara bagi host untuk mengautentikasi ke Tunnels API.
  • Akses terprogram (direkomendasikan). Aktifkan Set up programmatic access saat membuat tunnel agar komponen setup dapat mengautentikasi melalui Workload Identity Federation. Catat ID aturan federasi (fdrl_...) dan ID organisasi Anda.
  • Manual. Lewati akses terprogram. Anda akan mendapatkan token tunnel dari Console, membuat CA dan sertifikat server sendiri, dan mendaftarkan CA di Console.
• Host dengan Docker dan Docker Compose terinstal. Alur manual juga memerlukan openssl (1.1.1 atau lebih baru).
• Konektivitas jaringan keluar dari host 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 host pada alamat yang akan Anda konfigurasikan di bawah 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:

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")
EOF

Langkah-langkah Instal berikut melakukan cd ke mcp-tunnel/ dan mencatat di mana harus menambahkan service dan route yang sesuai.

Instal

Panduan ini menyediakan satu pendekatan referensi menggunakan Docker Compose. Anda bertanggung jawab untuk menyesuaikannya agar memenuhi persyaratan keamanan organisasi Anda.

File compose membaca TUNNEL_TOKEN dari environment host tanpa nilai default, sehingga ekspor 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 terprogram, 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 deployment

Verifikasi secara end-to-end dengan memanggil server MCP upstream dari sisi Anthropic: lihat Menggunakan server MCP yang di-tunnel. Dengan server MCP contoh, URL yang di-route adalah https://echo.<your-tunnel-domain>/mcp. Jika verifikasi gagal, lihat Pemecahan Masalah.

Upgrade

Jalankan perintah di bagian ini dari dalam direktori deployment mcp-tunnel/.

Merotasi token tunnel

Dengan akses terprogram, naikkan --token-version di command service setup, atur pengidentifikasi Workload Identity Federation, buat JWT OIDC baru, dan jalankan kembali komponen setup:

# Edit docker-compose.yaml: naikkan nilai integer pada argumen --token-version
# di layanan setup (misalnya, --token-version=1 menjadi
# --token-version=2). Biner setup menolak melakukan rotasi jika nilainya
# tidak berubah.

export TUNNEL_ID=tnl_...
export ANTHROPIC_FEDERATION_RULE_ID=fdrl_...
export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
# export ANTHROPIC_WORKSPACE_ID=wrkspc_...   # jika aturan Anda bercakupan workspace
# Buat 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 cloudflared

Argumen --token-version diedit di docker-compose.yaml alih-alih diteruskan pada command line agar nilai baru tetap bertahan untuk eksekusi komponen setup di masa mendatang. 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 variabel environment TUNNEL_TOKEN pada setiap host dan restart cloudflared (docker compose up -d cloudflared).

Pembaruan sertifikat

Anda bertanggung jawab untuk memantau masa berlaku dan memperbarui sertifikat server sebelum kedaluwarsa.

Dengan akses terprogram:

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

Argumen CLI menggantikan command service setup (argumen init) tetapi mempertahankan entrypoint-nya, sehingga ini menjalankan /setup renew-cert --output=dir:/data.

Tanpa akses terprogram, tanda tangani sertifikat server baru dengan CA Anda 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.ext

Dalam kedua alur, proxy melakukan polling terhadap tls.cert_file dan memuat ulang secara otomatis, sehingga tidak diperlukan restart.

Langkah selanjutnya