Claude Code MCP yapılandırması: .mcp.json, kapsamlar ve sorun giderme

.mcp.json biçimi

Biri uzak biri yerel iki sunucu içeren bir proje dosyası şöyle görünür:

{
  "mcpServers": {
    "hosttracker": {
      "type": "http",
      "url": "https://mcp.host-tracker.com/mcp"
    },
    "local-tool": {
      "type": "stdio",
      "command": "/path/to/executable",
      "args": ["--flag", "value"],
      "env": { "KEY": "value" },
      "timeout": 600000
    }
  }
}

type alanı, url mevcut olduğunda zorunludur. type olmadan bir url, bir yapılandırma hatası olarak bildirilir (mesaj size "type": "http", veya sse ya da ws eklemenizi söyler), ki bu eksik bir command hakkındaki daha eski ve çok daha az yardımcı olan bir şikayetin yerini almıştır. streamable-http değeri, http için bir takma ad olarak kabul edilir. Sabit bir kimlik bilgisine ihtiyaç duyan uzak bir sunucu bir headers nesnesi alır; yerel bir sunucu ise command, args ve env alır. İsteğe bağlı timeout, milisaniye cinsinden araç çağrısı başına bir sınırdır. WebSocket sunucuları yalnızca bir dosyada veya claude mcp add-json aracılığıyla tanımlanabilir; --transport bayrağı ws değerini kabul etmez.

--scope project ile claude mcp add komutu bu dosyayı sizin için yazar, bu yüzden elle düzenleme yalnızca komutun ortaya koymadığı alanlar için veya değişikliği bir pull request'te incelemeyi tercih ettiğinizde gereklidir.

Sırları dosyanın dışında tutmak

.mcp.json commit edilmek üzere tasarlandığından, token'lar içine yazılmamalıdır. Claude Code, command, args, env, url ve headers içindeki ortam değişkenlerini genişletir: ${VAR} değişkenin değerini alır, ve ${VAR:-default} ayarlanmadığında varsayılana döner.

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

Ayarlanmamış ve varsayılanı olmayan başvurulan bir değişken, sunucunun yüklenmesini durdurmaz; ${API_KEY} metni olduğu gibi gönderilir, ve claude mcp list bir uyarı yazdırır. Bir sunucu bağlanır ama her çağrı yetkisiz olarak reddedilirse bakılacak ilk şey bu uyarıdır.

OAuth'u destekleyen bir sunucu için gizlenecek hiçbir şey yoktur: girdiyi yalnızca type ve url olarak bırakın, ve her kullanıcı /mcp üzerinden bir kez oturum açar. Token, depo dışında kullanıcı başına saklanır, ve claude mcp remove ile yeniden kaldırılır.

Onay, öncelik ve yönetilen sunucular

Claude Code bir proje .mcp.json dosyasında bir sunucuyu ilk gördüğünde, etkileşimli bir oturum onu kullanıp kullanmayacağını sorar; etkileşimli olmayan çalıştırmalar (claude -p, Agent SDK, bulut oturumları) onu sormadan yükler. Karar proje başına hatırlanır; claude mcp reset-project-choices onu unutur, böylece bir değişiklikten sonra yeniden onaylayabilirsiniz.

Bir isim birden fazla yerde tanımlandığında sıra şöyledir: yerel kapsam, sonra proje kapsamı, sonra kullanıcı kapsamı, sonra eklentilerin sağladığı sunucular, sonra claude.ai'den gelen bağlayıcılar. Kazanan girdinin tamamı kullanılır. Kuruluşlar, yönetilen bir yapılandırma dosyası veya managedMcpServers ayarı (Claude Code 2.1.259 veya sonrası) aracılığıyla sabit bir sunucu listesi zorunlu kılabilir; bunlar her kullanıcı seviyesi kapsamın üzerinde sıralanır, ve münhasır denetim iddia eden yönetilen bir dosya, claude mcp add komutunun kurumsal yapılandırmanın etkin olduğunu söyleyen bir mesajla reddetmesine yol açar. İzin ve red listeleri (allowedMcpServers, deniedMcpServers) kullanıcıların hangi URL'leri veya komutları ekleyebileceğini de kısıtlayabilir, ve bir red her zaman kazanır.

Durum çıktısını okumak

claude mcp list her sunucuyu bağlı, kimlik doğrulaması gerektiriyor, bağlanamadı, onay bekliyor, disabledMcpjsonServers aracılığıyla reddedildi, veya bu proje için devre dışı olarak bildirir. Yazdırdığı, bilinmesi değerli birkaç daha az belirgin uyarı vardır: bir değerde gizli baştaki veya sondaki boşluk (bir satır sonuyla biten yapıştırılmış bir token), aynı ismin iki kapsamda farklı uç noktalara işaret etmesi, ve kendi sunucularınız için kullanılamayan bir avuç ayrılmış isim. WebSocket sunucuları listede hiç görünmez; bunları claude mcp get <name> veya /mcp ile kontrol edin.

Yaygın hatalar ve düzeltmeleri

1. Uzak bir sunucu "kimlik doğrulaması gerekiyor" gösterir veya 401 ya da 403 yanıtı verir. /mcp açın, sunucuyu seçin ve tarayıcıda oturum açmayı tamamlayın, veya claude mcp login <name> çalıştırın. Sunucu statik bir token kullanıyorsa, başlık değerini ve genişletilmemiş değişkenler hakkındaki uyarıyı kontrol edin.
2. Yerel bir sunucu başlangıçta bağlanamıyor. Gerçek hatayı görmek için komutunu aynı kabukta elle çalıştırın; yaygın nedenler eksik bir çalışma zamanı, kurulması gereken bir paket, veya gerekli bir ortam değişkenidir. Yavaş başlayan sunucular başlangıç sınırına takılır, ki bunu MCP_TIMEOUT milisaniye cinsinden yükseltir, örneğin MCP_TIMEOUT=10000 claude.
3. Sunucu bağlanıyor ama bir araç kırpılmış bir sonuç döndürüyor. Araç çıktısı varsayılan olarak 25.000 token'la sınırlıdır, 10.000'den itibaren bir uyarıyla; MAX_MCP_OUTPUT_TOKENS sınırı yükseltir.
4. Araçlar sohbette eksik görünüyor. Claude Code, bağlamı küçük tutmak için araç tanımlarını ihtiyaç duyulana kadar erteler, bu yüzden başlangıçta yalnızca isimler ve sunucu talimatları yüklenir; bir istek eşleştiğinde asistan onları yine de bulur. Bir sunucunun tam tanımlarının ilk turdan itibaren mevcut olmasını istiyorsanız, o sunucu girdisinde "alwaysLoad": true ayarlayın.
5. Uzak bir sunucu oturum ortasında düşüyor. Claude Code, kopan bir bağlantıyı artan gecikmelerle beş kez, ve başarısız bir ilk HTTP bağlantısını üç kez yeniden dener, ama kimlik doğrulama hataları için ve yerel sunucular için değil, bu yüzden bir kimlik doğrulama hatası kendi kendine düzelmez.

Yapılandırmayı canlı bir servise karşı test etmek

Bir projenin .mcp.json dosyasını doğrulamanın en hızlı yolu, yanıtlarını bağımsız olarak kontrol edebileceğiniz bir sunucudur. { "type": "http", "url": "https://mcp.host-tracker.com/mcp" } commit edilmiş ve her geliştirici /mcp üzerinden bir kez oturum açmışken, "staging URL'imizde Avrupa ve Asya'dan bir HTTP kontrolü çalıştır" gibi bir istek HostTracker'ın kontrol noktalarından gerçek durum kodları ve yanıt süreleriyle dönmek zorundadır, ki bu ya dosyanın doğru okunduğunu kanıtlar ya da hatayı oturum açmaya daraltır. Eşlik eden rehber, Claude Code'a bir MCP sunucusu nasıl eklenir, komut satırı yolunu ve kapsamları daha ayrıntılı ele alır.