MessagesTunnel MCP

Referensi MCP tunnels

Copy page



Field konfigurasi proxy, Tunnels REST API, persyaratan sertifikat, dan komponen setup.

Konfigurasi proxy

Proxy membaca konfigurasinya dari /etc/mcp-gateway/config.yaml (Compose) atau ConfigMap yang telah di-render (Helm, diisi dari gateway.config.*).

Untuk rute upstream https://, atur setidaknya salah satu dari upstream.tls.ca_file atau upstream.tls.include_system_cas; jika tidak, proxy tidak memiliki trust anchor untuk sertifikat upstream.

Pencocokan rute

routes adalah peta string datar (map[string]string), bukan daftar. Proxy mencari hostname yang masuk dengan pencocokan persis terlebih dahulu, lalu dengan menghapus sufiks tunnel_domain dan mencocokkan subdomain yang tersisa. Pencocokan hanya mempertimbangkan hostname; path permintaan dan query string diteruskan ke server MCP upstream tanpa perubahan.

Setiap nilai upstream harus persis berbentuk scheme://host:port. Port bersifat wajib. Menyertakan path akan ditolak saat pemuatan konfigurasi dengan invalid upstream (must be scheme://host:port).

Tunnels API

Tunnels REST API berada di /v1/tunnels dan mendukung pembuatan, pencantuman, dan pengarsipan tunnel, pendaftaran sertifikat CA, serta pengungkapan atau rotasi token tunnel. Lihat referensi Tunnels API untuk semua endpoint, skema permintaan dan respons, serta contoh.

Header yang wajib pada setiap permintaan:

Persyaratan sertifikat

Komponen setup menghasilkan sertifikat yang sesuai secara otomatis. Persyaratan ini hanya berlaku jika Anda menerbitkan sertifikat melalui PKI Anda sendiri.

Sertifikat CA

Unggah dengan POST /v1/tunnels/{tunnel_id}/certificates. Sebuah tunnel dapat menampung hingga dua sertifikat CA aktif sekaligus, yang memungkinkan rotasi tanpa downtime.

• Berenkode PEM, sertifikat tunggal, hingga 8 kB.
• Ekstensi BasicConstraints ada dengan CA:TRUE, ditandai critical.
• Ekstensi SubjectKeyIdentifier ada.
• KeyUsage mencakup keyCertSign.
• Berada dalam masa berlakunya.
• RSA 2048-bit atau lebih besar, atau ECDSA P-256 atau lebih besar, dengan tanda tangan SHA-256 atau lebih kuat.

Sertifikat server

Disajikan oleh proxy selama inner TLS.

• Ditandatangani langsung oleh CA yang terdaftar (tanpa intermediate).
• Ekstensi AuthorityKeyIdentifier ada dan cocok dengan SubjectKeyIdentifier milik CA.
• Subject Alternative Name mencakup nama DNS yang cocok dengan <route>.<tunnel-domain>. Wildcard *.<tunnel-domain> mencakup semua rute.
• Jika ekstensi ExtendedKeyUsage ada, ekstensi tersebut mencakup serverAuth.
• Berada dalam masa berlakunya.
• RSA 2048-bit atau lebih besar, atau ECDSA P-256 atau lebih besar, dengan tanda tangan SHA-256 atau lebih kuat.

Komponen setup menghasilkan CA ECDSA P-256 dengan masa berlaku lima tahun dan sertifikat server RSA 4096-bit dengan SAN wildcard dan masa berlaku 90 hari.

Komponen setup

Komponen setup dikirimkan di dalam image mcp-proxy sebagai binary setup. Jalankan dengan docker compose run --rm setup <subcommand> (Compose) atau andalkan hook dan CronJob milik chart (Helm).

setup init

Menghubungkan ke tunnel yang sudah ada (atau membuat tunnel baru jika tidak ada ID tunnel yang diberikan), lalu menghasilkan CA dan sertifikat server, mendaftarkan CA, mengambil token tunnel, dan menulis semua output ke tujuan.

Perintah ini melakukan autentikasi melalui Workload Identity Federation. Perintah ini membaca ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_WORKSPACE_ID (opsional), dan tepat salah satu dari ANTHROPIC_IDENTITY_TOKEN_FILE atau ANTHROPIC_IDENTITY_TOKEN. Lihat referensi WIF untuk semantik terkini dari variabel-variabel ini; komponen setup menurunkan service account dari federation rule, sehingga tidak memerlukan ANTHROPIC_SERVICE_ACCOUNT_ID secara terpisah.

setup renew-cert

Menerbitkan sertifikat server baru yang ditandatangani oleh CA yang tersimpan. Tidak melakukan panggilan API.

Mengatur --renew-before=720h membuat perintah ini menjadi no-op ketika sisa masa berlaku lebih dari 30 hari, sehingga aman untuk dijalankan pada jadwal tetap.