MCP Protokolü

NEXUS, makinenizde çalışan uygulamayı, kendini nexus-mcp olarak tanıtan yerel bir sunucu aracılığıyla MCP uyumlu her istemciye açar.

Kısa bilgiler

Sunucu adı	nexus-mcp
Taşıma	stdio
Mesaj çerçeveleme	satır sonuyla ayrılmış JSON-RPC 2.0 — satır başına bir mesaj, mesaj içinde satır sonu yok
Ağ portu	yok
supportedVersions	["2026-07-28", "2025-06-18"]
Keşif yöntemi	server/discover (yalnızca 2026-07-28 dönemi)

Taşıma

Sunucu, standart giriş ve çıkış üzerinden iletişim kurar. Her mesaj, tek bir satırda serileştirilmiş tek bir JSON-RPC 2.0 nesnesidir; bir mesaj asla içinde ham satır sonu barındırmaz. Sunucu hiçbir ağ portu açmaz — bağlanacak, güvenlik duvarına eklenecek veya dışarı açılacak bir şey yoktur. Sürecin standart çıkışa yazdığı her şey geçerli bir MCP mesajıdır; oraya başka hiçbir şey yazılmaz, dolayısıyla bir istemci stdout üzerindeki her satırı güvenle ayrıştırılabilir JSON-RPC olarak kabul edebilir.

Sürüm anlaşması

NEXUS'un MCP sunucusu iki protokol dönemini aynı anda destekler. Belirli bir isteğin hangi döneme ait olduğu, bağlantı başına değil, istek başına belirlenir:

	2026-07-28	2025-06-18
El sıkışma	yok — yerini server/discover alır	initialize / initialized, değişmeden
İstemci sürümünü nasıl bildirir	her istekte _meta["io.modelcontextprotocol/protocolVersion"]	initialize içinde params.protocolVersion
İstemci kimliği	_meta["io.modelcontextprotocol/clientInfo"], normalde mevcut	initialize içinde params.clientInfo
İstemci yetenekleri	_meta["io.modelcontextprotocol/clientCapabilities"], normalde mevcut	initialize içinde params.capabilities
tools/list sonucu	resultType, ttlMs, cacheScope ekler	düz MCP sonucu
tools/call sonucu	resultType ekler	düz MCP sonucu

Yönlendirme kuralı basittir ve her isteğe bağımsız olarak uygulanır: _meta geçerli bir dize değerinde io.modelcontextprotocol/protocolVersion taşıyorsa, istek 2026-07-28 sözleşmesine göre değerlendirilir. _meta böyle bir anahtar hiç taşımıyorsa, istek eski dönem (legacy) olarak karşılanır. Sunucunun hatırladığı, bağlantı genelinde geçerli bir "mod" yoktur — bir istemcinin bir dönem seçip orada kalması beklenir, ancak her istek, aynı bağlantıdaki önceki isteklerden bağımsız olarak kendi başına sınıflandırılır.

2026-07-28: el sıkışma yok, server/discover zorunlu

2026-07-28 istemcisi initialize çağırmaz. Bunun yerine, zorunlu olan server/discover çağrısını yapar; bu çağrı sunucunun desteklediği sürümleri, yeteneklerini, keşif sonucunun kendisi için önbellek davranışını ve sunucu kimliğini döndürür.

İstek:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "server/discover",
  "params": {},
  "_meta": {
    "io.modelcontextprotocol/protocolVersion": "2026-07-28",
    "io.modelcontextprotocol/clientInfo": { "name": "example-cli", "version": "1.4.0" },
    "io.modelcontextprotocol/clientCapabilities": {}
  }
}

Yanıt:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "server/discover",
    "supportedVersions": ["2026-07-28", "2025-06-18"],
    "capabilities": { "tools": {} },
    "ttlMs": 60000,
    "cacheScope": "session",
    "_meta": {
      "io.modelcontextprotocol/serverInfo": { "name": "nexus-mcp" }
    }
  }
}

resultType alanını, koda sabitlenecek bir değer olarak değil, dallanma için kullanılan opak bir ayırt edici olarak ele alın — bu örnek biçimi gösterir, garanti edilmiş bir sabiti değil. ttlMs ve cacheScope, keşif sonucunun kendisinin ne kadar süreyle ve hangi kapsamda önbelleğe alınabileceğini anlatır; başka hiçbir sonucun önbelleklenmesi hakkında bir şey söylemezler.

2025-06-18: initialize değişmeden çalışır

Eski dönem istemcisi standart MCP el sıkışmasını gerçekleştirir.

İstek:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": { "name": "example-cli", "version": "1.0.0" }
  }
}

Yanıt:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": { "tools": {} },
    "serverInfo": { "name": "nexus-mcp" }
  }
}

İstemci ardından, herhangi bir MCP sunucusunda olduğu gibi initialized bildirimini gönderir.

tools/list

tools/list, çalışan çalışma alanından canlı olarak karşılanır — hiçbir zaman önbelleğe alınmış veya bayatlamış bir katalog değildir. Bunun doğrudan bir sonucu vardır: çalışan bir çalışma alanı yoksa çağrı kapalı biçimde başarısız olur. Önceki bir kataloğa geri düşmez ve başarı kılığında boş bir liste döndürmez. Bu duruma karşılık gelen hata kodu kararlı sözleşmenin parçası değildir — belirli bir koda değil, "bu çağrı başarısız oldu" durumuna göre dallanın ve bunu bozuk bir istemcinin kanıtı olarak değil, bir çalışma alanı başlatıp yeniden denemek için bir işaret olarak değerlendirin.

2026-07-28 döneminde başarılı bir sonuç, standart tools dizisinin etrafına resultType, ttlMs ve cacheScope ekler:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "resultType": "tools/list",
    "ttlMs": 30000,
    "cacheScope": "workspace",
    "tools": [
      { "name": "canvas_get_state", "description": "[Local NEXUS app] Get a bounded summary (revision, role, element counts, labels) of one canvas.", "inputSchema": { "type": "object" } }
    ]
  }
}

tools dizisindeki her açıklama [Local NEXUS app] ile başlar ve aracın hangi düzlemde iş yaptığını bildirir. Nedeni için Araç Ad Alanları, ailelerin kendisi için MCP Araçları sayfasına bakın.

tools/call

2026-07-28 döneminde başarılı bir sonuç, standart MCP araç sonucu biçiminin etrafına resultType ekler:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "resultType": "tools/call",
    "content": [{ "type": "text", "text": "..." }],
    "isError": false
  }
}

Her aracın ne kabul ettiği ve ne döndürdüğü için MCP Araçları, tuvali değiştiren çağrıların uyduğu sonuç sözleşmesi için Tuval Rolleri sayfasına bakın.

Retler bir gerekçe kodu taşır

Anlaşılmış ve bilinçli olarak izin verilmemiş bir çağrı — hiç gerçekleştirilememiş bir çağrıdan farklı olarak — yine isError: true ile yanıtlanır, ancak gerekçenin cümleyi ayrıştırmadan okunabilmesi için bir structuredContent nesnesi ekler:

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "resultType": "tools/call",
    "content": [{ "type": "text", "text": "Orchestration denied: cross-agent orchestration is turned off in Settings." }],
    "structuredContent": {
      "allowed": false,
      "reason": "settingDisabled",
      "detail": "Orchestration denied: cross-agent orchestration is turned off in Settings."
    },
    "isError": true
  }
}

reason kararlıdır ve asla yerelleştirilmez; detail ise content ile aynı cümledir ve bir insan içindir. Tanınmayan bir reason değerini, gideremeyeceğiniz bir ret olarak değerlendirin ve yeniden denemek yerine detail içeriğini bildirin.

Bir yönetişim reddinin taşıyabileceği kodlar:

reason	Anlamı	Bunu ne değiştirir
notEntitled	Ajanlar arası orkestrasyon mevcut planda yok	Bunu içeren bir plan
settingDisabled	Yerel orkestrasyon ayarı kapalı	Ayarlar ▸ Ajanlar ▸ Orchestration
notOnAllowlist	Bu ajan yönetilen bir zincir başlatamaz	Ajanı izin listesine eklemek
depthExceeded	Zincir azami derinliğine ulaştı	Sınırı yükseltmek veya daha kısa bir zincir
breadthExceeded	Zincir azami ajan sayısına ulaştı	Sınırı yükseltmek veya daha az ajan
globallyStopped	Tümünü durdur devrede	Durdurmayı kaldırmak
awaitingApproval	Adım, bir kişinin yanıtlaması için bekletiliyor	Onaylayıp aynı çağrıyı yeniden denemek
refusedByUser	Bir kişi bu adımı reddetti	Otomatik bir şey yok — yanıt verilmiş
notQueued	Adım onaya sunulamadı	detail alanına bakın

structuredContent içermeyen düz bir isError: true ise diğer hata türüdür: hatalı biçimli bir argüman, bilinmeyen bir eş, devre dışı bir yetenek. Bunlar çağrı hakkındaki kararlar değil, çağrının kendisindeki kusurlardır.

Her kuralın neyi koruduğu ve gerekçelerin neden ayırt edilebilir tutulduğu için Orkestrasyon yönetişimi (EN) sayfasına bakın.

resources/list ve resources/read

Kaynaklar (resources), araçların salt okunur karşılığıdır: veri sunarlar, asla bir değişiklik yapmazlar. resources/list, çalışan çalışma alanının o an sunabildiği tüm kaynakları döndürür; resources/read bir uri alır ve içeriğini MCP'nin standart contents dizisi olarak döndürür.

Bugün üç kaynak ailesi mevcuttur:

• nexus://capabilities — yetenek kataloğu: her aracın adı, açıklaması ve (girilmişse) gerektirdiği yetenek, onay düzeyi, yan etkileri, geri alınabilirliği, uyumlu pencere türleri ve yeniden başlatma etkileri. Daha önce kullanmadığınız bir aracı çağırmadan önce bunu okuyun. Henüz kataloglanmamış bir araç capabilities: null bildirir — tahmin değil, dürüst bir "henüz kataloglanmadı".
• nexus://planes — bu sunucunun hangi düzlemde iş yaptığı ve hangisinde yapmadığı: neye eriştiği, tüm araçlarının açıklamasında taşıdığı önek ve birlikte kurulmuş bir Chainabit bulut sunucusunun ilgisiz bir hesaba ve ilgisiz bir çalışma alanı kimliğine eriştiğinin açık ifadesi. Her iki sunucu da bağlıysa bunu oturumun başında bir kez okuyun — bkz. NEXUS yerel MCP ile Chainabit bulut MCP.
• nexus://memory/{entryId} — paylaşılan bellekteki tek bir kayıt; görünürlüğü memory_get ile aynıdır: başka bir ajanın özel kaydı resources/list içinde hiç görünmez ve URI'si çözümlenmez.

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "resources/read",
  "params": { "uri": "nexus://capabilities" }
}

2026-07-28 döneminde buradaki sonuçlar yalnızca resultType ekler — ttlMs ve cacheScope yalnızca tools/list içindir (yukarıdaki tabloya bakın).

prompts/list ve prompts/get

İstemler (prompts), kullanıcının seçtiği iş akışlarıdır: bir ajanın kendi başına çağırmaya karar verdiği bir şey değil, istemcinin bir kişiye çalıştırması için sunabileceği adlandırılmış ve yeniden kullanılabilir bir betiktir. prompts/get bir name alır; bir description ile bir konuşmayı başlatmaya hazır bir messages dizisi döndürür.

Bildirimlere asla yanıt verilmez

Bir JSON-RPC bildirimi — yani id taşımayan bir mesaj — sunucu aksi hâlde hata döndürecek olsa bile hiçbir zaman yanıt almaz. Hatalı biçimlendirilmiş bir bildirim gönderirseniz size bunu söyleyen bir şey olmaz; bir bildirime yanıt beklemeyin.

Hatalar

Desteklenmeyen protokol sürümü — -32022

Bir istek, supportedVersions içinde bulunmayan bir protocolVersion bildirdiğinde döner — ister 2026-07-28 biçiminde _meta ile, ister eski biçimde initialize.params ile:

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

Hatalı biçimlendirilmiş _meta — -32602

_meta, io.modelcontextprotocol/ ad alanını kullandığında — yani bu önek altında en az bir anahtar taşıdığında — ancak geçerli bir dize protocolVersion taşımadığında döner. Örneğin aşağıdaki istek istemci kimliğini verir ama sürüm anahtarını atlar:

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/list",
  "params": {},
  "_meta": {
    "io.modelcontextprotocol/clientInfo": { "name": "example-cli", "version": "1.4.0" }
  }
}

Tahmin edilmek yerine reddedilir:

{
  "jsonrpc": "2.0",
  "id": 8,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "reason": "io.modelcontextprotocol/protocolVersion must be a string"
    }
  }
}

io.modelcontextprotocol/ ad alanını tümüyle atlayan bir istek hata değildir — yalnızca eski dönem olarak yönlendirilir.