MCP ve bağlı araçlar

Nessie’yi MCP sunucularına bağlayın ve dış bir ajanı eşleştirerek sizin adınıza Nessie içinde çalışmasını sağlayın.

MCP nedir

Model Context Protocol, bir dil modeline araçları tanımlamanın ve bunları çağırmanın küçük ve açık bir yoludur. Bir sunucu neler yapabildiğini bildirir — her biri argümanları için bir JSON şeması olan adlandırılmış araçların listesi — ve bir istemci bu listeyi keşfeder ve modelin adına bunları çağırır. Kasıtlı olarak sade tutulmuştur: değeri, bir kez yazılan tek bir entegrasyonun onu konuşan her model ve her ürünle çalışmasıdır.

Nessie bunun iki tarafında da yer alır

Bunu özenle belirtmek gerekir, çünkü iki taraf kolayca karıştırılır ve bilerek farklı yollarda yaşarlar.

• Dışa giden. Nessie bir MCP istemcisidir. Başkasının çalıştırdığı sunucuları bağlarsınız ve onların sunduğu araçlar, ajanlarınızın kullanabileceği araçlar olur. Yönetim yüzeyi /api/mcp/* adresindedir.
• Gelen. Nessie aynı zamanda bir MCP sunucusudur. Başka bir yerde çalışan bir ajan — bir geliştiricinin makinesindeki Claude Code veya Codex — panolarınızı ve belgelerinizi çağırabilir. Bu uç nokta POST /mcp’dir ve bilerek /api’nin dışındadır; böylece zıt iki anlam tek bir yol segmenti farkıyla birbirine karışmaz.

Bir MCP sunucusunu Nessie’ye bağlamak

Katalog girdileri ve örnekler

İki nesne vardır ve aradaki fark önemlidir:

• Bir katalog girdisi, bir sunucunun tanımıdır — adı, aktarımı, nasıl kimlik doğruladığı. Bir kez yazılır ve paylaşılabilir.
• Bir örnek, o girdinin bir kapsamda, ona ulaşan kimlik bilgileriyle kurulmuş halidir. Aynı girdiyi iki farklı ekibe kurmak iki örnek üretir.

Çoğu kişi bunlardan hiçbirine doğrudan dokunmaz. Yönetim arayüzündeki giriş noktası, /admin/apps adresindeki uygulama mağazasıdır: aynı kataloğa bağlantı ayrıntıları gizlenmiş olarak göz atar ve bir listedeki Connect bir örnek oluşturur. Ham nesnelere ihtiyaç duyan operatörler /api/mcp/catalog ve /api/mcp/instances adreslerini kullanır.

Bir sunucu henüz katalogda değilse, POST /api/mcp/discover bir URL alır ve sunucunun kendisi hakkında söylediklerini geri okur; POST /api/mcp/library/import ise genel sunucu kütüphanesinden bir girdi çeker. İlk çalıştırmada bir bağlantı, POST /api/apps/custom ile doğrudan bir URL’den de oluşturulabilir.

Aktarımlar

Nessie uzak sunuculara HTTP üzerinden bağlanır. İki aktarım çalışır: akışlı HTTP (güncel MCP aktarımı) ve eski HTTP+SSE aktarımı. Sunucu yalnızca sse sunmuyorsa http’yi seçin.

stdio aktarımı, sizin yazdığınız bağlayıcılar için reddedilir. stdio, MCP sunucusunun ana makinenin başlattığı yerel bir süreç olduğu anlamına gelir; Nessie sunucusunun içinde keyfi programlar çalıştırmak, bir operatörün anlamlı biçimde inceleyebileceği bir şey değildir. Yalnızca yerel olarak çalıştırılmak üzere paket olarak yayımlanan sunucular, aynı nedenle kütüphane içe aktarımlarından çıkarılır. Protokol alanında bir ws değeri bulunur ama uygulanmamıştır — bunu kullanan bir bağlantı, Nessie açmaya çalıştığında başarısız olur.

Nessie sunucuya nasıl kimlik doğrular

Bir katalog girdisi beş yöntemden birini bildirir: none, api_key, bearer, basic veya oauth2.

api_key bir başlık enjeksiyonudur ve girdi hangi başlığın ve hangi önekin kullanılacağını söyler; yani Authorization: Bearer …, X-API-Key: … ve X-Auth-Token: Token … farklı biçimlerde yapılandırılmış aynı yöntemdir. Anahtarın kendisi POST /api/mcp/instances/:instanceId/secret ile bir kez yapıştırılır ve bir daha asla okunamaz; örnek rotalarındaki hiçbir yanıt bir kimlik bilgisi referansı taşımaz.

oauth2 iki biçimde gelir. Sabit uç noktaları olan bir sunucunun bunlar katalog girdisindedir. Standart meta veri yayımlayan bir sunucu için hiçbir şey yapılandırmak gerekmez: Nessie korumalı kaynak ve yetkilendirme sunucusu belgelerini okur ve dinamik istemci kaydı ya da kendi well-known yolunda yayımladığı istemci-ID meta veri belgesi aracılığıyla kendine bir istemci üretir. Her iki durumda da el sıkışma POST /api/mcp/instances/:instanceId/oauth/start ile başlar ve sağlayıcının GET /api/mcp/oauth/callback adresine yönlendirmesiyle devam eder. Durum belirteci tek kullanımlıktır, veritabanında tutulur, on dakika geçerlidir ve PKCE her zaman kullanılır.

Bir kural insanları şaşırtır: kuruluş sahibi bile kişisel veya OAuth belirteci başka birine ekleyemez. Paylaşılan bir kimlik bilgisi yalnızca doğrulanmış bir API anahtarı girdisi için mümkündür; diğer her şey reddedilir. Bir kişiye ait kimlik bilgisi, o kişiye ait kalır.

Kimlik bilgileri nerede tutulur

Bağlayıcı sırları ve OAuth belirteç paketleri, kendi Postgres veritabanınızda, dağıtımın bağımsız olarak sürümlenen şifreleme anahtar halkası altında amaca özgü AES-256-GCM zarflarında saklanır ve yalnızca opak secret_* referanslarıyla adreslenir. Bunlar bilerek, Nessie’nin diğer sırlarını tutan harici sır kasasında değildir. Şifreli depo yapılandırılmamış bir üretim dağıtımı, tamamlayıp sonra düşüreceği bir OAuth el sıkışmasını tamamlamak yerine başlamayı reddeder.

Bir bağlantı nereye ulaşır

Bir örnek altı kapsamdan birine kurulur: system, organization, project, team, channel veya user. Bu kapsam, hangi çalıştırmaların onu kullanabileceği konusunda sert bir tavandır ve yetkiler onu yalnızca daraltabilir, asla genişletemez; yani kendi hesabınızla kurduğunuz bir bağlayıcı, sessizce kuruluş genelinde bir bağlayıcıya dönüşemez.

Kimin nerede kurabileceği aynı biçimi izler: kuruluşun Owner ve Admin rolleri her kapsamdaki kurulumları yönetir; diğer herkes bağlayıcıları kendi user kapsamında kurar ve ulaşmaya hak kazandığı paylaşılan örnekleri görebilir.

Bir ajana araç vermek

Bir sunucuyu bağlamak, araçlarını kimseye vermez. Bir örnek kurulduğunda Nessie onu yoklar ve reklam ettiği her aracı araç kaydına yansıtır; yönetim arayüzünde /admin/advanced/tools adresinde gösterilen de budur — yerleşik araçlar, MCP araçları, paket araçları ve executor araçları, her biri kaynağı ve durumuyla birlikte tek bir listede.

Yansıtılan bir aracın üç durumdan biri vardır: active, pending_review veya disabled. Paylaşılan kapsamlı bir kurulumdan gelen araçlar pending_review durumunda gelir ve bir ajanın onları görmesi için o sayfada onaylanmaları gerekir; kendi user kapsamınızdaki kurulumdan gelen araçlar ise hemen etkin olur, çünkü yalnızca siz maruz kalırsınız. İnceleme tek seferlik bir tören değil, tekrarlanan bir işlemdir: sonraki bir yoklama bir aracın açıklamasının ya da şemasının kaydığını bulursa, araç yeniden pending_review durumuna geçer ve biri değişikliğe bakana kadar sunulmaz.

Etkin bir aracı hangi ajanların çağırabileceği iki yoldan biriyle belirlenir:

• Uygulama mağazası üzerinden oluşturulan bir bağlantı açık bir yetki gerektirir. Bir ajan aracı yalnızca bir yetki onu adlandırdığında alır ve yetki, aracın güncel parmak iziyle karşılaştırılır; bu nedenle değişmiş bir araç yeni bir karar gerektirir.
• Aksi halde araç, kapsamının erişimindeki ajanlar için varsayılan olarak açıktır ve tek tek ajanlar aracın ayrıntı panelinden kapatılabilir.

Bir yetki tam olarak bir öznenin — bir rolün veya bir ajanın, ikisinin birden değil — adına işaret eder ve ret, izni geçersiz kılar. user kapsamlı bir bağlantı için soru hiç ortaya çıkmaz: o kişinin konuştuğu her ajan onu kullanabilir ve onu geri çekmenin tek yolu açık bir kapatmadır.

Yanlış yerde aranması kolay bir şey: yönetim arayüzündeki /settings/accounts bağlı hesaplardır — Slack, posta kutuları, model abonelikleri ve harici panoları destekleyen Linear, Jira, GitHub ve Trello OAuth bağlantıları. MCP bağlayıcıları /admin/apps adresindedir ve onların ürettiği araçlar /admin/advanced/tools adresindedir.

Araç çağrılarındaki onay kapıları

Bazı araç çağrıları durur ve bir kişiyi bekler. Bu olduğunda çalıştırma başarısız olmaz: çağrı dondurulur — araç adı, argümanlarının bir karma değeri ve devam etmek için yeterli durum — ve bir onay isteği, birinin yanıtlaması için /api/approvals altında görünür. Devam etmek idempotenttir; bu yüzden yinelenen bir onay çağrıyı iki kez çalıştıramaz. Karar veren kişi, sorulanın sınırlı bir özetini görür; tam argümanlar ve başlatan çalıştırma sunucu tarafında kalır.

İki ayrı kapı vardır ve bunlar farklı yapılandırılır.

• Yapısal kapılar, belirli yerleşik araçların bir özelliğidir ve yapılandırılamaz. Bir ajanın kendi posta kutusundan veya bağlı bir posta kutusundan e-posta göndermek, bir Gmail taslağı göndermek, bir posta hesabının bağlantısını kesmek, bir takvim etkinliği oluşturmak, değiştirmek veya iptal etmek ve tarayıcının oturum açmadığı bir siteye yazacak bir tarayıcı eylemi, hepsi bu şekilde kapılanır. Bunlar, olağan 30 dakika yerine yanıtlanması için 24 saatlik bir pencere alır.
• Politika kapıları, tool/invoke çiftindeki politika kurallarından gelir. Bir invokasyona izin veren bir kural requiresApproval taşıyabilir ve doğrulanmış bir onay olmadan değerlendirme, çalışmak yerine APPROVAL_REQUIRED döndürür. Kurallar önce reddetme ilkesiyle ve kapsama göre sıralı olarak değerlendirilir.

Bir aracın requiresApproval politika kuralını hangi yönetim ekranının yazdığını teyit edemedik — veri modeli ve zorlama ikisi de yerinde, ama böyle bir kuralı yazan ekranı doğrulayamadık.

Dışarıdan bir ajanı Nessie’ye bağlamak

Diğer yön. Nessie kendi MCP sunucusunu POST /mcp adresinde akışlı HTTP üzerinden çalıştırır ve bu sunucu durumsuzdur: her çağrı kendi kimlik bilgisini taşır ve kendi aktörünü çözümler, bu yüzden bir istemciyi tek bir replikaya bağlayacak bir oturum yoktur. ChatGPT, Claude, Claude Code, Codex veya birinin dizüstü bilgisayarındaki bir ajan, o kişinin zaten kullandığı araçların içinden panolarınız, belgeleriniz ve müşterilerinizle çalışabilir. Her uygulama için adım adım rehber ChatGPT, Claude ve diğer yapay zekâ uygulamalarını bağlamak başlığındadır.

Eşleştirilmiş kimlik bilgisi aslında nedir

Doğru anlamak gereken kısım budur, çünkü akla ilk gelen zihinsel model — izinleri eklenmiş bir API anahtarı — yanlıştır.

Eşleştirilmiş bir kimlik bilgisi asla bir kimlik değildir. Bir insanı adlandırır ve her araç çağrısı o insanın adına, HTTP rotalarının çağırdığı aynı servis fonksiyonlarına karşı çalışır. Bu nedenle bir ajan, kimlik bilgisini ödünç veren kişinin tıklayarak ulaşamayacağı hiçbir şeye erişemez. Kapsamlar erişimi yalnızca daraltır; onu genişleten bir kapsam yoktur.

Canlılık her çağrıda yeniden okunur, belirteçten asla güvenilmez: iptal, son kullanma tarihi, kullanıcının belirteç sürümü, kuruluş üyeliği ve güncel rolü. Bir rol düşürme, devre dışı bırakma veya “her yerden çıkış yap” işlemi, kimlik bilgisinin son kullanma tarihinde değil, ajanın bir sonraki çağrısında geçerli olur.

Belirteç opaktır, nag1_ önekiyle başlar, yalnızca bir SHA-256 karması olarak saklanır ve 90 gün yaşar. MCP uç noktası dışındaki herhangi bir rotada özel bir 403 ile reddedilir — onu başka yerde sunmak, yeniden denenecek kısmi bir başarı değildir. Bu sayede “panolarımı bir ajana ödünç verdim”, “hesabımı ona verdim” anlamına gelmez.

Bağlanmanın iki yolu

Bir tarayıcı açabilen uygulamalar — ChatGPT, Claude, Claude Code, Codex — MCP yetkilendirme profilini kullanır: PKCE (S256) ile OAuth 2.1, POST /mcp/oauth/register adresinde dinamik istemci kaydı, yenileme belirteçleri ve kaynak göstergeleri. Uygulama kişiyi /settings/security adresine gönderir; kişi neler yapabileceğini ve hangi ekiplerine ulaşacağını seçer ve tarayıcı bir kodla birlikte uygulamaya geri döner. Erişim belirteci bir saat geçerlidir ve yenilenir; bağlantı 90 gün yaşar.

Komut satırı ajanı bir tarayıcı kontrol etmez ve bir geri çağırma URL’si barındıramaz; bu yüzden bunun yerine cihaz yetkilendirme yetkisini (RFC 8628) kullanarak eşleşir.

1. Ajan, bir clientName ve istediği scopes ile POST /mcp/auth/device çağrısını yapar. Bir device_code, kısa bir user_code, bir verification_uri ve sorguda kodu zaten içeren bir verification_uri_complete alır; buna ek olarak yoklama interval değerini ve bir expires_in süresini. URI’yi yazdırır.
2. Bir kişi, oturum açmışken o URI’yi /settings/security adresinde açar. Hangi ajanın istediğini, hangi hesap adına çalışacağını, ne zamana kadar ve tam olarak neler yapabileceğini görür ve İzin ver ya da İzin verme seçer.
3. Ajan, authorization_pending, slow_down, expired_token ve access_denied yanıtlarına uyarak POST /mcp/auth/token adresine deviceCode ile yoklama yapar. Başarılı olursa { access_token, token_type, scope, expires_at } alır.

Her iki durumda da bir insan adımı vardır, çünkü kimlik bilgisi bir kişinin yetkilerini devralır; bu yüzden birinin ödünç vermeyi seçmesi gerekir. Burada hiçbir şey sıfırdan erişim üretmez. Bağlantı, bir kuruluş için /admin/security?tab=programs adresinden tümüyle kapatılabilir ve bu yanıt, bir ajan bağlantı başlattığında değil, birisi bir bağlantıya izin verdiğinde kontrol edilir.

Keşif

Kimlik doğrulaması yapılmamış bir POST /mcp, WWW-Authenticate başlığıyla 401 yanıtı verir; bu başlık /.well-known/oauth-protected-resource adresine (RFC 9728) işaret eder ve bu origin’i yetkilendirme sunucusu olarak adlandırır. /.well-known/oauth-authorization-server adresindeki meta veri (RFC 8414) kayıt, yetkilendirme, belirteç ve iptal uç noktalarını adlandırır. Bir istemci adresi bir kez aldığında ihtiyacı olan her şey bu zincirdir. Bir alan adından adresi bulmak için bir ajan /.well-known/ai-catalog.json dosyasını okur; bu dosya /mcp/server-card adresindeki Server Card’ı adlandırır (MCP Server Cards, SEP-2127). Cihaz yetkilendirme uç noktaları, korumalı kaynak belgesinde x-nessie-device-authorization altında listelenir.

Bir dağıtım, ikinci ve daha kısa bir adreste de yanıt verebilir: Nessie Cloud’un https://nessie.works/mcp adresi API’ye proxy edilir ve bu yoldan gelen bir istemci, kaynak olarak bu adresi geri alır; oturum açma ise API’de kalır. Yönlendirme yetmezdi, çünkü bir istemci kendisine verilen adres dışında herhangi bir adresi adlandıran meta veriyi reddeder. Operatör bu origin’leri NESSIE_MCP_ALIAS_ORIGINS içinde listeler.

Kapsamlar ve araçlar

Kapsamlar kasıtlı olarak kabadır — kimsenin açıklayamadığı bir kapsamı kimse doğru ayarlayamaz. Birden fazla ekibe ulaşan bir bağlantı, bunları nessie_team_list ile listeler ve diğer her araç teamId değerini adlandırır.

İhtiyaç duyduğu kapsam olmadan yapılan bir çağrı, bir aktarım hatası olarak değil, istenmesi gereken kapsamı adlandıran bir araç sonucu olarak döner; böylece model bir duvara tekrar tekrar çarpmak yerine yararlı bir şey bildirebilir.

Harici izleyiciler için ayrı bir araç ailesi yoktur. Bir pano, görevleri Nessie’de doğmuş olsun ya da Linear, Jira, GitHub veya Trello’dan yansıtılmış olsun, bir panodur; bu yüzden tek bir araç seti ikisini de kapsar ve her görev hangisinden geldiğini söyler. Fark yazmada yatar: salt okunur bir kaynaktan yansıtılan bir pano, yazmayı sözle reddeder ve ajana, ticket’ın diğer sisteme ait olduğunu ve yeniden denemenin işe yaramayacağını söyler.

Bir belgeyi yayımlamak bir kapsam değil, bir onaydır

Ajanlar taslak hazırlar; bir kişi yayımlar. Bu kural, Nessie’nin kendi ajanları için bir ajan aktörünü doğrudan reddederek uygulanır — ama eşleştirilmiş bir kimlik bilgisi bir kişi olarak çözülür, bu yüzden o ret onu yakalayamaz. Kapının başka bir yerde olması gerekir.

Bu yüzden nessie_doc_publish yayımlamaz. Bir knowledge.page.publish onayı açar — bir Nessie ajanının açtığının aynısı — ve { status: "awaiting_approval", approvalId } döndürür. Sorgulama, ikinci bir istek açmak yerine aynı isteği döndürür. Karar, Nessie’deki diğer her yayımlama kararının alındığı gibi alınır: bir kişi tarafından, belge hakkında, tam olarak o belge var olduğunda.

Bilerek bir yayımlama kapsamı yoktur. Bir zamanlar vardı — eşleştirme sırasında “bu ajan yayımlayabilir” diyen bir onay kutusuydu — ve kaldırıldı. Bu kutu, ürünün her yerde belge bazında sorduğu bir soruyu bir kez ve doksan gün boyunca karara bağlıyordu ve bunu belge var olmadan önce karara bağlıyordu; bu yüzden onu işaretleyen kişi neyi yayımlamayı kabul ettiğini bilemezdi. nessie_doc_publish documents_write gerektirir, çünkü istemek bedava değildir — sayfayı okur ve bir kararı birinin önüne koyar — ama bu kapsam yayımlama hakkında hiçbir şey vermez.

İsteğe iki kimlik kaydedilir ve bu ayrım yük taşır. İsteyen, kimlik bilgisinin kendisidir, onun adına hareket ettiği insan değil. Gereken onaylayan, o insandır ve yalnızca o yanıtlayabilir. İstek kişiyi isteyen olarak adlandırsaydı, kimsenin kendi isteğini onaylamasını engelleyen kural, karar verme hakkı olan tek kişiyi diskalifiye ederdi.

Eşleştirilenleri görmek ve iptal etmek

Bir kişinin kendi eşleştirilmiş ajanları /settings/security adresinde, her biri için bir etiket ve bir iptal denetimiyle listelenir. Bir sahip veya kuruluş yöneticisi, kuruluştaki her kimlik bilgisini /admin/security?tab=programs adresinde görür — her birinin adı, ne yapabildiği, canlı olup olmadığı ve hangi hesabı ödünç aldığı — ve bunların herhangi birini iptal edebilir. Kişisel liste yalnızca kendine özgüdür: canlı kimlik bilgilerinin bir listesi, genel okuma değil, ayak basılacak yerlerin bir listesidir.

Bir kimlik bilgisi üzerinden yapılan yazmalar, ödünç alan insana atfedilir ve kimlik bilgisinin kimliğini denetim üst verisinde taşır; böylece günlük, bir kişinin kendi düzenlemesini ajanının onun adına yaptığı bir düzenlemeden ayırt edebilir.

Henüz mevcut olmayanlar

Açık olmak için, çünkü bir protokolün yetenekleriyle belirli bir sunucunun yetenekleri arasındaki fark, belgelerin genellikle yanıltıcı olduğu yerdir:

• Sohbet, kanallar, çalıştırmalar ve ajan yönetimi MCP üzerinden sunulmaz.
• Bir program bir bülten hazırlar ve bir kişi onu gönderir: hiçbir şey bir kampanyayı göndermez, zamanlamaz veya silmez ve e-postanın kendisi tasarımcıda yazılır.
• Kişileri bağlamak ve birleştirmek, CRM şeması değişiklikleri, içe aktarmalar ve kanal kurulumu tarayıcıda bir kişide kalır.
• Bağlanmaya izin veren anahtar bir kuruluş düzeyinde bir ayardır. Ekip düzeyinde ve kişisel geçersiz kılmalar, bugün bir ekibin ya da kişinin ayarlayabileceği bir şey değildir.