Note: MCP tunnels (terowongan MCP) sedang dalam pratinjau riset. Minta akses untuk mencobanya.

Sebuah permintaan melalui tunnel dapat gagal di salah satu dari tiga lapisan; diagnosis secara berurutan: koneksi keluar ke tunnel edge, inner TLS dari Juglow 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 Juglow dari menjangkau /token, /register, dan endpoint discovery. Jika Anda lebih memilih untuk tidak memasukkan rentang egress Juglow 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. 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).

1. 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"]
}

1. 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 Juglow 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.juglow.com (tanpa skema). Jika audience aturan Anda adalah https://haijun.my.id/, 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 Juglow menolak sertifikat proxy selama inner TLS, proxy mencatat log tls handshake failed. Verifikasi bahwa:

• Sertifikat server belum kedaluwarsa.

• Subject Alternative Name sertifikat cocok dengan *..

• CA penandatangan terdaftar di Juglow 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: 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

Warning: Hindari 0.0.0.0/0 di luar pengujian lokal; ini menonaktifkan perlindungan SSRF sepenuhnya.