Ocak ayında ilk MCP sunucumuzu bir araç takip müşterisi için yazdığımızda, toplam araç sayımız 23'tü. Bugün aynı sunucuda 7 araç var ve sistem her açıdan daha iyi çalışıyor. Bu cümleyi bilerek yazının başına koydum, çünkü altı aydır müşterilerimize özel MCP sunucuları geliştiriyoruz ve öğrendiğimiz en pahalı dersler hep aynı yönü gösteriyor: bu işte fazlalık, eksiklikten daha çok zarar veriyor. İlk sunucusunu yazacak ekipler için bu yazı, o altı ayın süzülmüş ders notudur.
Önce iyi haber: SDK'lar (Python ve TypeScript) işi şaşırtıcı derecede kolaylaştırıyor. Basit bir sunucuyu bir öğleden sonra ayağa kaldırabilirsiniz. Kötü haber de tam burada saklı: kolay başlangıç, kötü tasarımı da kolaylaştırıyor. Çalışan bir şeye ulaşmak o kadar hızlı ki, "ne yapmalıyım" sorusunu hiç sormadan "nasıl yaparım" moduna geçmek işten değil.
Erken verilecek kararlardan biri de çalışma şekli: sunucu geliştiricinin makinesinde stdio ile mi konuşacak, yoksa ağ üzerinden, kimlik doğrulamalı bir uzak sunucu mu olacak? Kişisel kullanım ve prototip için ilki yeterli; birden fazla kullanıcının erişeceği kurumsal senaryoda ikincisi kaçınılmaz — ve kimlik doğrulamayı baştan tasarlamak, sonradan eklemekten kat kat ucuz. Bunu ocaktaki anatomi yazısında da söylemiştim, altı ayın tecrübesiyle altını bir kez daha çiziyorum.
REST API'nizi kopyalamayın; işi tasarlayın
En sık gördüğümüz hata şu: ekip mevcut REST API'sini alıyor, her endpoint'i bire bir araca çeviriyor. 40 endpoint, 40 araç. Kâğıt üstünde mantıklı, pratikte felaket. Model her soruda 40 seçenek arasında boğuluyor, benzer isimli araçları karıştırıyor, üç araçla yapılacak işi yedi çağrıya yayıyor.
Doğru soru "API'de ne var?" değil, "kullanıcı bu sistemle hangi işleri yapmak isteyecek?" sorusudur. Cevap neredeyse her zaman 5-8 iş çıkarır. Bizim araç takip sunucumuzda bu süzme şöyle sonuçlandı: arac_konum(plaka), rolanti_raporu(tarih_araligi), hiz_ihlalleri(esik) ve benzeri birkaç araç daha. Her biri bir iş sorusuna karşılık geliyor, bir veritabanı tablosuna değil. Az, isabetli, iyi açıklanmış araç; çok ve jenerik araçtan her zaman iyidir. 23'ten 7'ye inme hikâyemiz tam olarak buydu.
Peki o 5-8 işi nasıl buluyoruz? Yöntem hiç romantik değil: sistemin gerçek kullanıcılarıyla — operasyon müdürü, muhasebeci, destek temsilcisi — yarım saat oturup "bu sisteme en son ne sormak istediniz de soramadınız?" diyoruz. Bir de mevcut rapor ekranlarının kullanım loglarına bakıyoruz; en çok açılan beş rapor, ilk araçlarınızın en güçlü adaylarıdır. Araç listesi masa başında değil, sahada belirlenir. Masa başında belirlenen listeler, o 23 araçlı ilk sürümümüz gibi olur.
Açıklama yazmak dokümantasyon değil, mühendisliktir
Şunu kafamıza geç kazıdık: modelin sizin sisteminiz hakkındaki tek bilgisi, araç açıklamalarınızdır. Kod ne kadar şık olursa olsun, açıklama kötüyse sunucu kötüdür.
İyi bir açıklama dört şeyi söyler: aracın ne yaptığını, parametrelerin biçimini ve birimini, ne zaman kullanılacağını ve — bu hep unutulur — ne zaman kullanılmayacağını. "tarih: string" yazmak açıklama değildir; "tarih: YYYY-AA-GG formatında, örn. 2025-07-01" yazmak açıklamadır. "Bu araç geçmiş veriler içindir; canlı konum için arac_konum kullanın" gibi bir yönlendirme, modelin karar kalitesini gözle görülür yükseltir.
Ve açıklamalarınızı test edin. Bizim yöntemimiz basit: modele 20 gerçekçi kullanıcı sorusu soruyoruz ve hangi aracı seçtiğine bakıyoruz. Yanlış araç seçtiği her vaka, modelin değil açıklamanın hatasıdır — açıklamayı düzeltip tekrar koşuyoruz. Bu döngüyü ilk sunucumuzda dört tur döndük; dördüncü turda isabet neredeyse tama ulaştı.
İsimlendirmeyi de açıklamanın parçası sayın. Araç adları arasında dil ve kalıp tutarlılığı kurun; yarısı İngilizce yarısı Türkçe, yarısı fiille yarısı isimle başlayan bir liste modelin işini sessizce zorlaştırır. Biz "nesne_eylem" kalıbında ve tek dilde karar kıldık. Hangi kalıbı seçtiğinizden çok, seçtiğinize istisnasız sadık kalmanız önemli.
Üretime çıkmadan önce beş kapı
Demo ile üretim arasındaki farkı altı ayda iyice öğrendik. Bizim üretim kontrol listemizin özü şu beş madde:
- Dar yetki: Sunucu, arkasındaki sisteme mümkün olan en dar yetkiyle bağlanır — salt okunur veritabanı kullanıcısı, kapsamı daraltılmış API anahtarı. "Her şeye yetkili servis hesabı" gördüğümüz kurulumu üretime almayız.
- Şema doğrulama: Parametreler JSON Schema ile sıkı sınırlanır; serbest SQL veya shell komutu alan araç, bizim sözlüğümüzde araç değil açık kapıdır.
- Düzeltici hata mesajları: Modele dönen hata, modelin kendini toparlamasını sağlamalı. "Hata: kayıt yok" yerine "plaka bulunamadı; beklenen format: 34ABC123". Model bu ipucuyla ikinci denemede genellikle doğruyu buluyor.
- Tam loglama: Kim, hangi araç, hangi parametreler, sonuç boyutu, süre. Denetlenebilirlik pazarlık konusu değil.
- Sayfalı sonuç: 10 bin satır dönen araç, modelin bağlamını boğar ve kaliteyi düşürür. Özet + "devamı için şu anahtarı kullan" deseni her zaman daha iyi çalışıyor.
Bu beşin hiçbiri havalı değil, farkındayım. Ama üretimde sunucunuzu ayakta tutan şeyler tam olarak bunlar oluyor; havalı kısım (modelin doğal dille rapor dökmesi) zaten SDK sayesinde bedavaya geliyor.
Listenin dışında ama aklınızın içinde durması gereken iki konu daha var. Birincisi zaman aşımı: aracın arkasındaki sistem yavaşladığında model, dakikalarca dönen bir kum saatine dönüşmemeli; her araca makul bir timeout ve "işlem uzun sürüyor, birazdan tekrar sorun" tarzı bir dönüş tanımlayın. İkincisi sürümleme: bir aracın adını veya parametresini değiştirmek, o aracı öğrenmiş bütün istemcileri ve alışkanlıkları etkiler. API sürümlemede gösterdiğiniz özeni araç tanımlarında da gösterin; "nasılsa açıklamayı güncelleriz" rahatlığı, üretimde pahalıya patlar.
Küçük başlayın, ama üretim kalitesinde başlayın
Altı ayın belki de en önemli dersi şu oldu: ilk sunucunuz küçük olsun ama oyuncak olmasın. İki-üç gerçek araçla, gerçek yetki kısıtlarıyla, gerçek loglamayla başlayın; kullanıcılar (yani muhtemelen önce kendi ekibiniz) onunla gerçek iş yapsın. "Önce demo yapalım, güvenliği üretimde ekleriz" diyen her ekip, demoyu üretime alırken baştan yazıyor — bunu hem kendimizde hem müşterilerde gördük.
Bir de beklemediğimiz bir yan fayda: MCP sunucusu yazmak, kendi sisteminizin aynası oluyor. "Kullanıcı bu sistemden hangi 5-8 işi ister?" sorusuna cevap ararken, yıllardır kimsenin kullanmadığı endpoint'leri, tutarsız isimlendirmeleri, eksik raporları fark ediyorsunuz. İki müşterimizde MCP projesi, ana API'nin de temizlenmesiyle sonuçlandı.
Sisteminizi yapay zekâya güvenle açmayı düşünüyorsanız, tavsiyem hemen 40 araçlı bir dev proje kurgulamamanız: bir iş alanı seçin, 5 araç tasarlayın, dar yetkiyle yayına alın, kullanımı izleyin. Bu ilk adımı nasıl atacağınızı konuşmak isterseniz ücretsiz bir ön analizle başlayabiliriz; hangi araçların gerçekten gerekli olduğunu birlikte süzeriz — 23'ten 7'ye biz düşürdük, sizinkini baştan 7 tutarız.