Kendi MCP server’ınızı yazın: Python ile adım adım kurumsal entegrasyon rehberi

MCP server, yapay zekâ uygulamalarına veri ve işlem yetenekleri sunan Model Context Protocol bileşenidir. Python ile geliştireceğiniz bir MCP server sayesinde Claude Code, Cursor veya MCP destekleyen başka bir istemci; şirket içi API’ler, veritabanları, dosyalar ve iş uygulamalarıyla kontrollü biçimde çalışabilir.

Bu rehberde güncel MCP Python SDK ile çalışan basit bir server oluşturacak, bir tool ve resource tanımlayacak, MCP Inspector ile test edecek ve kurumsal dağıtımda dikkat edilmesi gereken güvenlik kurallarını ele alacağız.

MCP Nedir?

Model Context Protocol (MCP), yapay zekâ uygulamalarının dış veri kaynaklarına ve araçlara standart bir yöntemle bağlanmasını sağlayan açık bir protokoldür. MCP mimarisinde host, client ve server farklı sorumluluklara sahiptir. Kullanıcının çalıştığı yapay zekâ uygulaması host görevini üstlenir; MCP client bağlantıyı yönetir; MCP server ise kullanılabilecek araçları, kaynakları ve promptları sunar.

Bileşen	Görevi	Örnek
Host	Kullanıcının etkileşim kurduğu AI uygulaması	Claude Code veya başka bir MCP destekli uygulama
Client	Server ile protokol bağlantısını yönetir	Host içindeki MCP client
Server	Tool, resource ve prompt sunar	CRM sorgulama veya veritabanı erişim server’ı

MCP Server Ne İşe Yarar?

• Şirket içi API veya mikroservisleri yapay zekâya araç olarak sunabilir.
• Yetkili veritabanı sorgularını doğal dil üzerinden çalıştırabilir.
• Doküman, dosya veya bilgi tabanlarını resource olarak erişilebilir hâle getirebilir.
• CRM, ERP, destek sistemi ve proje yönetimi araçlarıyla entegrasyon kurabilir.
• Tekrarlanan kurumsal iş akışlarını kontrollü araç çağrılarına dönüştürebilir.

Hazır MCP server’lar genel amaçlı servisler için yeterli olabilir. Ancak kuruma özel veri modeli, kimlik doğrulama, iş kuralı veya erişim politikası varsa kendi server’ınızı geliştirmeniz gerekir.

Python ile MCP Server Kurulumu

Güncel MCP Python SDK, Python 3.10 veya üzerini gerektirir. Önce proje klasörünü ve sanal ortamı oluşturun:

mkdir mcp-kurumsal-server
cd mcp-kurumsal-server
python -m venv .venv

# macOS / Linux
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

SDK ve geliştirme komutlarını yükleyin:

pip install "mcp[cli]"

# uv kullanıyorsanız
uv add "mcp[cli]"

MCP Python SDK hızlı geliştiği için gerçek projede sürümü bağımlılık dosyanızda sabitleyin ve yükseltme öncesinde resmî migration notlarını inceleyin.

Python ile Basit MCP Server Örneği

Aşağıdaki örnek iki sayıyı toplayan bir tool ve isme göre karşılama metni döndüren bir resource sunar. Kodu server.py dosyasına kaydedin:

from mcp.server import MCPServer

mcp = MCPServer("BlueMark Demo")


@mcp.tool()
def topla(a: int, b: int) -> int:
    """İki tam sayıyı toplar."""
    return a + b


@mcp.resource("karsilama://{isim}")
def karsilama(isim: str) -> str:
    """İsme göre karşılama mesajı döndürür."""
    return f"Merhaba, {isim}!"

Type hint ve docstring’ler önemlidir. SDK bunları kullanarak aracın giriş şemasını ve açıklamasını oluşturabilir. Tool adını ve açıklamasını, modelin aracı hangi durumda çağırması gerektiğini anlayacağı kadar açık yazın.

MCP Server Nasıl Test Edilir?

Server’ı MCP Inspector ile geliştirme modunda açmak için şu komutu kullanın:

mcp dev server.py

# uv ile
uv run mcp dev server.py

Inspector üzerinden server’ın sunduğu tool ve resource listesini görebilir, topla aracını örnek parametrelerle çağırabilir ve dönen sonucu kontrol edebilirsiniz. Yalnızca mutlu yolu değil; eksik parametre, yanlış veri tipi, yetkisiz erişim ve bulunamayan kayıt gibi hata senaryolarını da test edin.

MCP Tool, Resource ve Prompt Arasındaki Fark

Özellik	Ne sunar?	Örnek
Tool	Çalıştırılabilir işlem	Sipariş sorgulama veya kayıt oluşturma
Resource	Okunabilir veri veya içerik	Politika belgesi veya ürün kataloğu
Prompt	Yeniden kullanılabilir görev şablonu	Destek kaydını analiz etme promptu

Veriyi yalnızca okumak gerekiyorsa resource; dış sistemde işlem yapmak gerekiyorsa tool daha uygun olabilir. Yanlış soyutlama, gereksiz yetki ve karmaşık istemci davranışına yol açabilir.

Gerçek API veya Veritabanı Nasıl Bağlanır?

Gerçek projede tool fonksiyonu doğrudan sabit veri döndürmek yerine servis katmanınızı çağırabilir. Bağlantı bilgilerini kaynak koda yazmayın; ortam değişkenlerinden alın. SQL sorgularında parametre kullanın ve modelden gelen girdiyi güvenilir kabul etmeyin.

import os
import sqlite3

from mcp.server import MCPServer

mcp = MCPServer("Personel Bilgi Server")
DB_PATH = os.getenv("DB_PATH", "sirket.db")


@mcp.tool()
def calisan_bilgisi_getir(calisan_id: str) -> dict:
    """Yetkili çalışan ID'si için ad ve departman bilgisini döndürür."""
    if not calisan_id.startswith("EMP"):
        raise ValueError("Geçersiz çalışan ID formatı")

    with sqlite3.connect(DB_PATH) as connection:
        row = connection.execute(
            "SELECT ad, departman FROM calisanlar WHERE id = ?",
            (calisan_id,),
        ).fetchone()

    if row is None:
        return {"bulundu": False}

    return {
        "bulundu": True,
        "ad": row[0],
        "departman": row[1],
    }

Bu örnek eğitim amaçlıdır. Üretim sisteminde uygulama seviyesinde kimlik doğrulama, kullanıcı bazlı yetkilendirme, bağlantı havuzu, zaman aşımı, hata yönetimi ve denetim kaydı eklenmelidir.

MCP Server Güvenliği Nasıl Sağlanır?

• En az yetki: Server yalnızca görevi için gerekli sistem ve kayıtlara erişsin.
• Girdi doğrulama: Model veya kullanıcı tarafından gelen her parametreyi doğrulayın.
• Çıktı minimizasyonu: TC kimlik numarası, şifre, token veya gereksiz kişisel veri döndürmeyin.
• İnsan onayı: Silme, ödeme, yayınlama ve yetki değiştirme gibi işlemlerde onay adımı uygulayın.
• Secret yönetimi: API anahtarlarını ve bağlantı bilgilerini kaynak koddan ayırın.
• Denetim kaydı: Kimlik, araç adı, zaman ve sonuç gibi gerekli bilgileri hassas veriyi açığa çıkarmadan loglayın.
• Hız ve kota sınırı: Kötüye kullanım ve maliyet artışına karşı rate limit uygulayın.

Tool açıklaması veya prompt içindeki “bu işlemi yapma” talimatı tek başına güvenlik kontrolü değildir. Kritik kısıtları server tarafında kod, erişim politikası ve kimlik doğrulama mekanizmalarıyla uygulayın.

MCP Server’ı Claude Code ile Kullanmak

MCP server’ınızı Claude Code’a bağlarken komut, argüman, ortam değişkeni ve bağlantı kapsamını kullandığınız Claude Code sürümünün güncel dokümantasyonuna göre tanımlayın. Önce yerel ve düşük yetkili bir test bağlantısı kurun; üretim sistemlerine doğrudan geniş erişim vermeyin.

MCP sunucusunu Claude Code ile kullanıyorsanız bağlantı komutları, çalışma akışı, test adımları ve proje standartları CLAUDE.md içinde açıklanabilir. Dosyanın kapsamı ve örnek yapısı için CLAUDE.md kurulum ve yapılandırma rehberini inceleyebilirsiniz. CLAUDE.md yönlendirici bağlam sağlar; MCP erişim yetkilerinin teknik olarak server ve istemci yapılandırmasında sınırlandırılması gerekir.

MCP Server Production Ortamına Nasıl Alınır?

Yerel kullanımda stdio taşıması uygun olabilir. Uzak veya çok kullanıcılı dağıtımlarda Streamable HTTP gibi desteklenen taşıma seçenekleri, kimlik doğrulama ve ağ güvenliğiyle birlikte değerlendirilmelidir. Container kullanımı bağımlılıkları izole edebilir; ancak tek başına yetkilendirme sağlamaz.

• SDK ve protokol sürümlerini sabitleyin.
• Health check, timeout, retry ve gözlemlenebilirlik ekleyin.
• Geliştirme, test ve üretim ortamlarının kimlik bilgilerini ayırın.
• Tool sözleşmelerini ve geriye dönük uyumluluğu yönetin.
• Güvenlik testlerini ve bağımlılık taramasını CI/CD sürecine ekleyin.

MCP mimarisini, Python server geliştirmeyi ve kurumsal entegrasyon senaryolarını uygulamalı öğrenmek isteyen ekipler Model Context Protocol (MCP) Eğitimi programını inceleyebilir.

MCP Server Hakkında Sık Sorulan Sorular

Sonuç

Python ile MCP server geliştirmek, yapay zekâ araçlarını kurumun veri ve iş süreçleriyle standart bir arayüz üzerinden buluşturur. Başarılı bir uygulama yalnızca çalışan tool yazmaktan ibaret değildir; doğru yetki modeli, açık tool sözleşmeleri, test, gözlemlenebilirlik ve sürüm yönetimi birlikte tasarlanmalıdır.