MCP Sunucuları

MCP (Model Context Protocol), Anthropic’in Claude’u harici araçlar ve veri kaynaklarıyla genişletmek için geliştirdiği standarttır. Bunu Claude için bir plugin sistemi olarak düşünebilirsiniz — CLI’ı veritabanlarına, tarayıcılara, API’lere ve özel dahili servislere Claude’un kendisini değiştirmeden bağlar.

Buna kimin ihtiyacı var: Claude’un veritabanlarını sorgulamasını, API’lere erişmesini, bulut depolamayı okumasını veya 60 yerleşik CLI aracının ötesinde araçlar kullanmasını istiyorsanız MCP sunucularına ihtiyacınız var. Yerleşik Read, Write, Bash ve Grep araçları iş akışınızı karşılıyorsa MCP’ye ihtiyacınız yok.

Sunucular; araçları, kaynakları ve prompt’ları dışa açar. Claude bunları oturum başlangıcında keşfeder ve talep üzerine kullanır. Bu bölüm taşıma protokollerini, yapılandırmayı, hata ayıklamayı ve harici yetenekleri bağlamanın getirdiği performans ödünleşimlerini kapsar.

Üç Taşıma Protokolü

MCP sunucuları Claude ile üç taşıma mekanizmasından biri aracılığıyla iletişim kurar. Doğru seçim, sunucunun nerede çalıştığına ve nasıl yönetildiğine bağlıdır.

Çoğu yerel geliştirme için stdio varsayılandır ve doğru seçimdir. Sunucu süreci oturum başladığında başlar ve sona erdiğinde kapanır. MCP sunucusu paylaşımlı veritabanı proxy’si veya ekip çapında araç sunucusu gibi uzun süre çalışan bir uzak servis olduğunda SSE veya streamable-http kullanın.

Satır İçi Yapılandırma

MCP sunucu tanımlarını --mcp-config ve bir JSON dizesiyle doğrudan komut satırında geçirin. Yapılandırma dosyası gerekmez.

Claude, dosya sistemi MCP sunucusunu alt süreç olarak başlatır, MCP protokol el sıkışması aracılığıyla araçlarını keşfeder, prompt’u yerine getirmek için kullanır ve oturum sona erdiğinde sunucuyu kapatır. Satır içi JSON, dosya tabanlı yapılandırmayla aynı mcpServers şemasını takip eder.

--mcp-config’e ham JSON yerine bir dosya yolu da verebilirsiniz:

claude -p "Query the database" --mcp-config ./mcp-config.json

Dosya Tabanlı Yapılandırma

Tekrarlanabilir kurulumlar için sunucuları bir JSON yapılandırma dosyasında tanımlayın. Bu aynı zamanda proje kökündeki .mcp.json (Claude tarafından otomatik keşfedilir) ve kullanıcı düzeyinde araçlar için ~/.claude/settings.json tarafından kullanılan formattır.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-filesystem", "/home/user/projects"],
      "env": {}
    },
    "database": {
      "command": "python",
      "args": ["-m", "mcp_server_postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost/mydb"
      }
    },
    "remote-tools": {
      "url": "http://internal-tools.company.com:3000/sse"
    }
  }
}

Her sunucu ya bir command (stdio için) ya da bir url (SSE / streamable-http için) belirtir. İsteğe bağlı env nesnesi, sunucu sürecine ortam değişkenleri geçirir — prompt’larda sabit kodlamak istemediğiniz gizli anahtarlar için kullanışlıdır.

MCP sunucuları beş farklı kapsamda tanımlanabilir ve çalışma zamanında birleştirilir. Aynı sunucu adı birden fazla kapsamda göründüğünde, daha spesifik kapsam kazanır.

Öncelik sırası: CLI > Yerel > Proje > Kullanıcı > Yönetilen.

Katı MCP Yapılandırması

--strict-mcp-config bayrağının iki kullanımı vardır: bir sunucu bağlanamazsa hemen hata vermek ve MCP izolasyonu — dizin ağacındaki tüm .mcp.json dosyalarını görmezden gelmek.

# İzolasyon: yalnızca bu belirli yapılandırmadaki sunucuları yükle
claude -p "Run audit" \
  --strict-mcp-config \
  --mcp-config ./my-servers.json

--mcp-config olmadan kullanıldığında, tüm MCP sunucularını tamamen kaldırır. --mcp-config ile kullanıldığında, yalnızca açıkça belirtilen yapılandırmayı yükler. Bu, üst MCP sunucularının kalıtımından kaçınması gereken monorepo’lardaki alt klasör oturumları için önemlidir.

CI/CD için kritik: --strict-mcp-config, MCP hatalarını sessizce görmezden gelmek yerine açık hale getirir. Otomatik ardışık düzenlerde, eksik bir veritabanı sunucusu derlemeyi başarısız kılmalı, düşük yeteneklerle devam etmemelidir. CI/CD kalıpları için Bölüm 13’e (Agent İş Akışları) bakın.

ToolSearch: Ertelenmiş Yükleme

Çok sayıda MCP sunucusu etkinken, araç açıklamaları bağlam penceresinin önemli bir kısmını tüketebilir. Claude, MCP araç açıklamaları bağlam penceresinin yaklaşık %10’unu aştığında otomatik olarak ToolSearch’ü etkinleştirir. Bu yapılandırılabilir değildir — otomatiktir.

Ertelenmiş yükleme nasıl çalışır:

1. Araç isimleri init olayında listelenir, ancak tam şemalar önceden yüklenMEZ
2. Claude isimleri görür ve araçların var olduğunu bilir
3. Claude belirli bir araca ihtiyaç duyduğunda, tam şemayı almak için ToolSearch’ü çağırır
4. Ancak o zaman şema bağlama yüklenir

Ertelenmiş yükleme olmadan, ayrıntılı şemalara sahip 80 MCP aracı yaklaşık 40K token bağlam tüketebilir. ToolSearch ile bu yük, bir araç gerçekten ihtiyaç duyulana kadar yaklaşık 2K token’a düşer. Ödünleşim, oturum sırasında kullanılan her benzersiz MCP aracı başına bir ekstra tur-gidiş-dönüştür.

Bir oturumda ertelenmiş araçları görebilirsiniz — <available-deferred-tools> bloğunda yalnızca isimle, parametre veya açıklama olmadan listelenir:

{
  "name": "mcp__chrome-devtools__take_screenshot",
  "deferred": true
}

Claude araca ihtiyaç duyduğunda, önce tam şemayı alır:

{
  "type": "tool_use",
  "name": "ToolSearch",
  "input": {
    "query": "select:mcp__chrome-devtools__take_screenshot",
    "max_results": 1
  }
}

Init Olayı: MCP Sunucu Durumu

--output-format stream-json kullanırken, init olayı her MCP sunucusunun bağlantı durumunu raporlar. Tüm beklenen sunucuların sağlıklı olduğunu doğrulamak için bunu otomasyonda ayrıştırın.

Her sunucu "status": "connected" veya "status": "error" gösterir. Otomasyonda, devam etmeden önce tüm beklenen sunucuların başarıyla başlatıldığını doğrulamak için bu init olayını kontrol edin:

claude -p "List tools" \
  --output-format stream-json \
  --verbose \
  --mcp-config ./mcp.json | head -1 | jq '.mcp_servers'

MCP Bağlantı Hatalarını Ayıklama

Bir MCP sunucusu bağlanamadığında, şu adımlarla ilerleyin:

Sunucu ikili dosyasını doğrudan test edin:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}' \
  | npx -y @anthropic-ai/mcp-server-filesystem /tmp

Bu askıda kalır veya hata verirse, sunucunun kendisi bozuktur — sorun Claude’da değildir.

Yaygın MCP hataları:

• Sunucu ikili dosyası bulunamadı: PATH’i kontrol edin. npx ilk çalıştırmada indirir (yavaş, zaman aşımına uğrayabilir).
• JSON ayrıştırma hataları: .mcp.json’ı jq < .mcp.json ile doğrulayın. Sondaki virgüller JSON’ı bozar.
• İzin reddedildi: Dosya sahipliğini kontrol edin. Yerel ikili dosyalar için chmod +x kullanın.
• Bağlantı reddedildi: SSE/streamable-http sunucuları için port çakışması.
• Eksik ortam değişkenleri: Yapılandırmanızdaki env nesnesini kontrol edin.
• Devre dışı bırakma geçersiz kılması: ~/.claude.json içindeki disabledMcpServers sunucuları sessizce engeller.

Günlükleri kontrol edin: MCP sunucu stderr’i ~/.claude/logs/mcp-<server-name>.log dosyasında yakalanır. Hata raporu göndermeden önce bunu okuyun.

MCP Araç Adlandırma ve Filtreleme

MCP araçları katı bir adlandırma kalıbı izler: mcp__<sunucu-adı>__<araç-adı>. Bu kural --disallowedTools ile araç filtreleme için önemlidir:

# Tek bir MCP aracını engelle
claude -p "..." --disallowedTools "mcp__chrome-devtools__click"

# Bir MCP sunucusunun tüm araçlarını engelle (glob kalıbı)
claude -p "..." --disallowedTools "mcp__chrome-devtools__*"

Performans Sınırları

MCP sunucuları güçlüdür ancak gerçek maliyetleri vardır. Bu kısıtlamaları aklınızda tutun.

Veri yoğun MCP araçları için çıktı sınırını artırmak istiyorsanız:

MAX_MCP_OUTPUT_TOKENS=50000 claude -p "Fetch large dataset" --mcp-config ./mcp.json

Claude’u MCP Sunucusu Olarak Kullanma

claude mcp serve komutu normal ilişkiyi tersine çevirir — Claude MCP araçlarını tüketmek yerine, diğer istemciler Claude’u araç olarak tüketir. Bu, Claude-Claude zincirleme ve meta-agent mimarilerini mümkün kılar.

Sunucu yalnızca stdio taşıma protokolü kullanır. Başka bir Claude örneğinin MCP yapılandırmasında alt süreç olarak yapılandırın:

{
  "mcpServers": {
    "claude-worker": {
      "command": "claude",
      "args": ["mcp", "serve"]
    }
  }
}

Bu, bir koordinatör Claude’un bir işçi Claude’u araç olarak çağırmasına olanak tanır. İşçi kendi bağlam penceresi, araç seti ve izinleriyle çalışır — doğal bir izolasyon sınırı oluşturur. Yerleşik Agent(type) aracından farklı olarak, claude mcp serve iç içe geçirmeye izin verir (derinlik sınırı yoktur) ve ayrı süreçler kullanır.

MCP Hata Modları

MCP sunucuları sinsi ve tehlikeli şekillerde başarısız olabilir:

Belirsiz takılmalar: Bir MCP sunucusu yanıt vermez hale geldiğinde, Claude’un takılma algılaması yoktur. Oturumlar herhangi bir zaman aşımı veya hata mesajı olmadan 16+ saat takılı kalabilir.

60 saniyelik kesin zaman aşımı: MCP_TIMEOUT yapılandırılabilir olsa da, 60 saniyeden uzun değerler sessizce görmezden gelinir. Sabit kodlanmış yaklaşık 60 saniyelik bir sınır vardır. MCP araçlarını 30 saniye içinde yanıt verecek şekilde tasarlayın.

Sessiz sunucu hataları: Varsayılan olarak, bozuk bir MCP sunucusu başlangıçta sessizce atlanır. Sessiz hataları kesin hatalara dönüştürmek için --strict-mcp-config kullanın.

IDE senkronizasyon boşluğu: CLI aracılığıyla eklenen MCP sunucuları VS Code eklentisiyle senkronize olmaz ve tersi de geçerlidir. Ayrı sunucu listeleri tutarlar.