AI Atlas
Tüm rehberler
🛠️ REHBER

Kendi MCP Sunucunuzu Yazın

Sıfırdan, kendi AI asistanınıza yetenek katan bir MCP sunucusu yazın: 2026-07-28 spesifikasyonunda ne değişti, TypeScript SDK v2 ve Python SDK 2.x ile test edilmiş yerel görev yöneticisi, Inspector ile test, Claude Desktop ve Claude Code'a bağlama, MCP Registry'de yayınlama.

Güncellendi:

MCP Server SDK
KENDİ MCP SUNUCUNU YAZ server.ts import { Server } server.tool({ name: 'add_task', inputSchema: { … }, handler }) // stdio transport stdio AI Asistan (Claude, Cline, Continue…) list_tasks() add_task(...) search_tasks(q) Yerel görev yöneticisi → tek bir sunucu, her host'la uyumlu.

Niye kendi MCP sunucunu yazasın?

MCP (Model Context Protocol), bir AI asistanına dış dünyaya dokunma yeteneği vermenin standart yolu. Hazır sunucular (bkz. MCP Server Kataloğu) yaygın ihtiyaçların çoğunu karşılıyor, ama bazı durumlarda kendi sunucunu yazman gerekir:

  • Kişisel asistan: kendi notlarınla, alışkanlıklarınla, kendi verinle konuşan bir asistan istiyorsundur.
  • Şirket içi sistem: kurum içi CRM, ERP ya da ürün API'sini asistana açmak istiyorsundur.
  • Paketlenmiş açık kaynak araç: topluluğa yararlı bir entegrasyonu MCP olarak dağıtırsın.
  • Kontrol katmanı: bir SaaS API'sini ham vermek yerine sınırları belli bir tool olarak sunarsın.

Bu rehber, host'tan bağımsız bir MCP sunucusunu uçtan uca yazmayı anlatıyor. MCP'yi destekleyen her asistan (Claude Desktop, Claude Code, Cursor, VS Code, Cline ve diğerleri) aynı sunucuya bağlanabilir.

Önce: 2026-07-28 spesifikasyonunda ne değişti?

MCP'nin güncel sürümü 2026-07-28 (28 Temmuz 2026'da stable olarak yayımlandı). İnternetteki eski örneklerin çoğu bir önceki sürüme (2025-11-25) göre yazıldığı için farkları bilmek önemli. Resmî değişiklik listesine göre başlıcaları:

  • Protokol durumsuz. initialize / notifications/initialized el sıkışması kalktı. Her istek kendi protokol sürümünü ve istemci yeteneklerini _meta alanında taşıyor (io.modelcontextprotocol/protocolVersion, io.modelcontextprotocol/clientCapabilities).
  • Oturum yok. Streamable HTTP'deki Mcp-Session-Id başlığı ve protokol düzeyindeki oturumlar kaldırıldı. Çağrılar arasında durum tutması gereken sunucu, kendi ürettiği bir tanıtıcıyı (handle) sıradan bir tool argümanı olarak döndürüp geri alıyor.
  • server/discover zorunlu. Sunucu desteklediği sürümleri, yetenekleri ve kimliğini bu çağrıyla bildiriyor.
  • Sunucudan istemciye istek yok. sampling/createMessage, elicitation/create gibi sunucunun başlattığı istekler yerine Multi Round-Trip Requests geldi: sunucu resultType: "input_required" ile ek bilgi istiyor, istemci isteği bu bilgiyle yeniden gönderiyor. Her sonuçta artık resultType alanı var.
  • Değişiklik bildirimleri tek bir subscriptions/listen akışında toplandı; ping ve logging/setLevel kaldırıldı.
  • Deprecated: Roots, Sampling ve Logging özellikleri; eski HTTP+SSE transport'u (yerine Streamable HTTP); Dynamic Client Registration (yerine Client ID Metadata Documents).

İyi haber: resmî SDK'lar bunların çoğunu görünmez kılıyor. Aşağıdaki iki sunucu, aynı koddan hem 2026-07-28 istemcilerine hem de el sıkışma kullanan 2025 dönemi istemcilerine cevap veriyor.

MCP'nin parçaları

Bir sunucu üç şey sunar:

  • Tools: asistanın çağırabileceği fonksiyonlar (örn. add_task).
  • Resources: asistanın okuyabileceği veri kaynakları (örn. dosya, kayıt).
  • Prompts: sunucunun önerdiği hazır prompt şablonları.

Çoğu pratik senaryoda tools yeter; bu rehber tool odaklı. Yerel sunucular stdio üzerinden (host sunucuyu alt süreç olarak başlatır, satır satır JSON-RPC mesajı alışverişi yapılır), uzak sunucular Streamable HTTP üzerinden konuşur.

Senaryo: kişisel görev yöneticisi

Asistana "yarın için 'rapor hazırla' ekle", "bu hafta yapılacaklarımı listele", "X görevini bitti işaretle" demek istiyorsun. Veri bir bulut servisinde değil, kendi diskindeki bir JSON dosyasında duruyor.

Tool'lar:

  • list_tasks(status?, due_before?) — görevleri listele.
  • add_task(title, due?, tags?) — yeni görev ekle.
  • complete_task(id) — görevi tamamlandı işaretle.
  • search_tasks(query) — başlığa veya etikete göre ara.

Veri varsayılan olarak ~/.tasks.json dosyasında; TASKS_FILE ortam değişkeniyle başka bir dosya gösterilebilir (test ederken işe yarar).

Aynı sunucuyu önce TypeScript, sonra Python ile yazacağız. İkisi de 8 Kasım 2026'da @modelcontextprotocol/server 2.4.0 ve mcp 2.3.0 ile, 2026-07-28 ve 2025-11-25 istemcilerine karşı test edildi.

TypeScript ile yazım

TypeScript SDK'nın v2 hattı, eski tek paket @modelcontextprotocol/sdk yerine ayrı sunucu ve istemci paketleriyle geliyor. v1 (1.x) hâlâ yayımlanıyor ama en yeni protokol olarak 2025-11-25'i biliyor; yeni projede v2 kullan.

Projeyi başlat

mkdir tasks-mcp && cd tasks-mcp
npm init -y
npm pkg set type=module
npm install @modelcontextprotocol/server zod
npm install -D typescript @types/node

tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "types": ["node"]
  },
  "include": ["src"]
}

"types": ["node"] satırı gerekli: SDK'nın README'sine göre TypeScript 6.0 ve sonrası @types/* paketlerini artık kendiliğinden dahil etmiyor.

Sunucu kodu

src/index.ts:

import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { z } from "zod";
import { readFile, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { homedir } from "node:os";
import { randomUUID } from "node:crypto";

const STORE = process.env.TASKS_FILE ?? join(homedir(), ".tasks.json");

type Task = {
  id: string;
  title: string;
  due?: string; // ISO tarih
  tags?: string[];
  done: boolean;
  created: string;
};

async function loadTasks(): Promise<Task[]> {
  try {
    return JSON.parse(await readFile(STORE, "utf8"));
  } catch {
    return [];
  }
}

async function saveTasks(tasks: Task[]) {
  await writeFile(STORE, JSON.stringify(tasks, null, 2), "utf8");
}

const text = (t: string) => ({ content: [{ type: "text" as const, text: t }] });

function createServer() {
  const server = new McpServer({ name: "tasks-mcp", version: "0.1.0" });

  server.registerTool(
    "list_tasks",
    {
      description: "Yapılacaklar listesini döner. Durum ve son tarih filtresi isteğe bağlı.",
      inputSchema: z.object({
        status: z.enum(["open", "done", "all"]).default("open"),
        due_before: z.string().optional().describe("ISO tarih; yalnızca bundan önce bitecek görevler"),
      }),
      annotations: { readOnlyHint: true },
    },
    async ({ status, due_before }) => {
      const before = due_before ? new Date(due_before) : null;
      const hits = (await loadTasks()).filter((t) => {
        if (status === "open" && t.done) return false;
        if (status === "done" && !t.done) return false;
        if (before && (!t.due || new Date(t.due) >= before)) return false;
        return true;
      });
      return text(JSON.stringify(hits, null, 2));
    },
  );

  server.registerTool(
    "add_task",
    {
      description: "Yeni bir görev ekler. due ISO tarih biçiminde; tags bir metin dizisi.",
      inputSchema: z.object({
        title: z.string().describe("Görev başlığı"),
        due: z.string().optional().describe("Son tarih, ISO biçiminde"),
        tags: z.array(z.string()).optional().describe("Etiketler, örn. ['iş', 'rapor']"),
      }),
    },
    async ({ title, due, tags }) => {
      const tasks = await loadTasks();
      const task: Task = { id: randomUUID().slice(0, 8), title, due, tags, done: false, created: new Date().toISOString() };
      tasks.push(task);
      await saveTasks(tasks);
      return text(`Eklendi: ${task.id} — ${task.title}`);
    },
  );

  server.registerTool(
    "complete_task",
    {
      description: "Bir görevi tamamlandı olarak işaretler.",
      inputSchema: z.object({ id: z.string().describe("Görev ID'si") }),
      annotations: { idempotentHint: true },
    },
    async ({ id }) => {
      const tasks = await loadTasks();
      const t = tasks.find((x) => x.id === id);
      if (!t) return { ...text(`Görev bulunamadı: ${id}`), isError: true };
      t.done = true;
      await saveTasks(tasks);
      return text(`Tamamlandı: ${t.title}`);
    },
  );

  server.registerTool(
    "search_tasks",
    {
      description: "Başlığa veya etikete göre görev arar.",
      inputSchema: z.object({ query: z.string() }),
      annotations: { readOnlyHint: true },
    },
    async ({ query }) => {
      const q = query.toLowerCase();
      const hits = (await loadTasks()).filter(
        (t) => t.title.toLowerCase().includes(q) || (t.tags ?? []).some((tag) => tag.toLowerCase().includes(q)),
      );
      return text(JSON.stringify(hits, null, 2));
    },
  );

  return server;
}

// serveStdio aynı fabrikadan hem 2026-07-28 (istek başına sürüm) hem de
// 2025 dönemi (initialize el sıkışmalı) istemcilere cevap verir.
serveStdio(createServer);

Derle ve çalıştır:

npx tsc
node dist/index.js

Terminal sessiz bekler; bu normal, sunucu stdin'den mesaj bekliyor. Kodun ana parçaları:

  1. registerTool her tool'u adı, açıklaması ve bir Zod şemasıyla kaydeder. SDK şemayı istemciye JSON Schema olarak ilan eder ve gelen argümanları doğrular: zorunlu bir alan eksikse tool hiç çalışmaz, istemci açıklayıcı bir hata alır.
  2. annotations (readOnlyHint, idempotentHint) host'a tool'un davranışı hakkında ipucu verir; örneğin salt okunur tool'lar için onay istemeyebilir. Bunlar ipucudur, güvenlik garantisi değil.
  3. isError: true iş mantığı hatasını (görev bulunamadı) protokol hatasından ayırır; model mesajı okuyup kullanıcıya düzgün aktarır.
  4. serveStdio(createServer) bir fabrika fonksiyonu alır ve bağlantının hangi protokol dönemiyle açıldığına göre doğru şekilde servis eder.

Python ile yazım

Python SDK'nın 2.x sürümü yüksek seviyeli MCPServer sınıfıyla geliyor: fonksiyonun tip ipuçları şemanın kendisi, docstring de açıklaması.

python -m venv .venv
.venv/bin/pip install mcp

tasks_mcp/server.py:

import json
import os
import uuid
from datetime import datetime, timezone
from pathlib import Path
from typing import Literal

from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ToolError

STORE = Path(os.environ.get("TASKS_FILE", Path.home() / ".tasks.json"))

mcp = MCPServer("tasks-mcp", version="0.1.0")


def load_tasks() -> list[dict]:
    if not STORE.exists():
        return []
    return json.loads(STORE.read_text("utf-8"))


def save_tasks(tasks: list[dict]) -> None:
    STORE.write_text(json.dumps(tasks, indent=2, ensure_ascii=False), "utf-8")


@mcp.tool()
def list_tasks(status: Literal["open", "done", "all"] = "open", due_before: str | None = None) -> list[dict]:
    """Yapılacaklar listesini döner. due_before ISO tarih; yalnızca bundan önce bitecek görevler gelir."""
    out = []
    for t in load_tasks():
        if status == "open" and t["done"]:
            continue
        if status == "done" and not t["done"]:
            continue
        if due_before and (not t.get("due") or t["due"] >= due_before):
            continue
        out.append(t)
    return out


@mcp.tool()
def add_task(title: str, due: str | None = None, tags: list[str] | None = None) -> str:
    """Yeni bir görev ekler. due ISO tarih biçiminde; tags bir metin listesi."""
    tasks = load_tasks()
    task = {
        "id": uuid.uuid4().hex[:8],
        "title": title,
        "due": due,
        "tags": tags,
        "done": False,
        "created": datetime.now(timezone.utc).isoformat(),
    }
    tasks.append(task)
    save_tasks(tasks)
    return f"Eklendi: {task['id']} — {title}"


@mcp.tool()
def complete_task(id: str) -> str:
    """Bir görevi tamamlandı olarak işaretler."""
    tasks = load_tasks()
    for t in tasks:
        if t["id"] == id:
            t["done"] = True
            save_tasks(tasks)
            return f"Tamamlandı: {t['title']}"
    raise ToolError(f"Görev bulunamadı: {id}")


@mcp.tool()
def search_tasks(query: str) -> list[dict]:
    """Başlığa veya etikete göre görev arar."""
    q = query.lower()
    return [
        t for t in load_tasks()
        if q in t["title"].lower() or any(q in tag.lower() for tag in (t.get("tags") or []))
    ]


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

Çalıştır:

.venv/bin/python tasks_mcp/server.py

Farklar:

  • Şema tip ipuçlarından çıkıyor. Literal[...] enum'a, varsayılanı olan parametreler isteğe bağlı alanlara dönüşüyor; elle JSON Schema yazmıyorsun.
  • Dönüş tipi yapılandırılmış çıktı olur. list[dict] döndüren tool, sonucu hem metin olarak hem de structuredContent alanında veriyor.
  • ToolError fırlatmak, sonucu isError: true olarak işaretliyor.
  • mcp.run() varsayılan olarak stdio üzerinden çalışıyor ve iki protokol dönemini de karşılıyor.

Test: MCP Inspector

Sunucuyu host'a bağlamadan önce resmî MCP Inspector ile dene. Inspector'ın 2.x hattı bir web arayüzü, bir CLI ve bir TUI ile geliyor; README'ye göre Node ^22.23.4, ^24.22.1 ya da >=26.12.1 istiyor.

# Web arayüzü
npx @modelcontextprotocol/inspector node dist/index.js

# CLI ile tek komutta tool listesi
npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list

# Python sunucusunda bir tool çağrısı
npx @modelcontextprotocol/inspector --cli .venv/bin/python tasks_mcp/server.py \
  --method tools/call --tool-name add_task --tool-arg title=deneme

Tool listesini doğrula, birkaç görev ekleyip listele, bilerek eksik parametre gönderip hatanın nasıl döndüğünü gör. Test sırasında gerçek dosyanı kirletmemek için -e TASKS_FILE=/tmp/test-tasks.json ekleyebilirsin.

Bir AI asistana bağlama

MCP standart olduğu için aynı sunucu her MCP uyumlu host'a bağlanır. Mantık aynı: host'a "şu komutu alt süreç olarak başlat" diyorsun. Yollar mutlak olmalı; host sunucuyu senin terminalindeki çalışma dizininden başlatmaz.

Claude Desktop için tipik yapılandırma:

{
  "mcpServers": {
    "tasks": {
      "command": "node",
      "args": ["/tam/yol/tasks-mcp/dist/index.js"]
    }
  }
}

Python tarafında sanal ortamın Python'unu ve betiğin tam yolunu ver:

{
  "mcpServers": {
    "tasks": {
      "command": "/tam/yol/tasks-mcp/.venv/bin/python",
      "args": ["/tam/yol/tasks-mcp/tasks_mcp/server.py"],
      "env": { "TASKS_FILE": "/tam/yol/gorevler.json" }
    }
  }
}

Host'a göre:

  • Claude Desktop: Ayarlar → Developer → Edit Config ile açılan claude_desktop_config.json. Konumu macOS'te ~/Library/Application Support/Claude/, Windows'ta %APPDATA%\Claude\, Linux'ta ~/.config/Claude/. Değişiklikten sonra uygulamayı tamamen kapatıp yeniden aç.

  • Claude Code: en kolayı CLI:

    claude mcp add tasks -- node /tam/yol/tasks-mcp/dist/index.js
    # tüm projelerde kullanmak için kullanıcı kapsamı:
    claude mcp add tasks --scope user -e TASKS_FILE=/tam/yol/gorevler.json -- node /tam/yol/tasks-mcp/dist/index.js

    Claude Code'un belgelerine göre local ve user kapsamı ~/.claude.json dosyasında, project kapsamı (ekiple paylaşılan) proje kökündeki .mcp.json dosyasında tutuluyor. .mcp.json içinde ${VAR} ve ${VAR:-varsayılan} ile ortam değişkeni kullanabilirsin; bu Claude Code'un bir özelliği, her host'ta çalışmaz.

  • Cursor, VS Code, Cline ve diğerleri: kendi arayüzlerinden ya da benzer bir JSON dosyasından MCP sunucusu eklenir; alan adları küçük farklar gösterebilir, kendi belgelerine bak.

  • Kendi uygulaman: @modelcontextprotocol/client (TypeScript) ya da mcp paketinin istemci tarafı (Python) ile sunucuya bağlanıp tool'larını kendi LLM çağrılarına ekleyebilirsin. TypeScript SDK v2 istemcisi varsayılan olarak 2025 el sıkışmasını kullanıyor; 2026-07-28 ile konuşmak için versionNegotiation: { mode: "auto" } seçeneğini açman gerekiyor.

Host sunucuyu başlatınca asistana "yarın için 'rapor hazırla' ekle" dediğinde add_task çağrılır, dosyaya yazılır, kısa bir özet döner.

En sık tuzaklar

stdout'a log basmak

stdio'da stdout protokol kanalıdır. Spesifikasyona göre sunucu stdout'a geçerli bir MCP mesajı dışında hiçbir şey yazmamalı; log için stderr kullanılabilir. Node'da console.log yerine console.error, Python'da print(..., file=sys.stderr) ya da logging kullan. Araya giren tek bir print bağlantıyı bozar.

Tool açıklaması yetersiz

Model bir tool'u ne zaman çağıracağını açıklamasından çıkarır. "Görev ekle" yerine "Yeni bir görev ekler. due ISO tarih biçiminde; tags bir metin dizisi." gibi tam bir açıklama yaz ve her parametreye ayrı açıklama koy (.describe() ya da docstring).

Yetki sınırı çok geniş

Gerçek sistemlere bağlanan sunucularda en az yetki ilkesi kritik: salt okunur token, dar kapsamlı IAM rolü, yalnızca gereken uç noktalar. Modelin bir hatası canlı sistemde zarara dönüşmesin. Sunucunun okuduğu dış içerik prompt injection taşıyabilir; yazma yapan tool'ları buna göre tasarla.

Hataları yutmak

Bir disk ya da ağ işlemi hata verdiğinde bunu anlamlı bir metinle isError olarak döndür: "Görev bulunamadı: 12345" gibi. Sessizce çöken bir tool, modelin yanlış bir şey uydurmasına yol açar.

Oturuma güvenmek

2026-07-28'de protokol düzeyinde oturum yok; ardışık çağrıların aynı süreçte, aynı bağlantıda geleceğini varsayma. Çağrılar arasında durum gerekiyorsa (örneğin sayfalı bir arama), sunucunun ürettiği bir tanıtıcıyı tool sonucu olarak döndür ve sonraki çağrıda argüman olarak al. Yeni sunucuda Roots, Sampling ve Logging gibi deprecated özelliklere dayanma; dizinleri tool parametresi ya da yapılandırmayla al, log için stderr ya da OpenTelemetry kullan.

Transport seçimi

Yerel kullanım için stdio ile başla. Uzaktan erişim gerekiyorsa Streamable HTTP kullan (her mesaj tek bir uç noktaya HTTP POST); eski HTTP+SSE transport'u deprecated. Uzak sunucu açtığında kimlik doğrulama (spesifikasyonun OAuth tabanlı yetkilendirme bölümü) artık senin sorumluluğun.

Eşzamanlı çağrı güvenliği

Asistan tek mesajda birden fazla tool çağırabilir. Örneğimizdeki "dosyayı oku, değiştir, yaz" akışı aynı anda iki yazma gelirse birini kaybedebilir; gerçek kullanımda dosya kilidi ya da SQLite gibi bir veritabanı kullan.

Yayınlama ve dağıtma

Sunucun çalışıyorsa paketleyip paylaşabilirsin:

  • npm / PyPI: TypeScript'te package.json'a bin alanı ekle ki npx tasks-mcp çalışsın; Python'da bir konsol betiği tanımla ki uvx tasks-mcp çalışsın.
  • MCP Registry: resmî kayıt defteri registry.modelcontextprotocol.io. Kayıt bir pull request ile değil, mcp-publisher aracıyla yapılıyor: mcp-publisher init bir server.json üretir, mcp-publisher login github ile giriş yapıp mcp-publisher publish ile yayımlarsın. npm paketlerinde sahiplik doğrulaması için package.json'a server.json'daki adla aynı bir mcpName alanı (GitHub girişiyle io.github.kullanici-adin/... biçiminde) eklemen gerekiyor. Depo README'sindeki son durum notuna göre Registry API'si Ekim 2025'ten beri v0.1'de dondurulmuş durumda.
  • README: kurulumu, gereken ortam değişkenlerini ve örnek yapılandırmayı yaz.
  • Kurum içi: hassas iş mantığı içeriyorsa özel npm/PyPI deposunda yayımla.

Yaygın senaryo fikirleri

Aynı iskeleti farklı veri kaynaklarına uygulayarak pek çok sunucu çıkarabilirsin:

  • Kişisel notlar / wiki: yerel Markdown dosyalarını okuma ve arama.
  • Akıllı ev: ışıkları aç/kapat, sıcaklığı sor.
  • Müzik kütüphanesi: son dinlenenler, çalma listesine ekleme.
  • Harcama defteri: harcama ekle, kategoriye göre toplam.
  • Dijital arşiv: kitap/film/oyun takip listeleri.
  • İşe özel: CRM, ürün analitiği, içerik takvimi, ticket sistemi.

Devamı için

Kaynaklar

Sık sorulan sorular

MCP 2026-07-28 sürümünde ne değişti?

Protokol durumsuz hâle geldi: initialize el sıkışması ve Mcp-Session-Id oturumları kaldırıldı; her istek kendi protokol sürümünü ve istemci yeteneklerini _meta alanında taşıyor. Sunucuların server/discover çağrısını desteklemesi gerekiyor. Roots, Sampling ve Logging özellikleri ile eski HTTP+SSE transport'u deprecated.

Eski (2025) MCP istemcileri yeni sunucumla çalışır mı?

Resmi SDK'larla evet. TypeScript SDK v2'nin serveStdio fonksiyonu ve Python SDK 2.x, aynı sunucudan hem 2026-07-28 hem de initialize el sıkışması kullanan 2025 dönemi istemcilerine cevap veriyor. Bu rehberdeki iki sunucu her iki dönemle de test edildi.

@modelcontextprotocol/sdk paketi hâlâ kullanılabilir mi?

v1 hattı (1.x) yayımlanmaya devam ediyor ama en yeni protokol sürümü olarak 2025-11-25'i biliyor. 2026-07-28 için TypeScript SDK v2'nin @modelcontextprotocol/server ve @modelcontextprotocol/client paketleri kullanılıyor.

Claude Code MCP sunucu ayarlarını nerede tutar?

Claude Code'un belgelerine göre local ve user kapsamındaki sunucular ~/.claude.json dosyasında, project kapsamındakiler proje kökündeki .mcp.json dosyasında tutulur. En kolay yol claude mcp add komutudur.

MCP sunucumu nerede yayımlarım?

Paketi npm veya PyPI'a koyduktan sonra resmi MCP Registry'ye mcp-publisher aracıyla server.json üzerinden kaydedebilirsin. npm paketlerinde sahiplik doğrulaması için package.json'a mcpName alanı eklemek gerekiyor.