MCP server nasil yazilir? MCP server, bir yapay zeka modelinin (LLM) dis dünyaya baglanmasini saglayan, Model Context Protocol (MCP) standardina uygun olarak yazilmis bir araç sunucusudur. Baska bir deyisle MCP server, dil modeline veritabani sorgulama, dosya okuma, API çagirma veya bir CRM kaydi olusturma gibi yetenekleri standart bir arayüz üzerinden kazandiran kod parçasidir. Bu rehber, sifirdan çalisan bir MCP server gelistirmek için izlenmesi gereken adimlari, gerekli araçlari ve dikkat edilmesi gereken noktalari ögretici bir dille açiklar.
MCP Server Nedir ve Neden Yazilir?
Model Context Protocol, Anthropic tarafindan ortaya konan ve yapay zeka uygulamalari ile dis veri kaynaklari arasindaki iletisimi standartlastiran açik bir protokoldür. MCP’den önce her yapay zeka entegrasyonu, her araç için ayri ayri ve birbirinden farkli sekillerde yazilmak zorundaydi. MCP bu kaosu ortadan kaldirir ve “bir kez yaz, her yerde kullan” yaklasimini mümkün kilar.
Bir MCP server, dil modeline hangi araçlara sahip oldugunu, bu araçlarin hangi parametreleri bekledigini ve nasil çalistirildigini bildirir. Model bir araci çagirmak istediginde istek MCP server’a iletilir, server gerçek islemi yapar (örnegin bir veritabanini sorgular) ve sonucu modele geri döndürür. Bu mimari sayesinde model, kendi egitim verisinin disindaki güncel ve özel bilgilere erisebilir.
Bu konunun daha genis çerçevesini ve yapay zeka ajanlarinin nasil çalistigini merak edenler için AI Agent Nedir? Agentic AI’a Kapsamli Rehber yazisi kapsamli bir baslangiç noktasi sunar.
MCP Server Yazmadan Önce Hangi Hazirliklar Gerekir?
Bir MCP server gelistirmeye baslamadan önce birkaç temel bilesenin hazir olmasi gerekir. Bu hazirliklar, gelistirme sürecinin sorunsuz ilerlemesini saglar ve ileride karsilasilabilecek sorunlari en aza indirir.
- Çalisma ortami: Python 3.10+ veya Node.js 18+ sürümlerinden biri kurulu olmalidir. MCP icin resmi SDK’lar bu iki dilde en olgun haldedir.
- SDK seçimi: Python icin mcp paketi, TypeScript icin @modelcontextprotocol/sdk paketi kullanilir.
- Bir MCP istemcisi: Gelistirilen server’i test etmek için Claude Desktop, Cursor veya MCP Inspector gibi bir istemci gereklidir.
- Net bir amaç: Server’in hangi sorunu çözecegi (örnegin hava durumu verisi saglamak, dosya yönetimi yapmak) önceden belirlenmelidir.
Bu temel bilesenler hazir oldugunda gelistirme süreci çok daha öngörülebilir ilerler. Özellikle amacin net olmasi, araçlarin gereksiz yere karmasiklasmasini önler.
MCP Server Adim Adim Nasil Yazilir?
MCP server gelistirme süreci, mantiksal olarak birbirini takip eden birkaç asamadan olusur. Asagidaki adimlar, en yaygin kullanilan Python SDK üzerinden açiklanmistir; ancak ayni mantik diger dillerde de geçerlidir.
1. Adim – Proje yapisini kurmak: Önce bos bir proje klasörü olusturulur ve sanal ortam aktive edilir. Ardindan MCP SDK projeye eklenir. Bu asama, baglilik yönetiminin temiz tutulmasini saglar.
2. Adim – Server’i baslatmak: SDK içinden bir server nesnesi olusturulur. Bu nesne, server’in adini ve tanimlayici bilgilerini tutar. Server, araçlarin ve kaynaklarin baglanacagi merkezi yapidir.
3. Adim – Araç (tool) tanimlamak: MCP server’in kalbi araçlardir. Her araç, bir isim, bir açiklama ve giris parametrelerinden olusur. Açiklama metni özellikle önemlidir; çünkü dil modeli araci ne zaman çagiracagina bu açiklamaya bakarak karar verir. Açik ve net açiklamalar, modelin dogru araci dogru zamanda kullanmasini saglar.
4. Adim – Araç mantigini yazmak: Her araç, çagrildiginda çalisacak bir fonksiyona baglanir. Bu fonksiyon gerçek isi yapar: bir API’ye istek atar, bir veritabanini sorgular veya bir hesaplama gerçeklestirir. Sonuç, modele anlamli bir formatta geri döndürülür.
5. Adim – Tasima katmanini seçmek: MCP server’lar iki temel yöntemle iletisim kurar. Yerel kullanim için stdio (standart giris/çikis), uzak veya web tabanli kullanim için ise HTTP/SSE tercih edilir. Baslangiç projeleri için stdio en pratik seçenektir.
6. Adim – Server’i çalistirmak: Son olarak server bir komutla baslatilir ve bir MCP istemcisine baglanir. Bu noktada server, modelin kullanimina hazir hale gelir.
Python ile Basit Bir MCP Server Örnegi Nasil Olur?
Asagidaki örnek, Python SDK kullanilarak yazilmis minimal bir MCP server’in iskeletini gösterir. Bu örnekte iki sayiyi toplayan basit bir araç tanimlanmistir. Amaç, sözdiziminden çok yapinin mantigini kavratmaktir.
Önce FastMCP sinifindan bir server nesnesi olusturulur. Ardindan bir fonksiyon, bir dekoratör (örnegin @mcp.tool()) ile araç olarak isaretlenir. Fonksiyonun adi araç adini, açiklama satiri (docstring) ise modelin görecegi açiklamayi olusturur. Parametre tipleri (örnegin int veya str) otomatik olarak sema haline getirilir. Son satirda server, stdio tasima katmaniyla çalistirilir.
Bu kadar küçük bir kod parçasi bile, bir dil modeline matematiksel toplama yetenegi kazandirmak için yeterlidir. Gerçek projelerde fonksiyonun içi; bir hava durumu API’sine, bir SQL veritabanina veya bir dosya sistemine baglanacak sekilde genisletilir. Önemli olan, her aracin tek bir net görevi yerine getirmesi ve açiklamasinin bu görevi dogru anlatmasidir.
stdio ve HTTP Tasima Yöntemleri Arasindaki Fark Nedir?
MCP server gelistirirken verilecek en önemli teknik kararlardan biri, tasima (transport) katmaninin seçimidir. Bu seçim, server’in nerede ve nasil kullanilacagini dogrudan etkiler. Asagidaki tablo iki yöntemi karsilastirir.
| Özellik | stdio | HTTP / SSE |
|---|---|---|
| Kullanim yeri | Yerel makine | Uzak sunucu / web |
| Kurulum zorlugu | Çok kolay | Orta |
| Kimlik dogrulama | Gerekmez | Genellikle gerekir |
| Çoklu kullanici | Uygun degil | Uygun |
| Tipik senaryo | Masaüstü istemci eklentisi | Bulut tabanli hizmet |
Genel kural sudur: bir araç yalnizca kisisel bilgisayarda Claude Desktop veya Cursor gibi bir istemciyle çalisacaksa stdio yeterlidir. Birden fazla kullaniciya hizmet verecek, internete açik bir server gerekiyorsa HTTP/SSE tercih edilmeli ve mutlaka kimlik dogrulama eklenmelidir.
MCP Server Nasil Test Edilir ve Yayinlanir?
Server kodu yazildiktan sonra, gerçek kullanima geçmeden önce dogru çalistigindan emin olunmalidir. Test asamasi, ilerleyen dönemde yasanabilecek hatalari erken yakalamak açisindan kritiktir.
En pratik test araci MCP Inspector‘dir. Bu araç, server’i bir web arayüzünde açar; tanimlanan araçlari listeler ve her birini manuel olarak çalistirip sonucunu görmeyi saglar. Böylece bir dil modeline baglamadan önce araçlarin beklendigi gibi çalisip çalismadigi kontrol edilebilir.
Testler basariyla geçtiyse server bir istemciye baglanir. Claude Desktop için bu islem, yapilandirma dosyasina server’in komutunu eklemekle yapilir. Cursor ve benzeri araçlarda da süreç oldukça benzerdir. Yayinlama asamasinda dikkat edilmesi gereken birkaç önemli nokta vardir:
- Hata yönetimi: Araçlar, basarisiz durumlarda anlamli hata mesajlari döndürmelidir.
- Güvenlik: API anahtarlari ve sifreler asla kod içine gömülmemeli, ortam degiskenleri ile yönetilmelidir.
- Dökümantasyon: Her aracin ne yaptigi açikça yazilmali, böylece hem model hem de gelistiriciler kolayca anlayabilmelidir.
- Sürüm kontrolü: Server kodu bir depo (örnegin Git) üzerinde tutulmali ve degisiklikler izlenmelidir.
Bu adimlar tamamlandiginda MCP server, üretim ortaminda güvenle kullanilabilir hale gelir. Iyi yazilmis bir MCP server, modelin yeteneklerini katlanarak artirir ve yapay zeka uygulamalarini gerçek dünya verileriyle bulusturur.
MCP Server Yazarken En Sik Yapilan Hatalar Nelerdir?
Gelistiriciler MCP server yazarken bazi tekrar eden hatalara düsebilir. Bu hatalari önceden bilmek, gelistirme sürecini hizlandirir ve daha saglam server’lar üretmeyi saglar.
- Belirsiz araç açiklamalari: Modelin araci ne zaman kullanacagini anlayamamasina yol açar. Açiklamalar somut ve net olmalidir.
- Asiri genis araçlar: Tek bir aracin çok fazla is yapmaya çalismasi, modelin kafasini karistirir. Her araç tek bir göreve odaklanmalidir.
- Zaman asimi yönetiminin eksikligi: Yavas çalisan dis servisler için zaman asimi süreleri tanimlanmalidir.
- Güvenlik açiklari: Dogrulanmamis girdilerin dogrudan veritabanina veya komut satirina iletilmesi ciddi risk olusturur.
Bu yaygin tuzaklardan kaçinmak, hem daha güvenilir hem de daha kullanisli bir MCP server ortaya çikarir.
Sikça Sorulan Sorular
MCP server yazmak için hangi programlama dili gerekir?
En yaygin seçenekler Python ve TypeScript’tir; çünkü resmi SDK’lar bu dillerde sunulur. Ancak protokol dilden bagimsiz oldugu için diger dillerde de server yazilabilir.
MCP server ile API arasindaki fark nedir?
API genel amaçli bir arayüzdür; MCP server ise bir API’yi veya veri kaynagini özellikle dil modellerinin anlayacagi standart bir formatta sunan bir katmandir.
MCP server yazmak ücretsiz mi?
Evet, MCP açik bir standarttir ve SDK’lari ücretsizdir. Yalnizca kullanilan dis servisler (örnegin bazi API’ler) ücretli olabilir.
Tek bir MCP server’da kaç araç tanimlanabilir?
Teknik bir üst sinir yoktur; ancak çok fazla araç modelin seçim yapmasini zorlastirir. Ilgili araçlari mantikli gruplar halinde tutmak önerilir.
MCP server’i internete açmak güvenli midir?
Açilabilir, ancak mutlaka kimlik dogrulama, girdi dogrulama ve yetkilendirme mekanizmalari eklenmelidir. Aksi halde ciddi güvenlik riskleri olusur.