İçeriğe geç
Ömer Tiryaki (Ana sayfa)
← Tüm notlar

Rehberkontrol edildi

MCP sunucusu bağlama

Claude’u Model Context Protocol ile kendi verilerinize ve araçlarınıza güvenli ve adım adım nasıl bağlayacağınız.

MCP nedir

MCP, yapay zekâ asistanlarının araçları ve verileri kullanmasını sağlayan açık bir standarttır. Bir MCP sunucusu dosya okuma, e-posta arama veya görev oluşturma gibi işlevler sunar. Claude bunları soruya uygun olduğunda çağırır. Üç rol vardır: Host, örneğin Claude Code gibi yapay zekâ uygulamasıdır. Host her sunucu için bağlantıyı tutan ayrı bir client oluşturur; sunucu ise araçları sağlayan programdır. Bir sunucu üç tür yapı taşı sunabilir:

  1. Tools: bir şey yapan işlevler; örneğin bir veritabanını sorgulamak veya bir API çağırmak.
  2. Resources: okunacak veriler; örneğin bir dosyanın içeriği veya bir veritabanı şeması.
  3. Prompts: tekrar eden görevler için hazır şablonlar.

İpucu:Basit bir benzetme: MCP standart bir priz gibidir. Uygun fişe sahip her araç, MCP konuşan her uygulamada çalışır; her eşleşme için ayrı kablo gerekmez.

Yerel mi uzak mı: aktarım yöntemleri

Aktarım yöntemi, client ile sunucunun mesajları nasıl değiştireceğini belirler. Mesajların kendisi her zaman aynıdır: JSON-RPC 2.0. stdio’da host, sunucuyu bilgisayarınızda bir program olarak başlatır ve onunla standart girdi ve standart çıktı üzerinden konuşur. Bu hızlıdır ve ağ gerektirmez. Streamable HTTP’de sunucu ağda bir yerde çalışır, bir URL üzerinden erişilir ve aynı anda birçok client’a hizmet verebilir.

İpucu:Eski kılavuzlarda hâlâ SSE aktarımı geçer. SSE artık kullanımdan kalkmıştır; uzak sunucular için Streamable HTTP kullanın.

Gereksinimler

Birçok hazır sunucu npx ile başlatıldığı için neredeyse her zaman Node.js gerekir. Bir şey eklemeden önce terminalde sürümleri kısaca kontrol edin.

  1. Güncel sürümde Claude Code veya Claude masaüstü uygulaması.
  2. npx ile başlayan sunucular için LTS sürümünde Node.js.
  3. TypeScript SDK ile kendi sunucunuz için: Node.js 20 veya üzeri.
  4. Uzak sunucular için: URL ve gerekiyorsa sağlayıcıda bir hesap.
node --version
npx --version

Claude Code’a ekleme

Claude yerel sunucuları bir program olarak başlatır, uzak sunuculara ise bir URL üzerinden ulaşır. Yerel sunucularda iki tire (--) Claude’un seçeneklerini sunucunun başlatma komutundan ayırır. Bu ayraç olmadan Claude, --port gibi sunucu seçeneklerini kendi seçeneği sanar. Anahtarları -e ile ortam değişkeni olarak, uzak sunucularda ise --header ile verin.

# yerel: bir klasördeki dosyalar
claude mcp add dosyalar -- npx -y @modelcontextprotocol/server-filesystem ~/Documents

# yerel, anahtar ortam değişkeni olarak
claude mcp add -e API_KEY=ANAHTARINIZ --transport stdio servisim -- npx -y @ornek/mcp-server

# uzak: bir URL üzerinden
claude mcp add --transport http sunucum https://example.com/mcp

# uzak, token header içinde
claude mcp add --transport http sunucum https://example.com/mcp --header "Authorization: Bearer TOKENINIZ"

İpucu:-e ile sunucu adı arasına --transport stdio gibi başka bir seçenek koyun. Aksi hâlde Claude adı başka bir anahtar-değer çifti olarak okur.

Kapsamlar ve ekip için .mcp.json

Kapsam (scope), bir sunucunun nerede geçerli olduğunu ve kimin gördüğünü belirler. Bir şey belirtmezseniz local kapsamına girer: yalnızca sizin için ve yalnızca bu projede. --scope user ile tüm projelerinizde kullanılabilir. Claude ikisini de ~/.claude.json dosyasında saklar. --scope project ile Claude sunucuyu proje klasöründeki .mcp.json dosyasına yazar; tüm ekibin aynı sunucuyu kullanması için bu dosyayı repoya eklersiniz.

{
  "mcpServers": {
    "team-api": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

İpucu:.mcp.json içinde ${VARIABLE} yazabilirsiniz; varsayılan değerle ${VARIABLE:-deger} şeklinde de olur. Böylece gerçek anahtar asla repoya girmez, herkes onu yerel olarak tanımlar. Claude Code bir .mcp.json dosyasındaki sunucuları kullanmadan önce bir kez onayınızı ister.

Claude masaüstü uygulamasında

Masaüstü uygulaması yerel sunucuları claude_desktop_config.json dosyasından okur. Dosya macOS’ta ~/Library/Application Support/Claude/ içinde, Windows’ta %APPDATA%\Claude\ içinde bulunur. mcpServers altındaki her kaydın bir adı, bir komutu (command) ve bu komutun argümanları (args) vardır.

  1. Uygulamada ayarları açın, solda “Developer” bölümünü seçin ve “Edit Config” düğmesine tıklayın.
  2. Sunucuyu mcpServers altına ekleyin ve dosyayı kaydedin.
  3. Uygulamadan tamamen çıkın ve yeniden başlatın. Pencereyi kapatmak yetmez.
  4. Giriş alanındaki “Connectors” bölümünde sunucunun ve araçlarının göründüğünü kontrol edin.
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/name/Documents"]
    }
  }
}

Dikkat:Yolları göreli değil, tam ve mutlak olarak yazın. Sunucu sizin kullanıcı yetkilerinizle çalışır ve paylaşılan klasörlerde sizin yapabildiğiniz her şeyi yapabilir.

Kontrol ve yönetim

Açık bir oturumda /mcp hangi sunucuların bağlı olduğunu ve hangi araçları sunduğunu gösterir. OAuth isteyen uzak sunuculara da buradan giriş yaparsınız: Claude tarayıcıyı açar, token’ı saklar ve kendisi yeniler. Terminalde üç komut işinize yarar.

claude mcp list             # tüm sunucular ve durumları
claude mcp get dosyalar     # tek bir sunucunun ayrıntıları
claude mcp remove dosyalar  # sunucuyu kaldır

İpucu:Claude Code’da bir sunucunun araçları mcp__sunucu__arac biçiminde adlandırılır. İzinlerde onlara bu adla tek tek izin verir veya engellersiniz.

Güvenli kalmak

Bir MCP sunucusu ona izin verdiğiniz her şeyi yapabilir. Yerel sunucular sizin kullanıcı yetkilerinizle çalışır, uzak sunucular Claude’un onlara gönderdiği tüm verileri görür. Bu yüzden birkaç sabit kural geçerlidir.

  1. Yalnızca güvenilir kaynaklardan sunucu kurun ve koda kısaca göz atın.
  2. Mümkün olduğunca az yetki: yalnızca gereken klasörü paylaşın.
  3. Anahtarları ve token’ları ortam değişkeni olarak verin, asla koda yazmayın.
  4. Bir şey değiştiren veya gönderen araçlarda her işlem için onay isteyin.
  5. Web sayfası, e-posta veya destek talebi gibi dış içerik yükleyen sunucularda prompt injection olasılığını hesaba katın.

Dikkat:Prompt injection, yüklenen verilerdeki bir metnin Claude’a talimat vermeye çalışması demektir. Bu yüzden dış metinleri okuyan bir sunucuyu, onaysız gönderen veya silen bir sunucuyla asla kontrolsüz birleştirmeyin.

Kendi sunucunuzu yazmak

Resmî TypeScript SDK ile her aracı bir ad, açıklama ve girdi şemasıyla tanımlarsınız. Şema, kodunuz çalışmadan önce girdileri doğrular ve aynı zamanda Claude’a hangi alanları doldurması gerektiğini söyler. Açıklama önemlidir, çünkü Claude aracı ne zaman kullanacağına buna göre karar verir. Life OS’umu Claude’a böyle bağladım: görevler, randevular ve belgeler doğrudan sohbette erişilebilir. Eski örnekler hâlâ 1. sürümdeki @modelcontextprotocol/sdk paketini kullanır.

  1. Bir proje oluşturun ve ES modülü olarak işaretleyin, çünkü SDK yalnızca ES modülleri sunar.
  2. SDK, zod ve tsx’i kurun. tsx, TypeScript’i derleme adımı olmadan çalıştırır.
  3. Sunucuyu src/index.ts içine yazın ve npx tsx src/index.ts ile başlatın.
  4. Dosyanın tam yolunu kullanarak Claude Code’a ekleyin.
npm init -y
npm pkg set type=module
npm install @modelcontextprotocol/server zod tsx

// src/index.ts
import { McpServer } from '@modelcontextprotocol/server';
import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
import * as z from 'zod/v4';

const server = new McpServer({ name: 'selam-sunucusu', version: '1.0.0' });

server.registerTool(
  'selamla',
  {
    description: 'Bir kişiyi adıyla selamlar',
    inputSchema: z.object({ name: z.string() }),
  },
  async ({ name }) => ({
    content: [{ type: 'text', text: `Merhaba, ${name}!` }],
  }),
);

async function main() {
  await server.connect(new StdioServerTransport());
}
main();

# ekleyin
claude mcp add selam -- npx tsx /tam/yol/src/index.ts

Dikkat:stdio’da standart çıktı protokol kanalıdır. Tek bir console.log bile mesajları bozar. Bu yüzden her zaman stderr’e yazan console.error ile log tutun.

MCP Inspector ile test

Bir sunucuyu Claude’a eklemeden önce en iyisi onu MCP Inspector ile test etmektir. Inspector, sunucunuzu başlatan ve her aracı elle çağırmanızı sağlayan yerel bir web arayüzüdür. Böylece arada bir model olmadan şemanın, girdilerin ve yanıtların doğru olup olmadığını hemen görürsünüz.

npx @modelcontextprotocol/inspector npx tsx src/index.ts

İpucu:Inspector, başkalarının yazdıkları da dahil her stdio sunucusuyla çalışır. Böylece bir sunucuyu eklemeden önce gerçekte hangi araçları getirdiğini kontrol edersiniz.

Uzakta çalıştırmak

Bir sunucuya birden fazla cihazdan veya birden fazla kişi tarafından erişilmesi gerekiyorsa, Streamable HTTP üzerinden uzakta çalışır. Cloudflare Workers bunun için uygundur: Cloudflare, sunucuyu /mcp yolunda yayınlayan bir şablon sunar. Giriş olmadan URL’yi bilen herkes onu kullanabilir. Bu yüzden özel veriler için önüne bir kimlik doğrulama koyun. MCP bunun için OAuth önerir; Claude Code da /mcp üzerinden sizi girişte yönlendirir.

# girişsiz şablonu oluşturun
npm create cloudflare@latest -- remote-mcp-server-authless --template=cloudflare/ai/demos/remote-mcp-authless

# yerelde test: http://localhost:8788/mcp
npm start

# yayınlayın
npx wrangler@latest deploy

# Claude Code’a ekleyin
claude mcp add --transport http sunucum https://remote-mcp-server-authless.HESABINIZ.workers.dev/mcp

Dikkat:“authless” şablonunda giriş yoktur. Öğrenmek için kullanın, ancak OAuth veya başka bir koruma eklenmeden ona gerçek veri bağlamayın.

Sık görülen hatalar ve çözümleri

Sorunların çoğunun birkaç nedeni vardır. İyi bir ilk adım her zaman sunucunun başlatma komutunu terminalde kendiniz çalıştırmaktır. Orada çıkan hatalar Claude’da da başlamasını engeller.

  1. Sunucu başlamıyor: komutu terminalde deneyin ve node ile npx’in bulunduğunu kontrol edin.
  2. Yanlış yollar: yapılandırma dosyalarında her zaman mutlak yol kullanın.
  3. Eksik değişkenler: .mcp.json içindeki bir ${VARIABLE} tanımlı değilse claude mcp list uyarır.
  4. Bozuk JSON: Tek bir eksik virgül, masaüstü uygulamasının hiçbir sunucu yüklememesine yeter.
  5. Değişiklik etkili olmuyor: masaüstü uygulamasından tamamen çıkıp yeniden başlatın.
  6. Yavaş başlangıç: bekleme süresini artırın; örneğin on saniye için MCP_TIMEOUT=10000 claude.

İpucu:Masaüstü uygulaması logları macOS’ta ~/Library/Logs/Claude, Windows’ta %APPDATA%\Claude\logs klasörüne yazar. mcp-server-AD.log dosyasında ilgili sunucunun hata çıktısı bulunur.

Kısa kontrol listesi

Yeni bir sunucuyu kalıcı olarak kullanmadan önce bu maddeleri gözden geçirin.

  1. Kaynak kontrol edildi, kod veya dokümantasyon okundu.
  2. Yalnızca gerekli klasörler ve yetkiler paylaşıldı.
  3. Anahtarlar ortam değişkeni olarak tanımlandı, hiçbiri repoda değil.
  4. Uygun kapsam seçildi: local, project veya user.
  5. Inspector veya /mcp ile sunucunun ve araçların çalıştığı kontrol edildi.
  6. Yazma yapan araçlara yalnızca onayla izin verildi.

Diğer notlar

Gizlilik

İzleme çerezi yok

Burada hakkınızda hiçbir veri toplanmaz.

Tarayıcınızın hatırladıkları

Bunların hiçbiri analiz için kullanılmaz.

Gizlilik politikasını okuyun