MCP Server Geliştirme: Anthropic MCP Implementation 2026

MCP server geliştirme, Anthropic’in Kasım 2024’te açık yayımladığı Model Context Protocol üzerinde LLM uygulamalarını araç ve veri kaynaklarına bağlayan sunucu bileşenleri inşa etmek demektir. 2026 itibarıyla MCP; OpenAI Agents SDK, Microsoft Copilot Studio ve Google Gemini ekosisteminde native desteklenen de facto tool-integration protokolüdür. Doğru tasarlanmış bir MCP server, ajan iş akışlarında her entegrasyon için ayrı tool wrapper yazma zorunluluğunu kaldırarak geliştirme süresini tipik kurumsal projelerde %40-60 kısaltır.

Bu rehber protokol spesifikasyonu, transport seçimi, capability negotiation ve production deployment’ı uçtan uca ele alır; Python ve TypeScript SDK örnekleri, OAuth 2.1 katmanı ve 2025-06-18 protocol revision baz alınmıştır.

Model Context Protocol Nedir ve Neden 2026’da Standart Oldu?

Model Context Protocol, LLM uygulamaları (host) ile bağlam sağlayıcılar (server) arasında JSON-RPC 2.0 üzerinden çalışan açık bir uygulama katmanı protokolüdür. Anthropic’in USB-C benzetmesinde olduğu gibi, MCP de Claude, GPT, Gemini gibi modelleri Slack, GitHub, Postgres, Notion ve şirket içi sistemlerle tek arabirimde buluşturur. Spec üç primitive üzerine kuruludur: resources (okuma için bağlam veri kaynakları), tools (yan etki üretebilen fonksiyon çağrıları), prompts (parametrik prompt şablonları).

2025 boyunca benimsenme hızı yüksekti: OpenAI Mart’ta Agents SDK’sında, Microsoft Mayıs’ta Copilot Studio’da, Google Gemini 2.5 sürümünde MCP desteği duyurdu. Bu çok satıcılı destek, MCP’yi proprietary tool-calling formatlarının üzerinde bir portability katmanına dönüştürdü.

Ekosistem aktörü	MCP desteği başlangıç	İstemci tarafı	Sunucu tarafı SDK
Anthropic Claude Desktop	Kasım 2024	Native	Python, TypeScript, Java, C#, Kotlin, Swift
OpenAI Agents SDK	Mart 2025	Native (Agents framework)	Resmi destek (Python)
Microsoft Copilot Studio	Mayıs 2025	Native + Azure AI Foundry	.NET resmi SDK
Google Gemini	Haziran 2025	Resmi MCP istemcisi	Gen AI SDK entegrasyonu
Cursor / Windsurf / Cline	2025 Q1-Q2	IDE-side native	Topluluk SDK’ları
LangChain / LlamaIndex	2025 Q2	Adapter	Resmi adapter paketi

MCP’nin function calling ve tool use mekanizmalarından farkı, model bağımsız wire-format ve capability negotiation sunmasıdır. Function calling vendor-spesifik JSON şeması üzerinde çalışırken MCP, initialize aşamasında yetenek negotiate eder — bu, geriye uyumlu protokol evrimi için temel tasarım kararıdır.

MCP Mimarisi: Host, Client ve Server Rolleri

MCP mimarisi üç bileşenli topolojiye dayanır. Host, kullanıcı etkileşimini yöneten ana uygulamadır (Claude Desktop, VS Code Copilot, custom agent runtime). Client, host içinde her sunucu için ayrı instance olarak çalışan, 1:1 bağlantıyı yöneten bileşendir. Server, resources/tools/prompts sağlayan bağımsız süreçtir. Host birden fazla server’a paralel bağlanabilir, her bağlantı izole client instance üzerinden yürür ve güvenlik sınırı buradan geçer.

Tipik kurumsal senaryoda host bir kurumsal chatbottur; aynı host Postgres, Jira ve internal docs vektör DB’sine bağlı üç ayrı sunucuyu paralel kullanır. Bu modüler yapı, granular izin yönetimini mümkün kılar.

• Resources: URI ile tanımlanmış, salt okunur veri kaynakları (ör. file:///docs/policy.md, postgres://schema/users). LLM context’ine eklenmek üzere host tarafından çekilir.
• Tools: Yan etki üretebilen, model tarafından çağrılabilen fonksiyonlar. JSON Schema ile parametre tanımı, idempotency hint’leri, destructive flag’i içerir.
• Prompts: Parametrik olarak yeniden kullanılabilen prompt şablonları. Slash command şeklinde kullanıcıya sunulabilir.
• Sampling: Sunucunun host’tan LLM completion isteyebildiği ters yönlü mekanizma — agent-of-agents desenleri için.
• Roots: Server’ın hangi dosya sistemi köklerine erişebileceğini tanımlayan istemci tarafı kısıt.

Transport Katmanı: stdio, HTTP+SSE ve Streamable HTTP

İlk mimari karar transport seçimidir. stdio transport, server’ı child process olarak başlatıp stdin/stdout üzerinden JSON-RPC taşır; tipik <1 ms IPC latency ve sıfır network overhead sunar, yalnızca aynı makinedeki host senaryolarında kullanılır. Claude Desktop ve Cursor’ın varsayılan transport’udur.

Streamable HTTP (2025-03-26 spec), HTTP POST + opsiyonel SSE yanıt akışı modelinde çalışır. Tek /mcp endpoint’inde hem JSON-RPC hem session taşır; load balancer arkasında scale eder, OAuth 2.1 ile korunur ve serverless platformlarda (Cloudflare Workers, Lambda) deploy edilir.

Transport	Latency	Network	Auth desteği	Tipik kullanım	Scaling profili
stdio	<1 ms (IPC)	Yok (local pipe)	Process izolasyonu	Local IDE, desktop client	1:1, process per server
HTTP+SSE (legacy)	5-50 ms	HTTP/1.1	Bearer token	Eski sunucular (deprecated)	Ayrı endpoint çiftleri
Streamable HTTP	3-30 ms	HTTP/1.1 veya 2	OAuth 2.1, mTLS	Production, remote server	Stateless veya session-bound
WebSocket (proposal)	2-10 ms	WS upgrade	WS subprotocol	Düşük-latency stream	Persistent connection

Session yönetimi Mcp-Session-Id header’ı ile yapılır. Sunucu initialize‘da session ID üretir; client sonraki isteklerde header’ı geri gönderir. Stateless deployment’larda (Lambda) session state Redis/DynamoDB’de tutulur; Anthropic’in cloudflare-mcp şablonu Durable Objects’i referans desen olarak sunar.

Python ile MCP Server Geliştirme: Minimum Implementasyon

Resmi mcp Python paketi, FastMCP yüksek seviye dekoratör API’si ile düşük seviye protokol API’sini birlikte sunar. Aşağıdaki örnek bir Postgres okuma sunucusunun iskeletini gösterir.

from mcp.server.fastmcp import FastMCP
import asyncpg

mcp = FastMCP("postgres-readonly", version="1.0.0")

@mcp.tool(description="Run a read-only SQL query against the analytics DB")
async def query(sql: str, limit: int = 100) -> list[dict]:
    if not sql.strip().lower().startswith("select"):
        raise ValueError("Only SELECT statements are permitted")
    conn = await asyncpg.connect(DSN)
    rows = await conn.fetch(f"{sql} LIMIT {limit}")
    await conn.close()
    return [dict(r) for r in rows]

@mcp.resource("postgres://schema/{table}")
async def get_schema(table: str) -> str:
    # Returns DDL text for the requested table
    ...

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

Örnekte üç tasarım kararı kritik: SELECT-only kısıtı SQL injection ve destructive operation riskini azaltır (AST doğrulaması için SQLGlot önerilir); limit varsayılanı context window’u korur; asyncpg seçimi event loop’u bloklamaz. FastMCP, Python type hint’lerinden otomatik JSON Schema üretir; Annotated ve Field ile parametre açıklaması eklemek LLM’in doğru tool çağrısı için kritiktir — Anthropic tool-use metriklerine göre açıklamasız tool’larda yanlış argüman oranı %22’ye çıkarken, açıklamalı tool’larda %4 civarındadır.

TypeScript ile Production MCP Server: Streamable HTTP Örneği

TypeScript SDK (@modelcontextprotocol/sdk) Cloudflare Workers, Vercel Functions ve Node.js servislerinde yaygındır. Aşağıdaki örnek, Streamable HTTP ile bir GitHub okuma sunucusunun production iskeletini gösterir.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from
  "@modelcontextprotocol/sdk/server/streamableHttp.js";
import express from "express";
import { z } from "zod";

const server = new McpServer({ name: "github-reader", version: "1.0.0" });

server.tool(
  "list_issues",
  "List open issues for a repo",
  { owner: z.string(), repo: z.string(), limit: z.number().default(20) },
  async ({ owner, repo, limit }) => {
    const res = await fetch(
      `https://api.github.com/repos/${owner}/${repo}/issues?per_page=${limit}`,
      { headers: { Authorization: `Bearer ${process.env.GH_TOKEN}` } }
    );
    return { content: [{ type: "text", text: await res.text() }] };
  }
);

const app = express();
app.use(express.json());
app.post("/mcp", async (req, res) => {
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: () => crypto.randomUUID(),
  });
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});
app.listen(3000);

• Avantaj: Type-safe parameter validation Zod schema ile derleme aşamasında yakalanır; runtime hataları azalır.
• Avantaj: Streamable HTTP, Cloudflare Workers ve Vercel Edge gibi serverless platformlarda doğrudan çalışır.
• Dezavantaj: stdio transport’a kıyasla 3-30 ms ek latency vardır; düşük gecikme isteyen local agent senaryoları için uygun değildir.
• Ne zaman seç: Birden fazla kullanıcı/ajan tek sunucuya bağlanacaksa, sunucu kurumsal kaynaklara dış ağdan erişiyorsa, OAuth 2.1 gerekiyorsa.
• Üretim notu: express.json() yerine body parser limitini açıkça set et (örn. 1 MB); büyük payload DoS vektörü olabilir.

Capability Negotiation, Sampling ve Elicitation Akışları

Protokol evrimini güvenli kılan mekanizma capability negotiation‘dur. initialize isteğinde client yeteneklerini deklare eder (sampling, roots/listChanged); server kendi yeteneklerini döner (tools/listChanged, resources/subscribe, prompts). Her iki taraf yalnızca karşı tarafın deklare ettiği yeteneklere istek gönderebilir — bu eski client/server’ların yeni özelliklerde patlamasını önler.

Sampling, sunucunun host üzerinden LLM completion talep edebildiği ters yönlü mekanizmadır. Örneğin code-review server’ı diff analizinde host’a sampling isteği gönderir; host kendi LLM’ini (Claude, GPT) kullanır ve sonucu döner. Bu desen agentic AI iş akışlarında orkestrasyon katmanlarında sıkça başvurulur. Sunucu istediği modeli zorlayamaz, sadece preference (hints, cost/speed priority) bildirebilir.

Elicitation (2025-06-18 spec), sunucunun çalışma sırasında kullanıcıdan ek bilgi (eksik parametre, onay, seçim) talep edebilmesidir. Önceki spec’te tool çağrısı atomikti; yeni akış çok adımlı kullanıcı etkileşimini protokol seviyesinde tanımlar — AI agent tasarım pattern’leri içindeki human-in-the-loop deseninin standardize edilmiş hali.

Güvenlik: OAuth 2.1, Prompt Injection ve Tool Poisoning

Güvenlik, opsiyonel katman değil temel tasarım sorumluluğudur. Remote MCP sunucuları için spec OAuth 2.1 + PKCE’yi authorization standardı kabul eder; sunucu authorization server rolünü kendisi üstlenebilir veya harici IdP’ye (Okta, Auth0, Microsoft Entra) delege edebilir. 2025’te Dynamic Client Registration (RFC 7591) yaygınlaştı; host’lar zero-touch onboarding yapabiliyor.

İkincil vektör prompt injection ve tool poisoning‘dir. Resource’tan dönen metin (e-posta, GitHub issue) LLM’e zararlı talimat enjekte edebilir. ENISA’nın 2025 Threat Landscape raporu, MCP bağlamında tool poisoning’i kurumsal LLM dağıtımlarındaki top-5 tehdit arasında listeledi. Korunma için LLM hallucination azaltma rehberindeki grounding teknikleri, sunucu input sanitization, destructive flag ve client tarafında human-in-the-loop onay birlikte uygulanmalıdır.

Tehdit vektörü	Etki	Olabilirlik (2026)	Korunma katmanı
Tool poisoning (resource içeriği)	Yetkisiz tool çağrısı, veri sızıntısı	Yüksek	Input sanitization, content provenance, output filtering
Confused deputy (token relay)	Server, client yetkisini başka servise relay eder	Orta	Audience-restricted token, OAuth resource indicators (RFC 8707)
Excessive scope	Geniş izinli token kötüye kullanım	Yüksek	Least-privilege scope, granular consent UI
Supply chain (3rd-party server)	Kötü amaçlı server kurulumu	Yüksek	Signed manifests, server allowlist, sandboxing
Session hijacking (Streamable HTTP)	Başkasının session’ında tool çağırma	Düşük-Orta	Session ID rotation, secure cookies, TLS pinning
Rate / cost abuse	Pahalı tool spam ile bütçe tüketme	Orta	Token bucket, per-tool quota, budget alarms

OAuth 2.1 kurulumunda Resource Indicators (RFC 8707) kritiktir. Token, hangi resource server için kullanılacağını belirtmelidir; aksi halde sunucu token’ı başka API’ye relay ederek confused deputy saldırısı yapabilir. NIST’in 2025 AI Risk Management Framework profili audience-restricted token’ı zorunlu kontrol olarak işaretledi.

Performans, Quota ve Maliyet Optimizasyonu

MCP server’lar modelin token bütçesini doğrudan etkiler; performans yalnızca latency değil context payload boyutu üzerinden değerlendirilir. tools/list her tool için 200-500 token harcar; 50 tool’lu sunucuda istek başına ~15K token ek context oluşur. Bu yüzden Anthropic, dinamik tool filtering ve tools/listChanged ile lazy loading desenini önerir.

Cost optimizasyonunda üç pratik öne çıkar: RAG altyapısı entegrasyonunda resource yanıtlarını summarize ederek döndürmek; tool yanıtlarına cacheable hint eklemek; sampling kullanan server’larda maxTokens ve stopSequences set ederek runaway completion’ı önlemek.

Optimizasyon	Tipik tasarruf	Karmaşıklık	Ne zaman uygula
Dinamik tool filtreleme (listChanged)	%30-60 prompt token	Orta	50+ tool’lu sunucular
Resource summarization	%40-80 context token	Düşük	Log, e-posta, uzun doküman kaynakları
Cacheable tool yanıtları	%20-50 latency + tekrar maliyeti	Düşük	Idempotent GET tool’lar
Streamable HTTP keep-alive	%15-25 latency	Düşük	Yüksek RPS senaryoları
Connection pooling (DB, HTTP)	%30-50 p95 latency	Orta	Her tool çağrısında yeni connection açan server’lar
Tool result truncation + pagination	%40-70 token	Orta	Liste döndüren tool’lar (issues, logs, rows)

Production’da p95 latency hedefi tool karmaşıklığına göre belirlenir. Anthropic referans benchmark’larında basit read-only Postgres tool’ları 50 ms p95, GitHub API tool’ları 250-400 ms p95, dosya sistemi grep tool’ları 80-150 ms p95 aralığında çalışır. Bu aralıkların dışı agent loop’unda algılanır gecikme yaratır.

Test, Observability ve MCP Inspector Kullanımı

MCP server geliştirme, geleneksel API test’inden farklı bir piramit gerektirir. MCP Inspector, Anthropic’in resmi geliştirme aracıdır — web UI üzerinden sunucuya bağlanır, tool’ları manuel çağırır, JSON-RPC akışını inceler (npx @modelcontextprotocol/inspector node ./build/index.js). Tool şeması, hata kodu ve resource subscribe doğrulaması için ilk savunma hattıdır.

Otomatik test stratejisi üç katmanlıdır: unit test’ler tool fonksiyon mantığını izole test eder; integration test’ler server’ı in-process başlatıp client API üzerinden çağrıları doğrular; eval test’leri gerçek LLM ile end-to-end tool seçimini ölçer. Benzer mantık RAG evaluation framework’lerinde uygulanır — MCP context’inde tool selection accuracy, parameter correctness ve cost-per-task metrikleriyle ölçülür.

1. Tool selection accuracy: Verilen kullanıcı niyetinde modelin doğru tool’u seçme oranı (hedef ≥%92).
2. Parameter correctness: Seçilen tool’a doğru parametrelerle çağrı yapma oranı (hedef ≥%88).
3. Task completion rate: Çok adımlı görevde başarılı tamamlama oranı (hedef ≥%75).
4. Cost per successful task: Bir görev için harcanan tipik token + tool çağrı sayısı.
5. Tool error rate: Tool çağrılarında 5xx benzeri hatalar; ≤%2 hedef.
6. p95 latency: Tool çağrı süresinin %95’inci yüzdeliği; SLO sınırı.

Observability tarafında OpenTelemetry MCP semantic conventions taslağı 2025’te yayımlandı. Her tool çağrı span’ı mcp.tool.name, mcp.session.id, mcp.transport, mcp.request.method attribute’larıyla zenginleştirilir. Datadog, Honeycomb ve Grafana Cloud 2026 başında MCP-aware dashboard şablonları yayımladı.

Deployment: stdio’dan Cloudflare Workers ve Kubernetes’e

Deployment seçimi kullanıcı profiline bağlıdır. Single-user local senaryoda sunucu stdio transport ile çalışır; paketleme uvx (Python) veya npx (Node) ile yapılır. Çok kullanıcılı kurumsal senaryoda Streamable HTTP üzerinde remote deployment zorunludur — Cloudflare Workers, Lambda + API Gateway, Vercel Functions veya Kubernetes.

Cloudflare Workers + Durable Objects deseninde region başına 50 ms altı p50 latency ve yatay scale avantajı vardır; ancak 30 sn CPU ve 128 MB memory limiti uzun süren tool’lar için kısıttır. Lambda’da 15 dakika çalışma süresi mümkündür ama cold start (200-500 ms) düşük gecikme senaryolarında zorludur — provisioned concurrency veya SnapStart önerilir.

Kubernetes’te her server’ı ayrı Deployment + Service + Ingress ile expose etmek yerine MCP Gateway deseni 2025 ikinci yarısında yaygınlaştı. Tek gateway pod’u path-based routing ile birden fazla upstream server’a yönlendirir; OAuth, rate limit ve audit logging gateway’de merkezileşir. Kurumsal yapay zeka entegrasyonu projelerinde bu desen AI gateway katmanının doğal parçasıdır.

Deployment hedefi	Tipik p50 latency	Max çalışma süresi	Cold start	Tipik maliyet (1M tool çağrısı)
Cloudflare Workers + DO	30-60 ms	30 sn CPU	~5 ms	~$5-15
AWS Lambda + API GW	80-200 ms	15 dk	200-500 ms	~$10-30
Vercel Functions (Edge)	40-80 ms	30 sn	~20 ms	~$10-25
Kubernetes (managed)	10-50 ms	Sınırsız	0 (always-on)	Sabit pod maliyeti
Fly.io / Railway	20-70 ms	Sınırsız	~50 ms (auto-stop)	~$5-20 küçük workload

Versiyon yönetimi, deployment’ın gizli karmaşıklığıdır. Protokol revision (2025-06-18) ve sunucu uygulama versiyonu ayrı kavramlardır; client initialize‘da protokol versiyonunu deklare eder, server en yüksek ortak versiyonu seçer. Production’da en az iki revision’ı paralel desteklemek (current + previous) zero-downtime upgrade için pratiktir.

Gerçek Dünya Örnek: Postgres + Vektör DB + GitHub Birleşik Server

Ömer Önal olarak son altı ayda kurumsal danışmanlık projelerinde kurduğumuz birleşik MCP server’lar, tek sunucuda Postgres okuma, vektör veritabanı retrieval ve GitHub metadata sorgusunu birleştirir. Avantajı agent’ın aynı session’da kaynakları join edebilmesi; dezavantajı granular izin sınırlarının zorlaşması — production’da hibrit yaklaşım önerilir: destructive tool’lar ayrı server, salt okunur join’ler birleşik.

Tipik akış: kullanıcı “son sprintte kapanmamış issue’larla ilgili commit’leri ve etkilenen müşteri segment’ini özetle” diye sorar. Agent GitHub tool’u ile open issues çeker, commit’leri sorgular, vektör DB’de internal docs bulur, Postgres’te müşteri ID listesini çeker ve birleşik özet üretir. Bu zincir AI destekli veri analitiği akışlarına doğrudan entegre olur.

• Kazanım: Geliştirme süresinde 3-4 hafta tasarrufu (her tool için ayrı integration framework yazmaya kıyasla).
• Kazanım: Operasyonel maliyet — tek deployment hattı, tek observability dashboard, tek auth katmanı.
• Risk: Tek sunucu büyürken cognitive complexity artar; 30+ tool sonrası split önerilir.
• Risk: Granular izin yönetimi MCP capability seviyesinde değil tool seviyesinde gerekir — server tarafında ayrı RBAC katmanı eklenmelidir.
• Ne zaman seç: Veri kaynakları arasında sık join gerektiren agent senaryoları, tek ekip sahipliği, paylaşılan auth provider varlığı.

Sıkça Sorulan Sorular

Sonuç

MCP server geliştirme, 2026’da artık opsiyonel bir teknik beceri değil — kurumsal LLM altyapısı kuran her ekibin temel kompetansıdır. Doğru transport seçimi (lokal için stdio, production için Streamable HTTP), sıkı capability negotiation, OAuth 2.1 tabanlı güvenlik ve OpenTelemetry üzerinden observability kuran ekipler, agent tabanlı iş akışlarını öngörülebilir maliyet ve operasyonel risk profiliyle ölçeklendirebiliyor. Tek sunucu içinde çok kaynak birleştirmek hızlı kazanım sağlasa da granular izin sınırı gerektiren senaryolarda hibrit topoloji önerilir.

Karar çerçevesinde önce kullanım profilini netleştir: tek kullanıcı + lokal mi, çok kullanıcı + remote mu? Transport ve auth bu cevaptan çıkar. Ardından primitive haritası — hangi tool, hangi resource, hangi prompt? Son olarak observability ve eval pipeline’ı sunucu canlıya alınmadan kurulmalı; geriye dönük metric eklemek hata bütçesini aşar.

Kurumsal MCP server geliştirme, mimari karar yoğunluğu yüksek bir alandır. Pilot ya da production projende destek istersen iletişim sayfasından ulaş; transport seçiminden eval framework’üne kadar uçtan uca çalışırım.

Dış kaynaklar ve referanslar: MCP Spec 2025-06-18 · GitHub modelcontextprotocol/servers · Anthropic MCP duyurusu · Microsoft Copilot Studio MCP · ENISA Threat Landscape 2025 · RFC 8707 Resource Indicators · OpenTelemetry GenAI semantic conventions