MCP és csatlakoztatott eszközök

Csatlakoztasd a Nessie-t MCP-szerverekhez, és párosíts egy külső ügynököt, hogy a nevedben dolgozhasson a Nessie-ben.

Mi az MCP

A Model Context Protocol egy kicsi, nyílt konvenció arra, hogy eszközöket írjunk le egy nyelvi modellnek, és meghívjuk őket. A szerver megmondja, mit tud: nevesített eszközök listáját adja meg, mindegyikhez JSON-sémával az argumentumokhoz. A kliens felfedezi ezt a listát, és a modell nevében hívja meg az eszközöket. Szándékosan unalmas: az érték az, hogy egyszer megírt integráció működik minden modellel és minden olyan termékkel, amely ezt a nyelvet beszéli.

A Nessie mindkét oldalon ott van

Ezt érdemes pontosan kezelni, mert a két fél könnyen összekeverhető, és szándékosan különböző útvonalakon élnek.

• Kimenő irány. A Nessie MCP-kliens. Olyan szervereket csatlakoztat, amelyeket valaki más üzemeltet, és az általuk kínált eszközök azok lesznek, amelyeket az ügynökei használhatnak. A kezelőfelület a /api/mcp/* alatt van.
• Bejövő irány. A Nessie MCP-szerver is. Egy máshol futó ügynök, például a Claude Code vagy a Codex egy fejlesztő gépén, el tudja érni a táblákat és dokumentumokat. Ez a végpont a POST /mcp, szándékosan az /api-n kívül, hogy a két ellentétes jelentésű út ne essen egy szegmensnyire egymástól.

MCP-szerver csatlakoztatása a Nessie-hez

Katalógusbejegyzések és példányok

Két objektum van, és a különbség számít:

• A katalógusbejegyzés a szerver definíciója: a neve, az átviteli módja és az, hogyan hitelesít. Egyszer íródik meg, és megosztható.
• A példány az a bejegyzés, amely egy adott hatókörben van telepítve, a hozzá tartozó hitelesítő adatokkal. Ugyanazon bejegyzés telepítése két különböző csapatnak két példányt eredményez.

A legtöbben egyiket sem érintik közvetlenül. Az admin bejárata a /admin/apps alkalmazásbolt: ugyanazt a katalógust böngészi, a kapcsolati részleteket elrejtve, és egy bejegyzésnél a Connect gomb példányt hoz létre. Az üzemeltetők, akik a nyers objektumokat akarják, a /api/mcp/catalog és a /api/mcp/instances útvonalakat használják.

Ha egy szerver még nincs a katalógusban, a POST /api/mcp/discover egy URL-t vesz át, és visszaadja, mit mond magáról a szerver. A POST /api/mcp/library/import pedig egy bejegyzést húz be a nyilvános szerverkönyvtárból. Az első kapcsolat közvetlenül is létrehozható URL-ből a POST /api/apps/custom segítségével.

Átviteli módok

A Nessie HTTP-n csatlakozik a távoli szerverekhez. Két átvitel működik: a streamable HTTP, a jelenlegi MCP-átvitel, és a régebbi HTTP+SSE. Válaszd a http-t, hacsak a szerver csak sse-t nem kínál.

A stdio átvitel az általad írt összekötőkre nem engedélyezett. A stdio azt jelenti, hogy az MCP-szerver egy helyi folyamat, amelyet a gazdagép indít. Tetszőleges programok futtatását a Nessie-szerveren belül egy üzemeltető nem tudja értelmesen átvizsgálni. Ugyanezért kerülnek ki a könyvtári importokból azok a szerverek, amelyeket csak helyi futtatásra szolgáló csomagként adnak ki. A protokoll-mezőben létezik egy ws érték, de nincs megvalósítva: az ezt használó kapcsolat nem nyílik meg, amikor a Nessie megpróbálja megnyitni.

Hogyan hitelesít a Nessie a szerver felé

A katalógusbejegyzés öt módszer egyikét deklarálja: none, api_key, bearer, basic vagy oauth2.

Az api_key fejléc-injektálás: a bejegyzés megmondja, melyik fejlécet és milyen előtagot használjon. Így az Authorization: Bearer …, az X-API-Key: … és az X-Auth-Token: Token … ugyanaz a módszer, csak máshogy beállítva. A kulcsot egyszer a POST /api/mcp/instances/:instanceId/secret-tel add meg, és azt soha többé nem lehet visszaolvasni. A példány-útvonalak egyik válasza sem tartalmaz hitelesítő-hivatkozást.

Az oauth2 két formában jön. Fix végpontokkal rendelkező szervernél a végpontok a katalógusbejegyzésben vannak. Olyan szervernél, amely szabványos metaadatot tesz közzé, semmit sem kell beállítani: a Nessie beolvassa a védett erőforrás- és az engedélyező-szerver dokumentumait, és dinamikus kliensregisztrációval, vagy a saját well-known útvonalán közzétett kliensazonosító-metaadat-dokumentummal maga hoz létre egy klienst. Mindkét esetben a kézfogás a POST /api/mcp/instances/:instanceId/oauth/start, majd a szolgáltató átirányítása a GET /api/mcp/oauth/callback címre. Az állapottoken egyszer használható, az adatbázisban él, és tíz percig érvényes. A PKCE minden esetben használatban van.

Egy szabály sok embert meglep: még egy szervezeti tulajdonos sem csatolhat személyes vagy OAuth-tokent valaki másnak. Megosztott hitelesítő csak olyan API-kulcs-bejegyzéshez lehetséges, amelyet érvényesként igazoltak. Minden más el van utasítva. Az a hitelesítő, amely egy személyhez tartozik, egy személyhez tartozó marad.

Hol tárolódnak a hitelesítő adatok

Az összekötők titkai és az OAuth-tokencsomagok a saját Postgres-adatbázisukban tárolódnak, célhoz kötött AES-256-GCM borítékokban, a telepítés külön verziózott titkosítási kulcsgyűrűje alatt. Csak átlátszatlan secret_* hivatkozásokon keresztül érhetők el. Szándékosan nincsenek a külső titokkezelőben, amely a Nessie többi titkát tartja. Az éles környezet, amely nem konfigurálta a titkosított tárat, nem indul el, ahelyett hogy olyan OAuth-kézfogást fejezne be, amelyet utána elveszítene.

Hová ér el egy kapcsolat

Egy példány hat hatókör egyikén van telepítve: system, organization, project, team, channel vagy user. A hatókör kemény plafon arra nézve, mely futások használhatják, a jogosultságok pedig csak tovább szűkíthetik, soha nem bővíthetik. Így a saját fiókoddal telepített összekötő nem válhat csendben szervezetszintűvé.

Ki hova telepíthet, ugyanolyan alakú: a szervezet tulajdonosai és adminisztrátorai bármely hatókörben kezelhetnek telepítéseket, mindenki más pedig a saját user hatókörében telepít összekötőket. Látja azokat a megosztott telepítéseket is, amelyek eléréséhez joga van.

Eszköz adása egy ügynöknek

Egy szerver csatlakoztatása nem adja át az eszközeit senkinek. Amikor egy példányt telepítenek, a Nessie megvizsgálja, és minden hirdetett eszközt levetít az eszközregiszterbe. Ezt látja az admin a /admin/advanced/tools oldalon: beépített eszközök, MCP-eszközök, csomageszközök és executor-eszközök egy listában, mindegyik a forrásával és állapotával.

A levetített eszköz három állapot egyikében van: active, pending_review vagy disabled. A megosztott hatókörű telepítés eszközei pending_review állapotba kerülnek, és az oldalon jóvá kell hagyni őket, mielőtt bármely ügynök látná. A saját user hatókörű telepítés eszközei azonnal aktívak, mert csak te vagy kitéve. Az átvizsgálás nem egyszeri formalitás, hanem ismétlődő. Ha egy későbbi vizsgálat azt találja, hogy egy eszköz leírása vagy sémája eltért, az eszköz visszakerül pending_review állapotba, és addig nem kínálják, amíg valaki meg nem nézi a változást.

Azt, hogy mely ügynökök hívhatnak egy aktív eszközt, kétféleképpen döntik el:

• Az alkalmazásboltban létrehozott kapcsolat kifejezett jogosultságot igényel. Az ügynök csak akkor kapja meg az eszközt, ha egy jogosultság név szerint megnevezi. A jogosultságot az eszköz aktuális ujjlenyomatához ellenőrzik, így egy megváltozott eszközhöz új döntés kell.
• Egyébként az eszköz alapértelmezetten be van kapcsolva a hatókörének elérésében lévő ügynökök számára. Az egyes ügynököket az eszköz részletes panelján lehet kikapcsolni.

Egy jogosultság pontosan egy főszereplőt nevez meg, egy szerepet vagy egy ügynököt, sosem mindkettőt, és a tiltás felülírja az engedélyt. Egy user hatókörű kapcsolatnál a kérdés fel sem merül: bármelyik ügynök, amellyel az illető beszél, használhatja. Csak egy kifejezett kikapcsolás vonja vissza.

Egy dolgot könnyű rossz helyen keresni: az admin /settings/accounts oldala a csatlakoztatott fiókok. Ezek a Slack, a levelezési fiókok, a modell-előfizetések, valamint azok az OAuth-kapcsolatok a Linearhez, a Jirához, a GitHubhoz és a Trellóhoz, amelyek a külső táblákat szolgálják ki. Az MCP-összekötők az /admin/apps alatt vannak, az általuk létrehozott eszközök pedig a /admin/advanced/tools alatt.

Jóváhagyási kapuk az eszközhívásokon

Néhány eszközhívás megáll, és egy személyre vár. Ilyenkor a futás nem hibázik: a hívás befagyasztódik, az eszköz neve, az argumentumai hash-értéke és elég állapot marad a folytatáshoz, és egy jóváhagyási kérelem jelenik meg a /api/approvals alatt, hogy valaki válaszoljon rá. A döntő személy egy korlátos összefoglalót lát arról, amit kérnek. A pontos argumentumok és az eredeti futás a szerveroldalon maradnak. A folytatás idempotens, így egy duplikált jóváhagyás nem futtathatja kétszer a hívást.

Két különálló kapu van, és eltérően vannak beállítva.

• Szerkezeti kapuk bizonyos beépített eszközök tulajdonságai, és nem állíthatók be. Az ügynök saját levelezőládájából vagy egy csatlakoztatottból való küldés, a Gmail-vázlat elküldése, egy levelezési fiók leválasztása, naptáresemény létrehozása, módosítása vagy lemondása, valamint az a böngészőművelet, amely olyan oldalra írna, ahová a böngésző nincs bejelentkezve: mind így van kapuzva. Ezekre 24 órás ablak áll rendelkezésre a válaszadásra, a szokásos 30 perc helyett.
• Szabályzati kapuk a tool/invoke párra vonatkozó szabályzati szabályokból jönnek. Az a szabály, amely egy hívást engedélyez, hordozhatja a requiresApproval jelzést. Érvényes jóváhagyás nélkül a kiértékelés APPROVAL_REQUIRED értéket ad vissza, ahelyett hogy futna. A szabályokat tiltás-először módon, hatókör szerint rendezve értékeljük ki.

Hogy melyik admin-képernyő írja a requiresApproval szabályzati szabályt egy eszközre, azt nem tudtuk megerősíteni. Az adatmodell és a kényszerítés is a helyén van, de a képernyőt nem sikerült azonosítani, amely ezt a szabályt írja.

Külső ügynök csatlakoztatása a Nessie-hez

A másik irány. A Nessie a POST /mcp címen saját MCP-szervert futtat, streamable HTTP-n keresztül, és állapotmentes: minden hívás hordozza a saját hitelesítő adatait, és maga oldja fel a saját szereplőjét. Így nincs munkamenet, amelyhez egy kliens egy replikához köthető lenne. A ChatGPT, a Claude, a Claude Code, a Codex vagy egy ügynök valakinek a laptopján dolgozhat a táblákon, dokumentumokon és ügyfeleken belül, abból az eszközből, amelyet az illető már használ. Az alkalmazásonkénti lépéseket itt találod: Csatlakoztatás a ChatGPT-hez, a Claude-hoz és más AI-alkalmazásokhoz.

Mi valójában a párosított hitelesítő

Ezt kell helyesen érteni, mert az a kézenfekvő mentális modell, amely szerint ez egy API-kulcs, amelyhez jogosultságok vannak csatolva, a rossz.

A párosított hitelesítő sosem identitás. Egy személyt nevez meg, és minden eszközhívás annak a személynek a nevében fut, ugyanazokkal a szolgáltatásfüggvényekkel, amelyeket a HTTP-útvonalak hívnak. Egy ügynök ezért nem érhet el semmit, amit az a személy, aki kölcsönadta, kattintással nem érne el. A hatókörök csak szűkíthetik ezt az elérést. Nincs olyan hatókör, amely bővítené.

Az érvényesség minden egyes hívásnál újraolvasódik, nem a tokenből bízunk benne: a visszavonás, a lejárat, a felhasználó tokenverziója, a szervezeti tagsága és az aktuális szerepe. Egy lefokozás, egy deaktiválás vagy a „kijelentkezés mindenhonnan” az ügynök következő hívásán érvényesül, nem a hitelesítő lejáratakor.

A token átlátszatlan, nag1_ előtaggal, csak SHA-256 hash-ként tárolódik, és 90 napig él. Az MCP-végponton kívül bármely útvonalon egy meghatározott 403-mal utasítják el. Másik helyen bemutatva nem olyan részleges siker, amelyet újra kellene próbálni. Ez tartja fenn, hogy az „kikölcsönöztem az ügynöknek a tábláimat” ne jelentse azt, hogy „kikölcsönöztem neki a fiókomat”.

Két csatlakozási mód

Az olyan alkalmazás, amely meg tud nyitni böngészőt, mint a ChatGPT, a Claude, a Claude Code vagy a Codex, az MCP-engedélyezési profilt használja: OAuth 2.1, PKCE (S256), dinamikus kliensregisztráció a POST /mcp/oauth/register címen, frissítő tokenek és erőforrásjelzők. Az alkalmazás elküldi a személyt a /settings/security oldalra. Ott kiválasztják, mit tehet az alkalmazás, és mely csapataikat éri el. A böngésző kóddal tér vissza az alkalmazáshoz. A hozzáférési token egy óráig él, és frissíthető. A kapcsolat 90 napig él.

Egy parancssori ügynök nem irányít böngészőt, és nem tud visszahívási URL-t fogadni, ezért az eszközengedélyezési folyamatot (RFC 8628) használja.

1. Az ügynök a clientName-mel és a kért scopes-szal meghívja a POST /mcp/auth/device végpontot. Visszakap egy device_code-ot, egy rövid user_code-ot, egy verification_uri-t, és egy verification_uri_complete-et, amelynek lekérdezésében már benne van a kód. Kap még a lekérdezés interval-ját és egy expires_in-t. Kiírja az URI-t.
2. Egy bejelentkezett személy megnyitja ezt az URI-t a /settings/security oldalon. Látják, melyik ügynök kéri, kinek a fiókjában dolgozna, meddig, és pontosan mit tehetne. Ezután kiválasztják az Engedélyezés vagy a Nem engedélyezem lehetőséget.
3. Az ügynök a deviceCode-dal lekérdezi a POST /mcp/auth/token végpontot, figyelembe véve az authorization_pending, a slow_down, az expired_token és az access_denied válaszokat. Sikeresen egy { access_token, token_type, scope, expires_at } objektumot kap.

Mindkét esetben van emberi lépés, mert a hitelesítő a személy jogosultságait örökli, így valakinek döntenie kell a kölcsönadásról. Itt semmi sem hoz létre hozzáférést a semmiből. A csatlakozás egész szervezetre is kikapcsolható a /admin/security?tab=programs oldalon. Ezt a választ akkor ellenőrzik, amikor valaki engedélyez egy kapcsolatot, nem akkor, amikor egy ügynök elindít egyet.

Felfedezés

Egy hitelesítés nélküli POST /mcp 401-et ad vissza egy WWW-Authenticate fejléccel, amely a /.well-known/oauth-protected-resource útvonalra mutat (RFC 9728). Ez nevezi meg ezt az originöt engedélyező szerverként. A /.well-known/oauth-authorization-server metaadatai (RFC 8414) megnevezik a regisztrációs, az engedélyezési, a token- és a visszavonási végpontot. Ez a lánc mindent megad, amire egy kliensnek szüksége van, miután megkapta a címet. Ahhoz, hogy egy ügynök egy domainből megtalálja a címet, a /.well-known/ai-catalog.json fájlt olvassa. Ez megnevezi a Server Card-ot a /mcp/server-card címen (MCP Server Cards, SEP-2127). Az eszközengedélyezési végpontok a védett erőforrás-dokumentumban, az x-nessie-device-authorization alatt szerepelnek.

Egy telepítés egy második, rövidebb címen is válaszolhat. A Nessie Cloud https://nessie.works/mcp címe az API-hoz van proxyn keresztül kötve, és az ezen az úton érkező kliens erőforrásként ezt a címet kapja vissza, miközben a bejelentkezés az API-n marad. Átirányítás nem lenne elég, mert a kliens nem fogad el olyan metaadatot, amely a kapott címtől eltérő címet nevez meg. Az üzemeltető ezeket az originöket a NESSIE_MCP_ALIAS_ORIGINS-ban sorolja fel.

Hatókörök és eszközök

A hatókörök szándékosan durvák. Egy hatókört, amelyet senki nem tud megmagyarázni, senki nem állít helyesen. Az a kapcsolat, amely egynél több csapatot ér el, a nessie_team_list-tel listázza őket, és minden más eszköz a teamId-val nevezi meg a csapatot.

Ha egy hívás nem rendelkezik a szükséges hatókörrel, az eszközeredményként érkezik, amely megnevezi, melyik hatókört kell kérni. Nem átviteli hibaként érkezik, így a modell hasznos dolgot tud jelenteni, nem próbálkozik újra egy falnak ütközve.

Külső követőrendszerekhez nincs külön eszközcsalád. A tábla attól tábla, hogy a feladatai a Nessie-ben keletkeztek-e, vagy a Linearból, a Jirából, a GitHubból vagy a Trellóból tükrözik őket. Így egyetlen eszközkészlet mindkettőt lefedi, és minden feladat megmondja, melyikből származik. Az írásban van a különbség: egy csak olvasható forrásból tükrözött tábla szavakkal visszautasít minden írást. Megmondja az ügynöknek, hogy a jegyet a másik rendszer birtokolja, és az újrapróbálkozás nem segít.

Dokumentum közzététele jóváhagyás, nem jogosultság

Az ügynökök vázlatot írnak, egy személy teszi közzé. Ezt a Nessie saját ügynökeire úgy érvényesíti, hogy az ügynök-szereplőt egyszerűen elutasítja. A párosított hitelesítő viszont személyként oldódik fel, így ez az elutasítás nem fogja meg. A kapunak máshol kell lennie.

Így a nessie_doc_publish nem tesz közzé. Egy knowledge.page.publish jóváhagyást nyit, ugyanazt, amelyet egy Nessie-ügynök nyit, és visszaad egy { status: "awaiting_approval", approvalId } objektumot. A lekérdezés ugyanazt a kérést adja vissza, nem nyit másodikat. A döntést ugyanúgy hozza meg egy személy, mint a Nessie minden más közzétételi döntését: arról a dokumentumról, abban a pillanatban, amikor az létezik.

Szándékosan nincs közzétételi hatókör. Volt egy, egy jelölőnégyzet a párosításkor, amely azt mondta: ez az ügynök közzétehet. Visszavonták. Egyszer és kilencven napra döntött egy kérdésben, amelyet a termék máshol mindenhol dokumentumonként kérdez. A dokumentum létezése előtt döntött, így az a személy, aki bejelölte, nem tudhatta, mit egyezik bele a közzétételbe. A nessie_doc_publish-nek a documents_write kell, mert a kérdezés nem ingyen van: elolvassa az oldalt, és döntést tesz egy személy elé. Ez a hatókör viszont semmit nem ad a közzétételről.

A kérésen két identitást rögzítünk, és a különbség kulcsfontosságú. A kérelmező a hitelesítő, sosem az ember, akinek nevében eljár. A szükséges jóváhagyó az az ember, és csak ő válaszolhat. Ha a kérés az embert nevezné meg kérelmezőként, az a szabály, amely megakadályozza, hogy valaki a saját kérését hagyja jóvá, kizárná az egyetlen embert, aki jogosult dönteni.

A párosítottak látása és visszavonása

Egy személy saját párosított ügynökeit a /settings/security oldalon látja, mindegyikhez címkével és visszavonási vezérlővel. Egy tulajdonos vagy szervezeti admin a /admin/security?tab=programs oldalon látja a szervezet összes hitelesítőjét: hogy mi a neve, mit tehet, él-e még, és kinek a fiókját kölcsönzi. Bármelyiket visszavonhatja. A személyes lista csak a sajátját mutatja, mert az élő hitelesítők listája megkapaszkodási pontok listája, nem általános olvasmány.

A hitelesítőn keresztül írt módosításokat a kölcsönadó emberhez rendeljük, és az audit-metaadatokban megjelenik a hitelesítő azonosítója. Így a napló meg tudja különböztetni egy személy saját szerkesztését attól, amelyet az ügynöke végzett el helyette.

Ami még nem érhető el

Kifejezetten kimondjuk, mert a protokoll képességei és egy adott szerver képességei közötti rés az, ahol a dokumentáció általában hazudik:

• A csevegés, a csatornák, a futások és az ügynökkezelés nincsenek kitéve MCP-n keresztül.
• Egy program előkészít egy hírlevelet, és egy személy küldi el. Semmi sem küld, ütemez vagy töröl kampányt, maga az e-mail pedig a szerkesztőben készül.
• A kapcsolatok összekapcsolása és egyesítése, a CRM-séma-módosítások, az importálások és a csatornabeállítás a böngészőben, egy személynél maradnak.
• A csatlakoztatási kapcsoló egy szervezeti szintű beállítás. Csapat- és személyes felülírásokat egy csapat vagy egy személy ma nem állíthat be.