Sorun Giderme

nexus-mcp'ye bağlanırken ters giden şeylerin çoğu üç ayrı hatadan kaynaklanır. Her birinin hat üzerinde kendine özgü bir biçimi vardır — bu sayfanın amacı, yanıt gelmeyen her durumu aynı kefeye koymak yerine bunları hızla birbirinden ayırmaktır.

Başarısız bir keşif çağrısı

tools/list (ve güncel dönemde server/discover ile komşu çağrılar) çalışan çalışma alanından canlı olarak yanıtlanır. Çalışan bir çalışma alanı yoksa ya da bağlanan sürecin ulaşabileceği canlı bir oturum yoksa, çağrı kapalı biçimde başarısız olur — önbelleğe alınmış bir kataloğa geri düşmez ve başarı kılığına sokulmuş boş bir sonuç döndürmez. Geri aldığınız şey, bir takılma değil, açık bir JSON-RPC hatasıdır:

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32603,
    "message": "No live NEXUS session credential"
  }
}

Yukarıda gösterilen tam ifade örnektir, garanti edilen bir sabit değildir — kararlı olan biçimdir: bağlantının takılması veya çağrının sessizce hiçbir şey döndürmesi yerine, hızlıca dönen standart bir JSON-RPC -32603 (Internal error). Bunu "bir çalışma alanı başlatın ve yeniden deneyin" olarak değerlendirin; bozuk bir istemcinin kanıtı olarak değil.

Desteklenmeyen bir protokol sürümü

Güncel dönemde _meta ile ya da eski dönemde initialize.params ile, supportedVersions içinde yer almayan bir protocolVersion bildirirseniz, istek başka hiçbir yanı incelenmeden reddedilir:

{
  "jsonrpc": "2.0",
  "id": 7,
  "error": {
    "code": -32022,
    "message": "Unsupported protocol version",
    "data": { "supported": ["2026-07-28", "2025-06-18"], "requested": "2024-11-05" }
  }
}

data.supported ve data.requested her zaman birlikte bulunur; böylece birden fazla MCP dönemini konuşabilen bir istemci, kendisinin de desteklediği bir sürümle yeniden deneyip denemeyeceğine programatik olarak karar verebilir. Bunun koruduğu anlaşma modeli için Protokol Dönemleri sayfasına bakın.

Yakından ilişkili bir hata: ayrılmış io.modelcontextprotocol/ ad alanını kullanan ama geçerli bir dize protocolVersion sağlamayan bir istek, tahmin edilmeye çalışılmak yerine hatalı biçimlendirilmiş kabul edilerek -32602 (Invalid params) ile reddedilir. Bu yükün tam hâli için MCP Protokolü sayfasına bakın — _meta bloğunu elle oluşturup istemci kimliğini veya yeteneklerini ayarlarken sürüm anahtarını unutursanız bu hataya kazara düşmek çok kolaydır.

Eksik veya süresi dolmuş bir oturum kimlik bilgisi

Bağlanan bir CLI, bir ortam değişkeni yerine oturuma özel bir kimlik bilgisi dosyası okur — bkz. Yollar ve Kimlik Bilgileri. Bu dosya normal çalışma sırasında yeniden yazılır ve oturum kapandığında silinir. Bu durumun hata olarak ortaya çıkmasının iki yolu vardır:

• Dosya bu süreç için hiç var olmamıştır (bu CLI hiçbir zaman canlı bir NEXUS oturumuna bağlanmamıştır).
• Dosya vardı ama işaret ettiği oturum o zamandan beri sona ermiştir ve yerine yenisi konmamıştır.

İkisi de aynı şekilde görünür: yerel olarak yanıtlanan el sıkışma yöntemleri dışındaki her çağrı, kısmi veya eskimiş bir yanıt yerine -32603 ile ve iletilecek canlı bir oturum olmadığını belirten bir mesajla başarısız olur. Kimlik bilgisine özel ayrı bir hata kodu yoktur — bakılması gereken işaret, hangi çağrıların başarısız olduğudur (canlı uygulamayı gerektiren her şey), hangilerinin olmadığı ise ayrı bir sorudur (initialize, server/discover ve yerel olarak yanıtlanan diğer yöntemler yanıt vermeye devam eder, çünkü bunların uygulamaya hiç ulaşması gerekmez).

Hızlı başvuru

Belirti	Kod	Ne anlama gelir
Her gerçek çağrı hemen başarısız oluyor, yalnızca el sıkışma yöntemleri çalışıyor	-32603	İletilecek canlı bir oturum yok — bir çalışma alanı oturumu başlatın veya yeniden bağlanın
Bağlantı, herhangi bir yöntem çalışmadan reddediliyor	-32022	Bildirilen protokol sürümü supportedVersions içinde değil
"Invalid params" ile reddediliyor	-32602	_meta, ayrılmış ad alanını geçerli bir protocolVersion olmadan kullandı
agent_trigger sonrasında süresiz takılıyor	(hata yok)	Beklenen davranış — bkz. Teslimat Semantiği; bu araç asla eşzamanlı yanıt vermez

Sonraki adımlar

• MCP Protokolü — eksiksiz hata kataloğu ve anlaşma sözleşmesi.
• Yollar ve Kimlik Bilgileri — kimlik bilgisi dosyasının konumu, adlandırması ve yaşam döngüsü.
• İstemci Bağlama — girdiyi en baştan doğru yapmak.