MCP sunucu kimlik doğrulama uygulama rehberi: en yeni spesifikasyon kullanımı

Birkaç gün önce (18 Haziran 2025), MCP (Model Context Protocol) ekibi, MCP Spesifikasyonu (2025-06-18) dosyasının en yeni sürümünü yayımladı. Bu güncelleme, kimlik doğrulama spesifikasyonunda önemli bir değişiklik içeriyor. MCP Sunucuları artık bir Authorization Server gibi erişim belirteçleri vermeyecek. Bunun yerine, erişim belirteçlerini kullanacaklar ve kaynakları bir Resource Server olarak sağlayacaklar.

MCP Auth (tak-çalıştır tarzı bir MCP Sunucu kimlik doğrulama kütüphanesi) geliştiricilerinden biri olarak, bu projede en yeni MCP kimlik doğrulama spesifikasyonunu destekleyecek şekilde geliştirmeler yaptım. Kendi uygulama deneyimlerime dayanarak, MCP Sunucun için en yeni spesifikasyonla uyumlu kimlik doğrulama özelliklerini nasıl uygulayacağını göstereceğim.

Bu yazıda şunları öğreneceksin:

• Yeni MCP kimlik doğrulama spesifikasyonunda MCP kimlik doğrulama işleyişini anlama
• MCP kimlik doğrulama spesifikasyonu gereksinimlerine göre Resource Server olarak MCP Sunucusunun ne uygulaması gerektiğini netleştirme
• Kendi MCP Sunucun için en yeni MCP kimlik doğrulama spesifikasyonuna uygun kimlik doğrulama desteği uygulama rehberliği
• Uygulama sırasında gözden kaçabilecek noktalar ve güvenlik sorunlarını belirleme

Lütfen unutma, bu makale:

• Okuyucunun JWT (JSON Web Token) hakkında temel bilgiye sahip olduğunu varsayar. JWT'nin yapısı, imza doğrulaması ve diğer temel konseptler ayrıntılı olarak anlatılmayacak. Detaylar için Auth Wiki - JWT sayfasına bakabilirsin
• MCP kimlik doğrulama spesifikasyonunun dayandığı çeşitli RFC'leri kapsamlı şekilde anlatmaz, yalnızca bu RFC gerekliliklerine uygun uygulama örnekleri sunar
• MCP Client ve Authorization uygulama ile etkileşim detaylarını kapsamıyor. Bunlar genellikle, MCP spesifikasyonuna dayalı olarak MCP'yi destekleyen LLM istemcileri ve yetkilendirme sunucu sağlayıcıları tarafından uygulanır. MCP Sunucu geliştiricilerinin müdahale etmesine gerek yoktur ve buna izin de verilmez. Detaylar için OAuth Client ve Authorization Server 'a bakabilirsin
• Makalede bahsedilen tüm erişim belirteçlerinin JWT olduğunu varsayar, çünkü piyasadaki en yaygın formattır. Diğer belirteç türleri, ilgili yetkilendirme sunucusu sağlayıcısının dökümantasyonuna göre kullanılmalıdır.

MCP kimlik doğrulama nasıl çalışır?#

En yeni MCP kimlik doğrulama spesifikasyonu gereği, MCP kimlik doğrulama akışı aşağıdaki diyagramda gösterilmiştir:

1. MCP Client, https://github-tools.com adresindeki MCP Sunucudan kaynak ister. Kullanıcı henüz giriş yapmadığı için, bu isteğin HTTP yetkilendirme başlığı, kullanıcıyı temsil eden bir erişim belirteci içermez.

2. MCP Sunucu, istemcinin isteğinin yetkilendirme başlığından bir erişim belirteci alamadığı için, MCP Client'a bir HTTP 401 hatası döndürür. Bu hata yanıtında, MCP Sunucusunun kaynak metadatasının URL'sini içeren bir WWW-Authenticate başlığı bulunur (resource_metadata alanının değeri).

3. MCP Client, dönen WWW-Authenticate başlığından resource_metadata değerini çıkarır (örneğin: https://github-tools.com/.well-known/oauth-protected-resource). Ardından, MCP Client bu adresten, Resource Server olarak MCP Sunucusu tarafından sunulan kaynak metadatasını ister. Bu metadata, authorization_servers ve scopes_supported gibi içerikler barındırır ve MCP Client'ın, erişmek istediği kaynaklar için gerekli erişim belirtecini hangi yetkilendirme sunucusundan, hangi izinlerle alması gerektiğini anlamasına yardımcı olur.

4-8. MCP Client, kaynak metadatasından elde ettiği yetkilendirme sunucusu metadata URL'ine göre, yetkilendirme sunucusu metadata bilgisini ister. Sonrasında, OAuth 2.1 akışını bu yetkilendirme sunucusu ile başlatır ve yetkilendirme bittikten sonra bir erişim belirteci elde eder.

9. MCP Client, yetkilendirme sunucusundan aldığı erişim belirtecini taşır ve MCP Sunucudan tekrar kaynak ister.

10. MCP Sunucu, belirtecin geçerli olduğunu doğruladıktan sonra istenen kaynağı döndürür. Bundan sonra, MCP Client ve MCP Sunucu arasındaki iletişim geçerli belirteç ile devam edecektir.

Şimdi, MCP kimlik doğrulama akışına göre MCP sunucusunun kimlik doğrulama mekanizmasını adım adım nasıl uygulayacağını açıklayacağız.

Yetkisiz istekleri yönet: 401 hatası ve WWW-Authenticate Başlığı döndürme#

Yukarıdaki akışta gösterildiği gibi, MCP Client, MCP Sunucuya erişim belirteci olmadan bir istek gönderdiğinde, MCP Sunucu, WWW-Authenticate başlığında kaynak metadata URL'sini içeren bir HTTP 401 Unauthorized hatası döndürmelidir.

MCP kimlik doğrulama spesifikasyonu hata yönetimi gereği, MCP Client istekleri erişim belirteci taşımadığında olduğu kadar, MCP Sunucu geçersiz bir erişim belirteci aldığında da 401 hatası ve WWW-Authenticate başlığı döndürmelidir.

401 hatası ne zaman döndürülmeli öğrendik, peki WWW-Authenticate başlığı nasıl oluşturulmalı?

RFC9728 Bölüm 5.1 gereği, WWW-Authenticate başlığı, korunan kaynak metadata URL'ini gösteren bir resource_metadata parametresi içermelidir.

Temel formatı şöyledir:

Burada, Bearer yetkilendirme şemasıdır ve OAuth 2.0 ile korunan kaynaklara erişmek için bearer belirteci gerektiğini belirtir (bakınız: MDN dökümantasyonu). Takip eden resource_metadata parametresinin değeri, MCP Sunucunun sunduğu kaynak metadata endpoint'inin tam URL'sidir.

Gerçek kod örneği:

MCP Client bu şekilde bir 401 hatası aldığında, WWW-Authenticate başlığındaki resource_metadata değerine erişerek MCP Sunucunun kaynak metadatasını alır. Sonrasında, metadata'nın sağladığı bilgilerle belirlenen yetkilendirme sunucusundan, MCP Sunucuya erişimde kullanılabilecek bir erişim belirteci almak için yetkilendirme akışını başlatır.

Artık 401 hatasının ne zaman döneceğini ve resource_metadata URL'si gerekeceğini biliyoruz. Ancak bu kaynak metadata URL'si nasıl oluşturulur ve metadata içinde neler olmalıdır, henüz öğrenmedik. Şimdi bunları inceleyeceğiz.

Kaynak metadata keşif mekanizması uygula#

MCP kimlik doğrulama akışına göre, MCP Client 401 hatası aldıktan hemen sonra MCP Sunucudan kaynak metadata talep eder. Dolayısıyla, Resource Server rolünde olan MCP Sunucu, bir kaynak metadata keşif mekanizması sunmalıdır.

Metadata endpoint URL yolunu belirle#

OAuth sisteminde, kaynak adreslerini tanımlamak için URL kullanırız. Bu adrese "resource indicator" denir. RFC9728'e göre kaynak metadata, belirli bir /.well-known yolunda barındırılmalıdır.

Eğer MCP Sunucun (örneğin https://github-tools.com) sadece tek bir hizmet veriyorsa, metadata endpoint şu olmalıdır:

Aynı ana makinede birden fazla farklı MCP servisi sunuyorsan, her servis için bağımsız bir metadata endpoint olmalı. Örneğin, https://api.acme-corp.com kurumsal platformunda şu servisler var:

• https://api.acme-corp.com/github - GitHub entegrasyonu
• https://api.acme-corp.com/slack - Slack entegrasyonu
• https://api.acme-corp.com/database - Veri tabanı sorgu servisi

Karşılık gelen metadata endpointleri:

• https://api.acme-corp.com/.well-known/oauth-protected-resource/github
• https://api.acme-corp.com/.well-known/oauth-protected-resource/slack
• https://api.acme-corp.com/.well-known/oauth-protected-resource/database

Bu tasarımın avantajı, her hizmetin farklı yetki alanlarına ve yetkilendirme sunucusu yapılandırmalarına sahip olabilmesidir. Örneğin:

• GitHub hizmeti, GitHub OAuth sunucusunu kullanır ve github:read, github:write izinlerine ihtiyaç duyar
• Slack hizmeti, Slack OAuth sunucusunu kullanır ve slack:channels:read, slack:messages:write izinleri ister
• Veritabanı hizmeti, kurumsal iç yetkilendirme sunucusunu kullanır ve db:query yetkisi ister

Yukarıdaki durumlardan şu patterni özetleyebiliriz:

Kaynağın tanımlayıcısından metadata endpoint URL'sini şöyle elde edebiliriz:

Kaynak metadata yanıtı oluştur#

Endpoint URL yolu belirlendikten sonra, bu endpoint'in RFC9728 gereği, JSON formatında metadata döndürmesini sağlamamız gerekir.

Uygulamada odaklanılması gereken dört temel alan vardır.

İlki resource alanı, yani kaynak tanımlayıcısı. MCP Client'ın erişmek istediği adres ile aynı olmalıdır.

İkincisi, authorization_servers alanı. MCP Client'ın hangi yetkilendirme sunucusundan erişim belirteci talep edeceğini belirten bir dizi. OAuth 2.0 Protected Resource Metadata (RFC 9728) spesifikasyonunda bu alan opsiyoneldir ancak MCP kimlik doğrulama spesifikasyonunda zorunludur; çünkü MCP Client, yetkilendirme isteklerini hangi sunucuya göndereceğini kesin şekilde bilmelidir. Bu bilgi olmadan istemci OAuth akışını tamamlayamaz.

Sonra, bu Resource Server tarafından desteklenen tüm izinlerin listelendiği scopes_supported alanı gelir.

Son olarak, MCP Client'ın, erişim belirtecini sunucuya hangi yöntem ile gönderebileceğini bildiren bearer_methods_supported alanı vardır. Genellikle ["header"] olarak ayarlanır, yani yetki alınan belirteç HTTP Authorization başlığında gönderilmelidir.

Örnek olarak, https://github-tools.com MCP Sunucusu için kaynak metadata yapılandıralım:

Bu yapılandırma MCP Client'a şunları bildirir: https://github-tools.com kaynağına erişmek istiyor, https://auth.github-tools.com yetkilendirme sunucusundan erişim belirteci almalısın, github:read, github:write, repo:admin gibi izinler talep edebilirsin ve elde edilen erişim belirtecini Authorization başlığı ile göndermelisin.

Çoğu uygulamada bu dört alanı yapılandırmak yeterlidir. Daha karmaşık konfigürasyonlar için RFC9728'in tüm alan listesine bakabilirsin.

Erişim belirteçlerini doğrula#

MCP Client, yetkilendirme sunucusundan erişim belirteci aldıktan sonra, bu belirteç ile MCP Sunucudan kaynak talep eder.

Pratikte MCP sunucuları erişim belirteci doğrularken şunlara dikkat etmeli:

1. Temel belirteç doğrulamasında, yetkilendirme sunucusu bilgisini doğrudan belirteçten almak yerine, MCP Sunucu yapılandırmasına göre doğrulayın.
2. Belirtecin hedef kitlesinin (audience), MCP Sunucusu olup olmadığını doğrula. Böylece belirtecin gerçekten bu sunucunun kaynaklarına erişmek üzere alınıp alınmadığına emin olunur.
3. Scope doğrulamasını düzgün uygula

Erişim belirteçlerini doğrularken MCP Sunucusu yapılandırmasını kullan#

MCP Sunucusu bir erişim belirteci aldığında, bu belirteç kendi içinde yetkilendirme sunucusu bilgisi (issuer) barındırır. Bazen geliştiriciler, doğrulamada yalnızca belirtecin taşıdığı issuer değerini baz alır. Bu özellikle aşağıdaki durumda karışıklığa yol açabilir — MCP Sunucu kaynak metadatasında birden çok yetkilendirme sunucusu yapılandırması varsa, örneğin:

Bu durumda, geliştiriciler genellikle, doğrulama için kullanılacak yetkilendirme sunucusu bilgisini, doğrulanmamış belirteçten alınan issuer değerine göre belirler. Saldırganlar, MCP Sunucusu için sahte bir yetkilendirme sunucusu oluşturup, sahte erişim belirteci üretebilir. Eğer sadece belirteçteki issuer değerine bakılıp, bu değerin gösterdiği sunucuya güvenilirse, bu sahte belirteç doğrulamayı geçer.

Bu yüzden doğru doğrulama yöntemi şudur:

• Yalnızca bir yetkilendirme sunucusu varsa: belirteci arka uçta yapılandırılmış olan sunucuya göre doğrula
• Birden çok yetkilendirme sunucusu varsa: belirteçten doğrulanmamış şekilde issuer değerini çek, MCP Sunucu yapılandırmasında bu sunucunun olup olmadığını kontrol et. Yoksa belirteci reddet

Elbette, belirteç doğrularken issuer değeri sıkı şekilde doğrulanmalı.

jose JWT doğrulama kütüphanesiyle örnek:

Belirteç hedef kitlesini (audience) doğrula#

MCP kimlik doğrulama spesifikasyonunun Token Audience Binding and Validation kısmında, bir istemci yetkilendirme sunucusundan erişim belirteci talep ederken bu belirtecin hangi kaynak için kullanılacağını da belirtmesi gerektiği yazar. MCP Sunucu da, belirteci doğrularken belirteçteki hedef kitlenin (audience), kendisi olup olmadığını kontrol emelidir.

Bu sistemin altında yatan standart, OAuth 2.0 Resource Indicators (RFC 8707)'dir. Akışı şöyle özetleyebiliriz:

1. İstemci isteği aşaması: MCP Client erişim belirteci için yetkilendirme sunucusuna talepte bulunurken, isteğe resource parametresini ekler ve bu belirtecin hangi kaynak sunucusunda kullanılacağını iletir (örneğin https://github-tools.com)

2. Belirteç dağıtım aşaması: Yetkilendirme sunucusu, erişim belirteci oluşturken bu kaynak adresini belirtece bağlar. JWT biçimli belirteçlerde, bu kaynak adresi, JWT içindeki audience (aud) alanına yazılır

3. Belirteç doğrulama aşaması: MCP Sunucu belirteci aldığında, JWT içindeki audience alanının, kendi kaynak tanımlayıcısıyla tam olarak eşleşip eşleşmediğini kontrol eder

Örneğin, https://github-tools.com MCP Sunucusu için:

Bu audience doğrulaması, belirteç kötüye kullanımını engelleyen temel bir güvenlik mekanizmasıdır. Audience doğrulaması yoksa saldırganlar, başka bir servis için üretilmiş belirteçlerle senin MCP Sunucuna erişmeyi deneyebilir ve sunucu bunları yanlışlıkla kabul edebilir.

Scope doğrulaması#

Bazı MCP Sunucular, dahili kaynaklara erişimi yönetir, çünkü farklı kullanıcıların erişim yetkileri farklı olabilir.

Bu nedenle erişim belirteci doğrulandıktan sonra, belirtecin ilgili işleme izin verip vermediğine bakmak gerekir. Bunu, belirtecin scope iddiasında (claim) mevcut kaynağa erişim için gerekli izinlerin olup olmadığına bakarak yapabiliriz:

MCP kimlik doğrulama spesifikasyonu gereği, eğer belirteç, mevcut kaynak için gerekli izni taşımıyorsa, 403 Forbidden hatası dönülmelidir.

Sonuç#

Bu makale sayesinde, MCP Sunucun için en yeni spesifikasyonla uyumlu kimlik doğrulama özelliklerini uygulayabilmelisin. Unutma: belirteçleri güvenli şekilde doğrula, metadataları düzgün yapılandır ve audience'ı sıkı şekilde doğrula.

Bir MCP Sunucusu geliştiriyorsan MCP Auth kütüphanesini dene. Bu makalede anlatılan tüm işlevleri zaten içerir ve hızlıca kimlik doğrulama desteği entegre etmene yardımcı olur.

Sorularını GitHub'da tartışmaktan çekinme. Hadi MCP ekosistemini hep birlikte ileriye taşıyalım.