MCP Sunucusu Nasıl Kurulur: Adım Adım Genel Bakış

MCP sunucusu kurmak için odaklı bir yetenek kümesini tipli tool, resource ve prompt olarak sunun, bunları scoped kimlik doğrulamanın ardında mevcut API'nize bağlayın, sonra resmi bir SDK ile stdio ya da HTTP/SSE üzerinden çalıştırın ve dağıtmadan önce gerçek bir istemciyle test edin.

TL;DR

MCP sunucusu, bir AI istemcisi ile mevcut sistemleriniz arasında ince ve iyi açıklanmış bir adaptördür. Backend'inizi baştan yazmak değildir.
İşin büyük kısmı tasarımdır: doğru yetenekleri seçmek ve ajanın gerçekten okuyabileceği net, tipli şemalar ve açıklamalar yazmak.
Resmi bir SDK kullanın (TypeScript veya Python). Yerelde stdio ile başlayın, uzak dağıtımlar için HTTP/SSE'ye geçin.
Her zaman scoped kimlik doğrulama, idempotency ve ajanın üzerine hareket edebileceği hata mesajları ekleyin. Ajan, ne döndürürseniz onun üzerine iş yapar.
Gerçek bir istemciyle (Claude, Cursor, ChatGPT) test edin. Sonra dağıtın, metrikleri izleyin ve iyileştirin.

MCP sunucusu nedir ve neden kurulur?

MCP sunucusu, Model Context Protocol konuşan bir süreçtir. Böylece AI istemcileri yeteneklerinizi standart bir biçimde çağırabilir. Her istemci için ayrı bir eklenti yazmak yerine işlevselliğinizi bir kez sunarsınız, MCP uyumlu her istemci onu kullanabilir.

Protokol size üç temel öğe verir:

Öğe	Amacı	Örnek
Tools	Modelin çağırabileceği eylemler	`create_invoice`, `search_orders`
Resources	Modelin yükleyebileceği salt okunur veri	Bir belge, bir kayıt, bir yapılandırma dosyası
Prompts	Yeniden kullanılabilir prompt şablonları	"Bu destek talebini özetle"

Sunucuyu bir sözleşme gibi düşünün. Ajana, makinenin okuyabileceği bir biçimde, ne yapabileceğini ve nasıl yapacağını tam olarak söyler.

MCP sunucusu adım adım nasıl kurulur?

Bu adımları sırayla ilerleyin. İlk birkaçı tasarım kararı, geri kalanı uygulama ve operasyon.

Sunmak istediğiniz yetenekleri ve çıktıları seçin. Veritabanı tablolarınızdan değil, ajanın halletmesi gereken işlerden başlayın. "Bir teslimatı yeniden planla" bir yetenektir. UPDATE deliveries SET ... değildir. Yüzeyi küçük tutun. Birkaç yüksek değerli eylem, elli ince sarmalayıcıdan her zaman daha iyidir.
Her yeteneği bir tool, resource veya prompt'a eşleyin. Yan etkisi olan her şey tool olur. Modelin yüklemesi gereken salt okunur bağlam resource olur. Yeniden kullanılabilir talimat şablonları prompt olur. Emin değilseniz, bütün bir görevi tek çağrıda bitiren daha az ve daha kaba tool'lara doğru eğilin.

Tipli giriş/çıkış şemaları tanımlayın. Her tool, istemcinin argümanları doğrulayabilmesi ve modelin onları doğru doldurabilmesi için kesin bir şema ister. Zorunlu alanlar, enum'lar ve birimler konusunda net olun. İşte küçük, örnekleyici bir tanım:

{
  "name": "search_orders",
  "description": "Müşteri e-postası ve duruma göre siparişleri bulur.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "email": { "type": "string", "format": "email" },
      "status": { "type": "string", "enum": ["open", "shipped", "closed"] }
    },
    "required": ["email"]
  }
}

Her tool'u mevcut API'nize veya iş mantığınıza bağlayın. Tool işleyicisi, uygulamanızın zaten kullandığı servis katmanını çağırsın. Onu yeniden yazmayın. Böylece doğrulama, izinler ve denetim günlükleri insan trafiğinde de ajan trafiğinde de aynı kalır.
Scoped kimlik doğrulama, idempotency ve iyi hata mesajları ekleyin. Çağıranın kimliğini taşıyın ve bir insana uygulayacağınız yetkilendirmenin aynısını zorunlu kılın. Yazma işlemlerini idempotent yapın (örneğin istemcinin sağladığı bir anahtar kabul edin) ki yeniden denemeler güvenli olsun. Bunu atlamayın. Ajanlar başarısızlıkta yeniden dener, yani idempotent olmayan bir yazma gerçek bir risktir. Bir de ajanın akıl yürütebileceği hatalar döndürün: "Bu e-posta için sipariş bulunamadı", "500 Internal Server Error"dan çok daha işe yarar.
Tool açıklamalarını kendiniz için değil, ajan için yazın. Açıklamalar API'nin bir parçasıdır. Ürününüzü hiç görmemiş bir model için yazın: tool ne yapar, ne zaman kullanılır, her parametre ne demektir, geriye ne döner. Kısıtlamaları doğrudan metne koyun ("tutarlar kuruş cinsinden", "en fazla 100 sonuç"). Model yalnızca burada söylediğinizi bilir.
Bir transport ve SDK seçin, sonra yerelde çalıştırın. Resmi bir SDK kullanın. Yaygın tercihler TypeScript ve Python. Yerel geliştirme ve masaüstü istemciler için en az uğraştıran yol stdio: istemci sürecinizi başlatır ve standart giriş/çıkış üzerinden konuşur. Uzak ya da çok kullanıcılı sunucular için HTTP/SSE kullanın. Tipik bir yerel kayıt şöyle görünür:
```
mcp add my-server -- node ./dist/server.js
```
Gerçek bir istemciyle test edin. Claude, Cursor veya ChatGPT'yi bağlayın ve her tool'u gerçekçi prompt'larla çalıştırın. Modelin açıklamalarınızı nasıl okuduğunu ve şemalarınızı nasıl doldurduğunu izleyin. Her belirsizlik hemen kendini gösterir. Çoğu SDK ayrıca bir inspector ile gelir, böylece ham istek ve yanıtları bir sohbet istemcisi dışında inceleyebilirsiniz.
Dağıtın, gözlemleyin, iyileştirin. Sunucuyu, backend'inize güvenli biçimde erişebileceği bir yere dağıtın. Tool çağrılarına günlükleme ve metrik ekleyin (gecikme, hata oranı ve ajanların gerçekte hangi tool'lara uzandığı), sonra gördüklerinize göre şemaları ve açıklamaları sıkılaştırın. Açıklamaları bir kez yazılan yapılandırma değil, yaşayan bir metin olarak ele alın.

MCP sunucusu nasıl güvenli ve güvenilir tutulur?

Her tool çağrısını, otonom bir çağırandan gelen güvenilmez girdi gibi ele alın. Argümanları şemanıza göre doğrulayın, işleyicinin içinde kullanıcı bazlı yetkilendirmeyi zorunlu kılın ve "ajan güveniliyor" diye izinleri asla genişletmeyin. Token'ları ihtiyaç duydukları minimuma indirin, kimin neyi çağırdığını günlükleyin, maliyetli işlemlere hız sınırı koyun.

Güvenilirlik, zaten bildiğiniz disiplinlerden gelir: yazmalarda idempotency anahtarları, alt sistem çağrılarında zaman aşımı ve yeniden denemeler, net ve yapılandırılmış hatalar. Bir ajan, başarısızlıkta bir insandan çok daha sık yeniden dener. Bu yüzden ilk günden tekrarlı çağrılara göre tasarlayın.

Sıkça sorulan sorular

Hangi SDK ve dili kullanmalıyım?

Yığınınıza uyan resmi SDK hangisiyse onu. TypeScript ve Python SDK'ları en yaygın kullanılan ve en iyi belgelenmiş olanlar. Sunucuyu backend'inizle aynı dilde kurarsanız, ekstra bir ağ atlaması olmadan servis katmanınızı doğrudan çağırabilirsiniz.

stdio mı kullanmalıyım, HTTP/SSE mi?

İstemcinin sunucunuzu alt süreç olarak başlattığı yerel ve masaüstü-istemci kurulumlarında stdio kullanın. Sunucu uzaktaysa, kullanıcılar arasında paylaşılıyorsa veya barındırılan bir hizmet olarak çalışıyorsa HTTP/SSE kullanın. Birçok ekip her ikisini de aynı işleyicilerin ardında destekler.

Bir sunucu kaç tool sunmalı?

Düşündüğünüzden az. Net ve sonuç odaklı küçük bir tool kümesi, bir modelin doğru kullanması açısından koca bir ince CRUD sarmalayıcı kataloğundan daha kolaydır. Tek bir görev ajanın beş tool çağrısını gerektiriyorsa, bu onu tek çağrıya indirmenin işaretidir.

Tool açıklamalarımın yeterince iyi olduğunu nasıl anlarım?

Gerçek bir istemciyle test edin ve modelin ne yaptığını izleyin. Model yanlış tool'u seçiyor, zorunlu bir alanı atlıyor ya da bir parametreyi yanlış kullanıyorsa, genellikle iyileştirilmesi gereken model değil açıklamadır. Net açıklamalar, düzeltebileceğiniz en yüksek kaldıraçlı şeydir.

MCP sunucusu kurmak büyük ölçüde iyi API tasarımı pratiğidir. Doğru çıktıları sunun, onları kesin biçimde açıklayın, düzgün güvenceye alın ve gerçek ajan davranışına karşı iyileştirmeye devam edin. Bu temelleri doğru yaparsanız, sunucunuz hiçbir özel entegrasyon gerektirmeden her MCP uyumlu istemcide çalışır.

Bu işi her gün yapan kişilerce tasarlanıp teslim edilmiş üretim sınıfı bir MCP sunucusu istiyorsanız, Toplantı ayarlayın.