MCP OAuth 2.1 dengan PKCE: amankan server agen Anda dalam 7 langkah

Spesifikasi MCP 2026-03-15 mengunci OAuth 2.1 dengan PKCE sebagai standar otorisasi untuk server MCP jarak jauh. Kunci API dalam variabel lingkungan masih berfungsi pada hari pertama, namun registri, Claude Desktop, Cursor, VS Code Copilot, dan Windsurf semuanya lebih memilih server yang didukung OAuth saat digunakan telusuri integrasi. Jika server Anda masih meminta pembawa berumur panjang di file konfigurasi, Anda meninggalkan sebagian distribusi di atas meja.

Bagian tersulitnya bukanlah OAuth itu sendiri; ini adalah lima spesifikasi kecil yang dibuat oleh aliran autentikasi MCP bersama-sama: OAuth 2.1 (RFC 9700), PKCE (RFC 7636), Pendaftaran Klien Dinamis (RFC 7591), Indikator Sumber Daya (RFC 8707), dan Metadata Sumber Daya yang Dilindungi. Masing-masing berukuran kecil; kabel di situlah tim terjebak. Inilah jalannya, secara berurutan.

Langkah 1: Sajikan dokumen Metadata Sumber Daya yang Dilindungi

File PRM memberi tahu klien di mana server otorisasi Anda berada, cakupan apa yang Anda terima, dan apa saja pengidentifikasi sumber daya untuk dimasukkan ke dalam aud mengeklaim. Selenggarakan di /.well-known/oauth-protected-resource pada asal yang sama dengan titik akhir MCP Anda:

Itu authorization_servers list adalah lompatan penemuan. Klien mengambil PRM Anda, ikuti entri pertama ke dokumen metadata AS, dan buat URL otorisasi dari sana. Pertahankan daftarnya pada satu entri kecuali Anda menjalankan federasi; banyak penerbit membingungkan klien dan tidak ada dalam spesifikasi yang memerlukannya.

Langkah 2: Publikasikan metadata server otorisasi

Penyedia identitas Anda (Auth0, Okta, Clerk, Cloudflare Access, atau Hydra yang dihosting sendiri) melayani metadata AS di /.well-known/oauth-authorization-server. Klien MCP mengkonsumsinya untuk mempelajari titik akhir otorisasi dan token, jenis hibah yang didukung, dan lokasi JWKS untuk verifikasi token:

Tiga bidang yang diminta spesifikasi: code_challenge_methods_supported harus menyertakan S256; grant_types_supported harus menyertakan authorization_code Dan refresh_token; registration_endpoint harus ada jika Anda mendukung klien dinamis. Merindukan siapa pun dan Claude Desktop akan menandai server sebagai tidak patuh selama pengaturan.

Langkah 3: Hasilkan pasangan PKCE pada klien

PKCE terdiri dari 20 baris kode klien dan mematikan kelas intersepsi kode otorisasi menyerang. Hasilkan 32 byte acak, enkode base64url menjadi verifikator, SHA-256 verifikator menjadi tantangan, dan mengirimkan tantangan dengan permintaan otorisasi:

Itu resource parameter (RFC 8707) adalah salah satu implementasi yang paling banyak dilewatkan. Tanpa itu, token yang dibuat untuk server MCP Anda dapat diputar ulang terhadap API lain yang mempercayainya penerbit yang sama; dengan itu, itu aud klaim menyematkan token ke pengidentifikasi sumber daya Anda dan tidak ada orang lain yang menerimanya.

Langkah 4: Tukarkan kode dengan token

Setelah pengalihan kembali, klien POST kode ditambah pemverifikasi asli ke token titik akhir. Server otorisasi menghitung ulang SHA-256 dari pemverifikasi dan membandingkannya dengan tantangan yang tersimpan; jika cocok, Anda mendapatkan token akses:

Simpan token penyegaran di penyimpanan aman (Keychain, Windows Credential Manager, Linux libsecret) dan hapus pemverifikasi dari penyimpanan sesi saat pertukaran berhasil. Akses token hidup 5 hingga 60 menit; token penyegaran hidup lebih lama tetapi tetap harus diputar saat digunakan.

Langkah 5: Verifikasi token pembawa pada setiap permintaan MCP

HTTP yang dapat dialirkan membuat verifikasi token menjadi sederhana: setiap permintaan HTTP membawa Authorization header, sehingga server MCP Anda memverifikasinya di middleware sebelumnya mengirimkan panggilan alat. Ambil JWKS satu kali, simpan dalam cache, dan validasi penerbit, audiens, dan kedaluwarsa pada setiap panggilan:

Tiga klaim yang menangkap bug nyata: iss menyematkan penerbit; aud menyematkan sumber daya (mencegah pemutaran ulang lintas sumber daya); exp menangkap token basi. Jangan menerima token tanpa ini; “Saya sudah memvalidasinya tanda tangan" tidak sama dengan "Saya memvalidasi klaim tersebut."

Langkah 6: Gerbang setiap alat pada cakupan yang dinyatakan oleh anotasinya

Desain cakupan minus OAuth 2.1 memberi Anda akses biner: klien dapat memanggil setiap alat atau tidak ada. Sistem anotasi MCP menutup kesenjangan tersebut dengan membiarkan setiap alat mendeklarasikan cakupannya kebutuhan. Penangan membaca anotasi dan cakupan token pada waktu pemanggilan:

Pisahkan cakupan destruktif dan baca-saja. Pengguna yang mengabulkan tools:read untuk menjalankan laporan mingguan seharusnya tidak dapat dijalankan send_email dari token yang sama. Claude Desktop dan Cursor meminta cakupan di layar persetujuan, sehingga pemisahan terjadi UX jujur tentang apa yang dapat dilakukan klien.

Langkah 7: Dukung pendaftaran klien dinamis

Registrasi klien dinamis memungkinkan klien MCP mendaftar sendiri di server otorisasi Anda tanpa manusia mengisi formulir. Kursor atau Claude Desktop POST permintaan pendaftaran, menerima a client_id, dan segera menjalankan aliran OAuth:

Ini adalah bagian yang memindahkan server MCP Anda dari "tempelkan kunci API di file konfigurasi" ke "klik Hubungkan di Kursor dan berikan akses." Layak untuk dilakukan jika server Anda bersifat publik; dapat dilewati jika Anda hanya mengirim ke sekelompok kecil klien yang dikenal.

Verifikasi aliran penuh dari ujung ke ujung

Setelah bagian-bagiannya berada di tempatnya, panggilan alat MCP lengkap tampak seperti yang diautentikasi oleh pembawa lainnya Permintaan HTTP:

Jika Anda melihat 401 dengan WWW-Authenticate: Bearer resource_metadata="...", klien mengetahui di mana menemukan pengaturan autentikasi Anda dan menjalankan kembali alurnya. Header itu adalah jabat tangan yang memungkinkan penyegaran token senyap dan penyambungan kembali setelah pencabutan.

Lembar contekan desain ruang lingkup

Poin-poin penting

• OAuth 2.1 memerlukan PKCE. Bukan barang yang bagus untuk dimiliki; setiap aliran kode autentikasi membawa a pemverifikasi dan tantangan atau gagal memenuhi spesifikasi.
• PRM di /.well-known/oauth-protected-resource adalah titik masuknya. Klien menemukan pengaturan autentikasi Anda dari satu URL itu; lewati saja dan klien tidak dapat melakukan konfigurasi otomatis.
• Gunakan resource parameter (RFC 8707). Sematkan audiens token ke server MCP Anda sehingga token yang bocor tidak dapat diputar ulang terhadap API lain.
• Validasi penerbit, audiens, kedaluwarsa, cakupan. Cek tanda tangan saja biar pemutaran ulang lintas sumber daya.
• Pisahkan cakupan destruktif. tools:read, tools:invoke:safe, Dan tools:invoke:destructive berikan kepada pengguna menyetujui UX yang mereka harapkan dari izin OS.
• Registrasi klien dinamis membuka instalasi tanpa konfigurasi. Bayar biaya pelaksanaan satu kali; setiap klien MCP baru mendapatkan keuntungan selamanya.

Server MCP yang dihosting Botoi di api.botoi.com/mcp menjalankan pola yang sama. Telusuri dokumen pengaturan MCP untuk konfigurasi Claude Desktop, Claude Code, Cursor, VS Code, dan Windsurf. Untuk penandatanganan JWT dan verifikasi primitif yang digunakan middleware di atas, lihat Titik akhir JWT API di dokumen interaktif.