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:
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/initializedel sıkışması kalktı. Her istek kendi protokol sürümünü ve istemci yeteneklerini_metaalanında taşıyor (io.modelcontextprotocol/protocolVersion,io.modelcontextprotocol/clientCapabilities). - Oturum yok. Streamable HTTP'deki
Mcp-Session-Idbaş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/discoverzorunlu. Sunucu desteklediği sürümleri, yetenekleri ve kimliğini bu çağrıyla bildiriyor.- Sunucudan istemciye istek yok.
sampling/createMessage,elicitation/creategibi sunucunun başlattığı istekler yerine Multi Round-Trip Requests geldi: sunucuresultType: "input_required"ile ek bilgi istiyor, istemci isteği bu bilgiyle yeniden gönderiyor. Her sonuçta artıkresultTypealanı var. - Değişiklik bildirimleri tek bir
subscriptions/listenakışında toplandı;pingvelogging/setLevelkaldı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/nodetsconfig.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.jsTerminal sessiz bekler; bu normal, sunucu stdin'den mesaj bekliyor. Kodun ana parçaları:
registerToolher 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.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.isError: trueiş mantığı hatasını (görev bulunamadı) protokol hatasından ayırır; model mesajı okuyup kullanıcıya düzgün aktarır.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 mcptasks_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.pyFarklar:
- Ş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 destructuredContentalanında veriyor. ToolErrorfırlatmak, sonucuisError: trueolarak 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=denemeTool 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.jsClaude Code'un belgelerine göre local ve user kapsamı
~/.claude.jsondosyasında, project kapsamı (ekiple paylaşılan) proje kökündeki.mcp.jsondosyasında tutuluyor..mcp.jsoniç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 damcppaketinin 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çinversionNegotiation: { 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'abinalanı ekle kinpx tasks-mcpçalışsın; Python'da bir konsol betiği tanımla kiuvx tasks-mcpçalışsın. - MCP Registry: resmî kayıt defteri
registry.modelcontextprotocol.io. Kayıt bir pull request ile değil,mcp-publisheraracıyla yapılıyor:mcp-publisher initbirserver.jsonüretir,mcp-publisher login githubile giriş yapıpmcp-publisher publishile yayımlarsın. npm paketlerinde sahiplik doğrulaması içinpackage.json'aserver.json'daki adla aynı birmcpNamealanı (GitHub girişiyleio.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
- MCP — protokolün kavramı.
- MCP Server Kataloğu — yazmadan önce hazırı var mı diye bak.
- Ajan protokolleri haritası — MCP, A2A ve ödeme protokolleri hangi katmanda.
- Claude Skills Rehberi — skill'ler ve MCP birlikte nasıl çalışır.
- Function Calling — MCP'nin altında yatan tool çağırma davranışı.
Kaynaklar
- MCP spesifikasyonu 2026-07-28 — Key Changes
- MCP spesifikasyonu — Versioning and Compatibility
- MCP TypeScript SDK ve v2 belgeleri
- MCP Python SDK
- MCP Inspector
- MCP Registry
- Claude Code — MCP
- Yerel MCP sunucularına bağlanma (Claude Desktop)
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.