MCP sunucusu eklemek, mevcut REST API’lerinizi değiştirmenizi gerektirmez. Bir ajan tools/call ile bir araç çağırdığında, sunucu bu işlemi arka planda mevcut API’nizle gerçekleştirebilir. Ancak MCP yalnızca REST için bir sarmalayıcı da değildir; yerel dosyalara, veritabanına veya başka servis arayüzlerine erişen araçlar sunabilir.
Bu ayrım entegrasyon tasarımını doğrudan etkiliyor. API’nizdeki her endpoint’i aynen araca çevirmek yerine, ajanın hangi işlemleri hangi sınırlarla yapacağını belirlemeniz gerekiyor. Araç sözleşmesi, token’ın hedefi ve backend’in kullanıcı yetkisi aynı isteğin farklı kontrol noktalarıdır.
İstek gerçekte hangi katmanlardan geçiyor?
API, bir yazılımın sunduğu işlevlere erişim sözleşmesidir. REST, GraphQL veya gRPC bunun farklı uygulama biçimleri olabilir. MCP ise bir host uygulamasının, istemcileri aracılığıyla sunucuların sunduğu araçlara ve bağlama standart bir yöntemle erişmesini sağlar. Model tek başına ağ bağlantısı kurmaz; bağlantıyı ve çağrı yürütmesini host uygulama yönetir.
Örneğin bir destek ajanından belirli müşterinin açık taleplerini bulmasını istediğinizi düşünün. MCP istemcisi sunucunun sunduğu araçları keşfeder, model uygun aracı ve argümanlarını önerir, host uygulama gerekli kontrollerden sonra çağrıyı gönderir. Sunucu da destek sisteminin API’sinden yetkili kayıtları alır.
Buradaki örnek araç adı search_tickets olabilir. Sunucunun GET /tickets endpoint’ini mi, dahili bir arama servisini mi kullandığı istemciden gizlenebilir. Araç sözleşmesi kullanıcı görevini tarif eder; backend uygulama ayrıntıları ayrıca yönetilir.
Bu yaklaşımın temel parçaları MCP mimari dokümanında açıklanıyor. Araçların yanında resources ve prompts gibi başka protokol yetenekleri de var. MCP’yi yalnızca araç çağrısına indirgemek, entegrasyonun sağlayabileceği bağlam katmanını gözden kaçırır.
Yetkilendirme tek bir kontrol noktasına bırakılamaz
Paylaşılan, ağ üzerinden erişilen MCP sunucusu gelen isteğin kimliğini ve erişim kapsamını doğrulamalı. Backend API de kendi yetkilendirmesini uygulamalı. Kontrolün yalnızca bir tarafta bulunması, diğer taraftaki eksikliği telafi etmez. Özellikle çok kullanıcılı sistemlerde hangi kaydın kime gösterilebileceği backend tarafında açık olmalı.
Yerel stdio bağlantısında ise istemci ile sunucu süreçler arası iletişim kurar; HTTP yetkilendirme akışını buna aynen uygulamayın. Sunucunun backend’e hangi kimlikle bağlandığını ve yerel sürecin hangi dosyalara erişebildiğini ayrıca inceleyin. Taşıma yöntemi değişse de işlem yetkisini sınırlama ihtiyacı devam eder.
Önemli bir ayrıntı da token’ın hedefi, yani audience bilgisidir. MCP sunucusu, gelen token’ın kendisi için düzenlendiğini doğrulamalı; başka bir API için alınmış token’ı kabul edip o API’ye aktarmamalıdır. MCP güvenlik rehberi, bu token passthrough davranışını açıkça yasaklıyor. Sunucunun kendisi için üretilmiş token’ı farklı bir API’ye aynen geçirmesi de hedef ayrımını ihlal eder.
Bu kural, bütün backend çağrılarının ortak ve yüksek yetkili bir servis hesabıyla yapılması gerektiği anlamına gelmez. Tasarıma göre uygulama kimliği veya kullanıcı adına yetkilendirilmiş bir akış kullanılabilir. İkinci durumda downstream API için geçerli, doğru audience ve izinleri taşıyan ayrı token alınır.
Benim burada öncelik verdiğim kontrol, modelin araç argümanına yazdığı kullanıcı kimliğinin güvenilir kabul edilmemesi. Yetkili kullanıcı bilgisi doğrulanmış oturumdan gelmeli. Kullanıcı yalnızca kendi taleplerini görebiliyorsa, model farklı bir müşteri numarası gönderdiğinde API bunu reddetmelidir.
Endpoint sayısı kadar araç açmak gerekmiyor
İyi bir araç adı, modelin yapabileceği işi anlatır. Aynı talep aramasını e-posta, müşteri numarası ve durum filtresiyle yapan birkaç endpoint, tek bir arama aracı altında sunulabilir. Buna karşılık arama ve talep silme işlemlerini tek araçta birleştirmek yetki ve onay akışını belirsizleştirir.
Anthropic’in araç tasarımı rehberi, araçları mevcut API’lerin birebir kopyası olarak düşünmek yerine anlamlı görevler etrafında tasarlamayı öneriyor. Bu, her sistemde aynı birleşimin kullanılacağı anlamına gelmez; karar gerçek kullanım senaryosuna bağlıdır.
search_tickets için durum filtresinin kabul ettiği değerleri, sayfa boyutu sınırını ve boş sonuç davranışını şemada tanımlayın. Sonuçta yalnızca gereken alanları döndürün. Yüzlerce kaydın bütün açıklamalarını göndermek yerine sınırlı bir özet ve gerektiğinde ayrıntı çağrısı daha denetlenebilir olabilir.
Hata sözleşmesi de önemli. Yetki eksikliği, bulunamayan kayıt ve geçici servis kesintisi aynı boş listeyle dönmemeli. Aksi halde ajan hatalı şekilde hiç kayıt olmadığı sonucuna varabilir. Hatanın yeniden denenebilir olup olmadığını anlaşılır biçimde belirtin.
Araç keşfi context maliyetini nasıl etkiler?
Araç adları, açıklamalar, giriş şemaları ve sonuçlar modelin işlediği bağlamın parçası olabilir. Maliyet yalnızca sunucu sayısına bağlı değildir. Şemaların uzunluğu, sonuç hacmi ve istemcinin araçları ne zaman yüklediği de belirleyicidir. Context ve kalıcı hafıza yazısında bu bağlamın nasıl taşındığını açıklamıştım.
Bazı istemciler tanımları ihtiyaç anında getirir; bazıları daha geniş bir listeyi başlangıçta sunar. Bu yüzden belirli bir testte ölçülmüş araç sayısı ve token tüketimini bütün MCP kurulumları için sabit oran gibi kullanmamak gerekir. Tool Search yaklaşımı, bu farkın neden önemli olduğunu gösteriyor.
Önerim önce gerçek görevlerle ölçüm yapmak. Ajan hangi araçları çağırıyor, kaç başarısız deneme yapıyor, ne kadar sonuç geri dönüyor? Kullanılmayan araçları kapatın; ancak yalnızca isim sayısını azaltmak için birbirinden farklı işlemleri aşırı genel bir araca sıkıştırmayın.
Okuma ve değiştirme işlemlerinin sınırı
MCP araçlarında readOnlyHint ve destructiveHint gibi annotations bulunur. Bunlar istemciye davranış hakkında bilgi verir; erişim kontrolü veya güvenlik garantisi değildir. İstemci, tanımını aldığı sunucunun güvenilirliğini ayrıca değerlendirmelidir.
destructiveHint, her yazma işleminin eş anlamlısı da değildir. Örneğin yalnızca yeni kayıt ekleyen bir işlemle mevcut veriyi silen işlem aynı etkiye sahip olmayabilir. Varsayılanları ve diğer ipuçlarıyla ilişkisini araç sözleşmesinden okuyun.
Veri silme, ödeme veya dışarıya mesaj gönderme gibi işlemler için host tarafında açık onay ve sunucuda uygun yetki gerekir. Backend’in işlem kaydı, deneme kimliği ve tekrar çağrı davranışı da tasarlanmalı. Aynı isteğin iki kez gelmesi çift işlem yaratıyorsa yalnızca modelden dikkatli olmasını istemek yeterli olmaz.
Entegrasyonu bu sınırlarla tasarlayın
- MCP aracını gerçek kullanıcı görevi etrafında tanımlayın.
- MCP sunucusunda ve backend’de yetkilendirme uygulayın.
- Token audience sınırlarını koruyun, passthrough yapmayın.
- Araç ipuçlarını gerçek izin ve onay kontrolleriyle destekleyin.
Mevcut API’yi koruyarak ajan entegrasyonu kurabilirsiniz; belirleyici olan hangi işlemi, kimin adına ve hangi sözleşmeyle sunduğunuzdur. Sorularınız olursa yorumlarda buluşalım.
