dev.io rehberi uzak MCP sunucuları için OAuth 2.1 el sıkışmasını adım adım anlatıyor

Uzak MCP sunucularının yarattığı sorun

dev.io üzerinde yayımlanan bir anlatıma göre, çoğu ekip MCP kimlik doğrulamasıyla olması gerekenden daha geç tanışıyor. stdio üzerinden başlatılan yerel bir sunucu, makinede zaten mevcut olan her şeyi yeniden kullanır: bir AWS_PROFILE ayarı, bir DOCKER_HOST değişkeni veya bir config dizininde duran token'lar gibi. Sunucunun bir şirket genelinde paylaşılması gerektiği anda bu kalıtım ortadan kalkar: gerçek bir hostname arkasında Streamable HTTP konuşan uzak bir sunucu, her çağırıcının kimliğini kanıtlamak zorundadır. Protokolün yanıtı, PKCE, metadata discovery ve bearer token'larla OAuth 2.1'dir; makale, Claude Desktop, Cursor ve VS Code'un manuel geçici çözümler olmadan bağlanabilmesi için bir client'ın yaptığı istekleri adım adım anlatır.

URL'ye token gömme kısayolu neden başarısız olur

Baştan çıkarıcı yaklaşım, MCP endpoint URL'sine bir token eklemektir. dev.io yazısının açıkladığı gibi, bu beş dakika ayakta kalır ve sonra her güvenlik incelemesinden kalır. URL'ler proxy log'larına, tarayıcı geçmişlerine ve Referer header'larına kaydedilir. Token'ı döndürmek, herkese yeni bir URL dağıtmak demektir. Audience kısıtlaması yoktur, bu yüzden bir sunucu için yakalanan bir token diğer iç host'lara karşı yeniden oynatılabilir. Ve herhangi bir özel header şeması, sizi sonsuza dek client başına dokümantasyon yazmaya mahkûm eder. Her MCP client'ı aynı standart akışı uyguladığı için, bunu bir kez uygulamak tüm uyumlu client'ların çalışması anlamına gelir.

Bir client yolu nasıl bulur

Makaleye göre el sıkışması, korumalı bir kaynağın kimliği doğrulanmamış bir isteğe 401 ve bir well-known protected-resource dokümanına işaret eden bir WWW-Authenticate header'ıyla yanıt vermesiyle başlar. Bu doküman kaynağın adını, authorization server'larını, desteklenen bearer yöntemlerini ve kullanılabilir scope'ları belirtir. Client daha sonra authorization server'ın kendi metadata dokümanını fetch eder ve authorize, token ve registration endpoint'lerini öğrenir. Auth0, Okta, Keycloak ve AWS Cognito bu dokümanları zaten sunar; yani iş, sıfırdan bir auth server yazmak değil, route'ları yapılandırmaktır.

Registration ve PKCE

MCP client'ları önceden kayıtlı uygulamalar değildir. İlk bağlantıda registration endpoint'ini çağırır ve bir client ID alırlar. Public client'lara bilinçli olarak secret verilmez, çünkü bir masaüstü uygulaması bunu saklayamaz; OAuth 2.1 bunun yerine PKCE'ye yaslanır. Client bir code verifier ve onun SHA-256 challenge'ını üretir, kullanıcıyı authorization endpoint'ine gönderir ve onay sonrası dönen kodu, verifier'ı elinde tuttuğunu kanıtlayarak değiştirir. Yazarın belirttiği gibi, bir sağlayıcı dinamik registration'ı kapatırsa, bir client ID'yi bant dışında (out of band) verebilir ve kullanıcıya MCP URL yapılandırmasında iletebilirsiniz; akışın geri kalanı değişmez.

Ortaya çıkan access token, her JSON-RPC isteğinde Authorization header'ıyla taşınır. Makaledeki örnek token yanıtı 900 saniyelik bir geçerlilik süresi gösterir ve yazar, access token'ların haftalarca değil dakikalarca yaşaması gerektiğini savunur; uzun ömürlü kimlik bilgisi ise refresh token'dır ve client'a dokunmadan sunucu tarafında iptal edilebilir.

Scope'lar ve hata modları

Makale uyarıyor: düz read/write scope'ları, bir sunucu birkaç servis boyunca yirmi araç sunduğunda kötü yaşlanır. Bunun yerine capability bazlı scope tanımlayın; araç listeleme, salt okunur çağrılar, durum değiştiren çağrılar ve sunucu yönetimini ayırın ve denetimi her çağrıda zorunlu kılın. Yetkisiz bir çağrıyı, bir agent'ın sınırı bir şeyi kırarak keşfetmesine izin vermek yerine, eksik scope'u adıyla belirten yapılandırılmış bir JSON-RPC hatasıyla reddedin.

Yazara göre destek taleplerinin çoğundan dört hata sorumludur: metadata'nın HTTP üzerinden sunulması veya sondaki eğik çizgi uyuşmazlığı — issuer birebir eşleşmek zorundadır; izin listesinde eksik loopback redirect URI'ları, bu masaüstü girişini imkânsız kılar; çok kiracılı kurulumlarda audience claim'i eksik token'lar; ve ölümcül addedilen clock skew — geçerlilik doğrulamasında en az 60 saniyelik pay önerilir. Önerilen test yolu, önce bir AI client olmadan döngüyü doğrulamaktır: metadata için curl, authorization akışı için bir tarayıcı ve token'la doğrudan initialize ve tools/list çağrıları; ardından OAuth dansını MCP Inspector ile etkileşimli olarak sürmek.

Neden önemli

Ekipler OpenAPI dokümanlarını host edilmiş MCP sunucuları olarak yayımladıkça, kimlik doğrulaması bir demoyu gerçek altyapıdan ayıran şeydir: dokümantasyon herkese açık kalabilirken, canlı sistemlere dokunan araçlar OAuth, kullanıcı bazlı scope'lar ve audit log'larının arkasında durabilir. Standart akışı bir kez doğru kurmak, mevcut ve gelecekteki uyumlu client'ların özel entegrasyon çalışması olmadan bağlanması demektir; MCP endpoint'ini bir kurumun gerçekten işletebileceği bir şeye dönüştüren de budur.