MCP Sunucusu Nasıl Yazılır? 30 Satır Python ile Claude'a Kendi Aracınızı Bağlayın

Claude çok şey biliyor ama sizin şirketinizi bilmiyor. Hangi siparişin kargoda olduğunu, stokta kaç ürün kaldığını ya da müşterinin geçen ay ne satın aldığını göremiyor. Her seferinde bu bilgileri kopyalayıp sohbete yapıştırmak da ne pratik ne de güvenli.

Model Context Protocol (MCP) bu boşluğu dolduruyor. Anthropic'in 2024 sonunda açık standart olarak yayınladığı MCP, yapay zekâ uygulamalarını dış araçlara ve verilere bağlamanın ortak dili. Bu yazıda sıfırdan küçük bir MCP sunucusu yazıp Claude'a bağlayacağız. Sonunda Claude'a "12345 numaralı sipariş nerede?" diye sorduğunuzda cevabı sizin sisteminizden alacak.

Kısaca:

• MCP, yapay zekâ uygulamaları için bir "USB-C" gibi: bir kere yazdığınız sunucu, MCP destekleyen her istemciyle çalışır.
• Bir MCP sunucusu üç şey sunabilir: araçlar (tools), kaynaklar (resources) ve prompt şablonları.
• Resmî Python SDK'sı ile bir araç tanımlamak, bir fonksiyona dekoratör eklemek kadar kolay.
• Aynı sunucuyu Claude Desktop'a bir JSON ayarıyla, Claude Code'a tek bir komutla bağlayabilirsiniz.

MCP nedir, neden gerekli?

MCP'den önce her yapay zekâ uygulaması, her araç için kendi entegrasyonunu yazmak zorundaydı. On uygulama ve on araç, yüz ayrı entegrasyon demekti. MCP bu denklemi değiştiriyor: araç sahibi bir MCP sunucusu yazar, yapay zekâ uygulaması bir MCP istemcisi olur ve ikisi ortak protokol üzerinden konuşur.

Mimari üç parçadan oluşur:

• Host (ana uygulama): Kullanıcının etkileşime girdiği uygulama. Claude Desktop, Claude Code ya da bir IDE.
• Client (istemci): Host'un içinde, her sunucuyla bire bir bağlantıyı yöneten bileşen.
• Server (sunucu): Sizin yazdığınız, araçları ve verileri sunan program.

Sunucunuz ne sunabilir?

Web sitelerinin tarayıcıdaki ajanlara araç sunmasını sağlayan WebMCP de aynı fikrin web'e uyarlanmış hâli.

Kurulum

Resmî Python SDK'sını kurarak başlayalım. Python 3.10 veya üzeri gerekiyor:

pip install "mcp[cli]"

İlk MCP sunucusu: Sipariş sorgulama

Aşağıdaki örnek, bir e-ticaret şirketinin sipariş sistemini simüle ediyor. Gerçek projede sözlük yerine veritabanınıza ya da iç API'nize bağlanırsınız.

# siparis_sunucusu.py
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("siparisler")

SIPARISLER = {
    "12345": {"musteri": "Ayşe Y.", "durum": "kargoda", "kargo": "TR998877"},
    "12346": {"musteri": "Mehmet K.", "durum": "hazırlanıyor", "kargo": None},
}

@mcp.tool()
def siparis_durumu(siparis_no: str) -> str:
    """Sipariş numarasına göre siparişin güncel durumunu ve kargo takip numarasını döndürür."""
    siparis = SIPARISLER.get(siparis_no)
    if siparis is None:
        return f"{siparis_no} numaralı sipariş bulunamadı."
    kargo = siparis["kargo"] or "henüz yok"
    return f"Durum: {siparis['durum']}, kargo takip no: {kargo}"

@mcp.tool()
def bekleyen_siparisler() -> list[str]:
    """Henüz kargoya verilmemiş siparişlerin numaralarını listeler."""
    return [no for no, s in SIPARISLER.items() if s["durum"] != "kargoda"]

@mcp.resource("katalog://urunler")
def urun_katalogu() -> str:
    """Satıştaki ürünlerin listesi."""
    return "Kupa (120 TL), Tişört (450 TL), Defter (90 TL)"

if __name__ == "__main__":
    mcp.run()

Hepsi bu kadar. Burada dikkat edilmesi gereken üç şey var:

1. Docstring'ler çok önemli. Claude, bir aracı ne zaman kullanacağına fonksiyonun adına ve açıklamasına bakarak karar verir. "Sipariş sorgular" yerine ne döndürdüğünü ve ne zaman kullanılacağını anlatan açık bir açıklama yazın.
2. Tip ipuçları şemaya dönüşür. siparis_no: str yazdığınızda SDK, Claude'a bu aracın bir metin parametresi beklediğini otomatik bildirir.
3. Hata durumunda anlamlı mesaj döndürün. Sipariş bulunamadığında istisna fırlatmak yerine açıklayıcı bir metin döndürmek, Claude'un kullanıcıya düzgün bir cevap vermesini sağlar.

Test edin: MCP Inspector

Sunucuyu Claude'a bağlamadan önce test etmek için SDK'nın geliştirme modunu kullanın:

mcp dev siparis_sunucusu.py

Bu komut, tarayıcıda MCP Inspector'ı açar. Buradan sunucunuzun araçlarını listeleyebilir, parametre girip çalıştırabilir ve dönen cevabı görebilirsiniz. Claude'un göreceği şeyi önce siz görmüş olursunuz.

Claude Desktop'a bağlama

Claude Desktop, yerel MCP sunucularını claude_desktop_config.json dosyasından okur. Dosyaya Claude Desktop'ın ayarlarındaki geliştirici bölümünden ulaşabilirsiniz. Şu tanımı ekleyin:

{
  "mcpServers": {
    "siparisler": {
      "command": "python",
      "args": ["C:\\projeler\\siparis_sunucusu.py"]
    }
  }
}

Dosya yolunu kendi sisteminize göre tam yol olarak yazın ve Claude Desktop'ı yeniden başlatın. Artık Claude'a "12345 numaralı siparişim nerede?" diye sorduğunuzda siparis_durumu aracını çağırmak için izin isteyecek ve cevabı sizin sisteminizden verecek.

Claude Code'a bağlama

Claude Code kullanıyorsanız işiniz daha da kolay. Terminalde tek bir komut yeterli:

claude mcp add siparisler -- python /tam/yol/siparis_sunucusu.py

claude mcp list ile bağlı sunucuları görebilirsiniz. Claude Code artık kod yazarken de sipariş sisteminize erişebilir; örneğin "bekleyen siparişler için bir hatırlatma e-postası şablonu hazırla" dediğinizde gerçek veriye bakarak çalışır. Claude Code'un genel kullanımı için Claude Code rehberimize göz atabilirsiniz.

Sık yapılan hatalar

stdout'a yazdırmak. Yerel MCP sunucuları, istemciyle standart giriş/çıkış (stdio) üzerinden konuşur. Kodunuzun herhangi bir yerinde print() ile stdout'a bir şey yazarsanız protokol mesajları bozulur ve bağlantı kopar. Hata ayıklama çıktılarını logging modülüyle ya da print(..., file=sys.stderr) ile standart hataya yazın.

Göreli dosya yolları. Claude Desktop sunucunuzu farklı bir çalışma dizininden başlatabilir. Ayar dosyasında ve kodda tam yol kullanın.

Belirsiz araç açıklamaları. "veri getirir" gibi bir açıklama, Claude'un aracı yanlış zamanda kullanmasına ya da hiç kullanmamasına yol açar.

Çok fazla araç. Tek sunucuya onlarca araç koymak, modelin doğru aracı seçmesini zorlaştırır. Araçları odaklı tutun, birbirine çok benzeyen araçları birleştirin.

Güvenlik: Claude'a ne kadar yetki vermeli?

MCP sunucunuz, Claude'un sizin adınıza gerçek sistemlerde işlem yapabilmesi demek. Bu güç dikkat ister:

• En az yetki ilkesi: Salt okuma yeterliyse yazma yetkisi vermeyin. Veritabanına salt okunur bir kullanıcıyla bağlanın.
• Yıkıcı işlemleri ayırın: Silme, ödeme ya da e-posta gönderme gibi araçları ayrı tutun ve istemcinin onay mekanizmasının devrede olduğundan emin olun.
• Girdileri doğrulayın: Modelden gelen parametrelere, bir kullanıcıdan gelen girdiye davrandığınız gibi davranın. SQL sorgularını parametreli yazın.
• Gizli bilgileri koda gömmeyin: API anahtarlarını ortam değişkenlerinden okuyun. Claude Desktop ayarında env alanıyla sunucuya ortam değişkeni geçebilirsiniz.
• Güvenmediğiniz sunucuları kurmayın: Başkasının yazdığı bir MCP sunucusu, bilgisayarınızda sizin yetkinizle çalışan bir programdır.

Sıkça sorulan sorular

MCP sadece Claude ile mi çalışır?

Hayır. MCP açık bir standart ve Anthropic dışındaki birçok yapay zekâ uygulaması ve geliştirici aracı tarafından da destekleniyor. Bir kez yazdığınız sunucuyu MCP destekleyen herhangi bir istemciyle kullanabilirsiniz.

Python dışında hangi dillerle MCP sunucusu yazılabilir?

Resmî SDK'lar arasında TypeScript, Python, Java, Kotlin, C# ve Go gibi diller bulunuyor. Ekibinizin zaten kullandığı dili seçmek en mantıklısı.

Yerel sunucu mu, uzak sunucu mu?

Bu yazıdaki örnek yerel (stdio) bir sunucu: bilgisayarınızda çalışır ve yalnızca sizin kullanımınız içindir. Bir ekibin ya da müşterilerin kullanacağı sunucular için MCP, HTTP üzerinden çalışan uzak sunucuları da destekler. Bu durumda kimlik doğrulama ve yetkilendirme zorunlu hâle gelir.

MCP sunucusu yazmak için yapay zekâ bilgisi gerekir mi?

Hayır. MCP sunucusu yazmak, küçük bir API yazmaktan farksız. Modeli eğitmiyor ya da ayarlamıyorsunuz; yalnızca modelin çağırabileceği fonksiyonları tanımlıyorsunuz.

MCP, yapay zekâyı şirketinizin gerçek verileriyle buluşturmanın en temiz yolu. Kendi sistemleriniz için güvenli bir MCP sunucusu ya da yapay zekâ entegrasyonu geliştirmek isterseniz kurumsal yazılım geliştirme sayfamızdan bize ulaşabilirsiniz.

Kaynaklar