MCP (Model Context Protocol) ile Yapay Zeka Ajanı Geliştirme Rehberi

Hızla gelişen yapay zeka dünyasında, Büyük Dil Modelleri (LLM'ler); muhakeme yapma, kod yazma ve karmaşık problemleri çözme konusunda kendilerini kanıtladılar. Ancak, yerel dosyalara, veritabanlarına, API'lere ve geliştirici araçlarına güvenli bir şekilde erişmek için standartlaştırılmış bir protokole sahip değillerdi.

Bu kopukluğu gidermek için Anthropic, Model Context Protocol (MCP) standardını duyurdu. Bu açık kaynaklı protokol, yapay zeka modellerinin dış veri kaynakları ve araçlarla (tools) güvenli ve yapılandırılmış bir şekilde iletişim kurmasını sağlar.

Yapay zeka entegrasyonu ve otomasyon süreçlerinde aktif çalışan bir Senior Full Stack Architect olarak, çeşitli otomasyon süreçlerinde MCP sunucularını yaygın olarak kullanmaktayım. Bu makalede, kendi ilk MCP sunucunuzu sıfırdan TypeScript ile nasıl kuracağınızı adım adım anlatacağım.

[!IMPORTANT] Özet Yanıt: Anthropic Agent SDK ve MCP Birlikte Nasıl Çalışır? Anthropic Model Context Protocol (MCP), Stdio veya SSE taşıma katmanı üzerinden çalışan açık bir RPC standardıdır. Anthropic Agent SDK (@anthropic-ai/sdk) ile birleştiğinde; LLM harici araçları tipli JSON şemalarıyla otomatik keşfeder, yapılandırılmış mesaj protokolüyle yürütür ve izin sınırları içinde güvenle sonuç üretir.

---

1. MCP Mimarisi Nasıl Çalışır?

MCP, yapay zeka ana uygulaması (Host) ile veri/araç kaynağı arasında bir istemci-sunucu (Client-Server) ilişkisi kurar:

• Host (Ev Sahibi - örn. Claude Desktop, Cursor veya Özel AI Ajanı): LLM'in çalıştığı ve hangi araçları tetikleyeceğine karar verdiği ana uygulama.
• Client (İstemci): Host içinde çalışan ve sunucuya bağlantıyı (genellikle standart girdi/çıktı - stdio veya SSE aracılığıyla) başlatan katman.
• Server (Sunucu): Yerel makinede veya bulutta çalışan, kaynakları, araçları ve hazır şablonları (prompts) istemciye sunan hafif bir uygulama.

graph LR
    Host[AI Host / Masaüstü İstemcisi] <--> Client[MCP İstemcisi]
    Client <-->|Stdio/SSE Protokolü| Server[MCP Sunucusu]
    Server <--> Filesystem[(Yerel Dosyalar)]
    Server <--> Database[(Veritabanları)]
    Server <--> APIs[Harici API'ler]

---

2. Temel Kavramlar: Kaynaklar, Araçlar ve Şablonlar

Bir MCP sunucusu geliştirirken yapay zeka modellerine üç temel yetenek sunarsınız:

1. Resources (Kaynaklar): Yapay zekanın referans alabileceği salt okunur veri kaynakları (veritabanı tabloları, sistem logları veya dosya içerikleri).
2. Tools (Araçlar): Yapay zekanın tetikleyebileceği çalıştırılabilir fonksiyonlar (dosya yazma, veritabanı sorgusu yapma veya API isteği atma). Araçlar genellikle kullanıcı onayı gerektirir.
3. Prompts (Şablonlar): Yapay zekanın rolünü, davranışını veya girdi formatını yönlendiren önceden yapılandırılmış prompt şablonları.

---

3. TypeScript ile Adım Adım MCP Sunucusu Yapımı

Geliştireceğimiz örnek sunucuda, yapay zeka ajanının yerel bilgisayarınızın CPU ve bellek durumunu sorgulayabileceği dinamik bir araç oluşturacağız.

Adım 1: Projeyi Başlatma

Yeni bir dizin oluşturup gerekli bağımlılıkları yükleyelim:

mkdir my-mcp-server
cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk
npm install -D typescript @types/node tsx
npx tsc --init

Adım 2: Sunucu Kodunu Yazma

Bir index.ts dosyası oluşturup aşağıdaki kodları ekleyin:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import os from "os";

// Sunucuyu Tanımla
const server = new Server(
  {
    name: "system-monitor-mcp",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

// Kullanılabilir Araçları Kaydet
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "get_system_metrics",
        description: "Bilgisayarın gerçek zamanlı CPU, RAM kullanımı ve çalışma süresi (uptime) bilgilerini döndürür.",
        inputSchema: {
          type: "object",
          properties: {},
        },
      },
    ],
  };
});

// Araç Çalıştırıldığında Tetiklenecek Mantık
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name } = request.params;

  if (name === "get_system_metrics") {
    const freeMem = os.freemem();
    const totalMem = os.totalmem();
    const usagePercent = ((totalMem - freeMem) / totalMem) * 100;

    const metrics = {
      platform: os.platform(),
      arch: os.arch(),
      uptimeSeconds: os.uptime(),
      cpuCount: os.cpus().length,
      memoryUsagePercentage: usagePercent.toFixed(2) + "%",
      freeMemoryGB: (freeMem / 1024 / 1024 / 1024).toFixed(2) + " GB",
    };

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(metrics, null, 2),
        },
      ],
    };
  }

  throw new Error(`Tool ${name} bulunamadı.`);
});

// Sunucuyu stdio ile Başlat
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("System Monitor MCP Sunucusu stdio üzerinde çalışıyor");
}

main().catch((err) => {
  console.error("Kritik hata:", err);
  process.exit(1);
});

---

4. MCP Sunucusunu Claude Desktop'a Bağlama

Yazdığınız bu sunucuyu Claude Desktop üzerinde test etmek için Claude yapılandırma dosyasını düzenlemeniz gerekir.

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Aşağıdaki yapılandırmayı ekleyin:

{
  "mcpServers": {
    "system-monitor": {
      "command": "npx",
      "args": [
        "-y",
        "tsx",
        "C:/dosya-yolunuz/my-mcp-server/index.ts"
      ]
    }
  }
}

Claude Desktop uygulamasını yeniden başlattığınızda, sağ altta bir çekiç simgesi göreceksiniz. Bu, yapay zekanın yerel aracınıza başarıyla eriştiğini gösterir.

---

5. Güvenlik ve Üretim (Production) Tavsiyeleri

MCP sunucularını uzak sunucularda veya ekipler genelinde yayına alırken dikkat edilmesi gerekenler:

• Strict Sandboxing (Sıkı Yalıtım): Yapay zekaya komut satırı yetkisi verirken komutları mutlaka filtreleyin ve doğrudan çalıştırılmasına izin vermeyin.
• Güvenli Kimlik Doğrulama: Bulut sunuculardaki MCP entegrasyonlarında stdio yerine Server-Sent Events (SSE) kullanarak araya OAuth2 veya API anahtarları gibi güvenlik katmanları ekleyin.
• Minimum Yetki İlkesi: MCP sunucusunun çalıştığı yerel işletim sistemi kullanıcısının yetkilerini olabildiğince kısıtlayın.

---

Sıkça Sorulan Sorular (FAQ)

Anthropic Agent SDK ile Model Context Protocol kullanmanın avantajı nedir?

Anthropic Agent SDK ile MCP'nin birlikte kullanımı, LLM mantığı ile yerel araç yürütmesini birbirinden tamamen ayırır. Ajan standart JSON şemaları alarak hangi aracı çalıştıracağını kendi başına belirlerken, izole ve tipli bir ortamda güvenle işlem yapar.

Model Context Protocol sunucuları yetkisiz erişimlere karşı nasıl korunur?

MCP sunucularını korumak için Zod ile tüm istemci girdileri doğrulanmalı, doğrudan kabuk (shell) komutu çalıştırılmamalı, yerel dosya sistemi erişimi beyaz listeye alınan dizinlerle sınırlandırılmalı ve Server-Sent Events (SSE) yayınlarında Bearer token doğrulaması zorunlu tutulmalıdır.

Bir MCP sunucusu aynı anda birden fazla yapay zeka istemcisine hizmet verebilir mi?

Evet. Server-Sent Events (SSE) veya HTTP akışı ile çalışan uzak MCP sunucuları; Claude Desktop, Cursor IDE ve özel otonom ajanlardan gelen eşzamanlı bağlantılara oturum bazlı taşıma izolasyonu ile hizmet verebilir.

---

Sonuç

Model Context Protocol (MCP), statik LLM mantığı ile aktif sistem yürütme süreçleri arasındaki köprüdür. Araçları standart şemalarla tanımlayarak, yapay zeka modellerini tam teşekküllü asistanlara dönüştürebiliriz.

Geliştirici Ömer Özbay'ın portföy vitrini olan gucluyumhe.dev adresinde de uyguladığı üzere; MCP yapılarından faydalanmak, güvenli ve esnek bir yerel otomasyon döngüsü kurmanızı sağlayarak yazılım geliştirme üretkenliğinizi üst seviyeye taşır.