Memecahkan masalah tunnel MCP

Sebuah permintaan melalui tunnel dapat gagal di salah satu dari tiga lapisan; diagnosis secara berurutan: koneksi keluar ke tunnel edge, inner TLS dari Anthropic ke proxy Anda, lalu perutean dan validasi IP menuju server MCP upstream.

Referensi cepat

Bagian-bagian berikut membahas kegagalan yang memerlukan lebih dari perbaikan satu baris.

OAuth gagal di balik allowlist IP sumber

Alur OAuth gagal ketika allowlist IP sumber pada server otorisasi Anda memblokir backend Anthropic dari menjangkau /token, /register, dan endpoint discovery. Jika Anda lebih memilih untuk tidak memasukkan rentang egress Anthropic ke allowlist, Anda dapat merutekan panggilan OAuth backend-ke-backend melalui tunnel sambil tetap mempertahankan endpoint /authorize yang menghadap browser pada hostname publik Anda yang sudah ada.

1. 1

   Tambahkan rute proxy untuk server otorisasi

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

   

   Mulai ulang proxy setelah mengedit routes (docker compose restart mcp-proxy, atau helm upgrade).

2. 2

   Sajikan metadata discovery dengan endpoint terpisah

   Respons /.well-known/oauth-authorization-server dari server otorisasi Anda harus mengarahkan authorization_endpoint ke hostname Anda yang sudah ada di allowlist dan semua yang lainnya ke tunnel:

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

   
3. 3

   Arahkan server MCP ke issuer tunnel

   Respons /.well-known/oauth-protected-resource dari server MCP Anda harus mereferensikan hostname tunnel sebagai server otorisasinya:

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

   

Dengan konfigurasi ini, browser pengguna mengakses /authorize pada hostname Anda yang sudah ada (yang sudah diizinkan oleh allowlist Anda), sementara backend Anthropic menjangkau /token, /register, dan dokumen discovery melalui tunnel.

Kegagalan autentikasi komponen setup

Komponen setup (Helm Job atau layanan setup Compose) melakukan autentikasi ke Tunnels API dengan menukarkan JWT OIDC melalui aturan federasi Anda. Ketika penukaran gagal, lihat Memecahkan masalah penukaran yang gagal dalam referensi Workload Identity Federation; mode kegagalannya (subject, audience, issuer, JWKS, lifetime) sama.

Penyebab khusus Tunnels:

• Audience default chart adalah api.anthropic.com (tanpa skema). Jika audience aturan Anda adalah https://api.anthropic.com, atur api.wif.audience agar cocok.
• Respons 403 dari Tunnels API setelah penukaran berhasil berarti scope aturan tidak mencakup workspace:manage_tunnels, atau service account aturan tersebut bukan anggota workspace tunnel. Atur scope dan tambahkan service account ke workspace.

Pada Helm, komponen setup berjalan sebagai Job hook pre-install. Saat gagal, Job dibiarkan untuk diperiksa (kubectl logs job/mcp-tunnel-setup -n mcp-tunnel). Helm tidak mengelola resource hook, jadi hapus Job tersebut sebelum mencoba lagi:

helm uninstall mcp-tunnel -n mcp-tunnel
kubectl -n mcp-tunnel delete job mcp-tunnel-setup

Tunnel tidak mau terhubung

Periksa log cloudflared terlebih dahulu. Penyebab umum:

• TUNNEL_TOKEN tidak ada, kedaluwarsa, atau disalin dengan tidak benar.
• Firewall memblokir TCP/UDP keluar pada port 7844 ke tunnel edge.

cloudflared juga mungkin mencatat peringatan tentang ukuran buffer penerimaan UDP; ini adalah petunjuk penyetelan QUIC, bukan error.

Error sertifikat

Ketika Anthropic menolak sertifikat proxy selama inner TLS, proxy mencatat log tls handshake failed. Verifikasi bahwa:

• Sertifikat server belum kedaluwarsa.
• Subject Alternative Name sertifikat cocok dengan *.<tunnel-domain>.
• CA penandatangan terdaftar di Anthropic untuk tunnel ini.

Lihat persyaratan sertifikat untuk aturan validasi lengkap.

Validasi IP upstream

Untuk perlindungan SSRF, proxy secara default hanya menghubungi alamat dalam rentang privat RFC1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16). Hanya IPv4 yang didukung untuk koneksi proxy-ke-upstream. (Rentang egress cloudflared-ke-edge di Persyaratan jaringan adalah hop yang berbeda.)

Jika proxy mencatat log IP validation failed: <ip> is not a private address, hostname upstream ter-resolve di luar rentang tersebut. Pada Kubernetes, beberapa distribusi terkelola mengalokasikan Service CIDR di luar RFC1918; jika kubectl get svc kubernetes -n default -o jsonpath='{.spec.clusterIP}' mengembalikan alamat di luar rentang privat, cari Service CIDR cluster Anda dan tambahkan.

Jika alamat tersebut sah, tambahkan CIDR pencakup yang paling sempit ke upstream.allowed_ips. Mengatur allowed_ips menggantikan default RFC1918 alih-alih memperluasnya, jadi sertakan rentang privat yang digunakan oleh server MCP upstream Anda yang lain:

upstream:
  allowed_ips:
    - 10.0.0.0/8
    - 172.16.0.0/12
    - 192.168.0.0/16
    - 127.0.0.0/8       # loopback, for local testing only