Referensi MCP tunnels



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 map string datar (map[string]string), bukan list. Proxy mencari hostname yang masuk dengan pencocokan persis terlebih dahulu, kemudian 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 berupa scheme://host:port. Port bersifat wajib. Menyertakan path akan ditolak saat pemuatan konfigurasi dengan pesan invalid upstream (must be scheme://host:port).



Tunnels API

REST API Tunnels berada di /v1/tunnels dan mendukung pembuatan, pencantuman, dan pengarsipan tunnel, pendaftaran sertifikat CA, serta menampilkan atau merotasi 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 menyimpan hingga dua sertifikat CA aktif sekaligus, yang memungkinkan rotasi tanpa downtime.

• Dikodekan PEM, sertifikat tunggal, hingga 8 kB.
• Ekstensi BasicConstraints ada dengan CA:TRUE, ditandai critical.
• Ekstensi SubjectKeyIdentifier ada.
• KeyUsage mencakup keyCertSign.
• Berada dalam periode validitasnya.
• 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 periode validitasnya.
• 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 validitas lima tahun dan sertifikat server RSA 4096-bit dengan SAN wildcard dan validitas 90 hari.



Komponen setup

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



setup init

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

Perintah ini mengautentikasi 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 aturan federasi, 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 masih tersisa lebih dari 30 hari validitas, sehingga aman untuk dijalankan pada jadwal tetap.