MCP a pripojené nástroje

Pripojte Nessie k serverom MCP a sparujte externého agenta, aby mohol v Nessie pracovať ako vy.

Čo je MCP

Model Context Protocol je malá, otvorená konvencia na opis nástrojov pre jazykový model a na ich volanie. Server deklaruje, čo dokáže — zoznam pomenovaných nástrojov, každý s JSON schémou pre svoje argumenty — a klient tento zoznam zistí a nástroje vyvolá v mene modelu. Je úmyselne skromný: hodnota spočíva v tom, že jedna integrácia napísaná raz funguje s každým modelom a každým produktom, ktorý tento protokol ovláda.

Nessie stojí na oboch stranách

Stojí za to byť presný, pretože tieto dve polovice sa ľahko zamieňajú a žijú na úmyselne odlišných cestách.

• Odchádzajúce. Nessie je MCP klient. Pripájate servery, ktoré prevádzkuje niekto iný, a nástroje, ktoré vystavujú, sa stanú nástrojmi, ktoré vaši agenti môžu používať. Správcovské rozhranie je /api/mcp/*.
• Prichádzajúce. Nessie je tiež MCP server. Agent bežiaci inde — Claude Code alebo Codex na vývojárovom počítači — môže pracovať s vašimi tabuľami a dokumentmi. Tento endpoint je POST /mcp, úmyselne mimo /api, aby dva opačné významy neboli len jeden segment cesty od seba.

Pripojenie MCP servera k Nessie

Položky katalógu a inštancie

Sú tu dva objekty a ich rozdiel je dôležitý:

• Položka katalógu je definícia servera — jeho názov, prenos a spôsob autentifikácie. Zapíše sa raz a dá sa zdieľať.
• Inštancia je táto položka nainštalovaná v jednom rozsahu, s poverením, ktoré sa k nej dostane. Nainštalovanie tej istej položky pre dva rôzne tímy vytvorí dve inštancie.

Väčšina ľudí sa k žiadnemu z nich priamo nedostane. Vstupom do administrácie je App Store na /admin/apps: prehliadá ten istý katalóg so skrytými údajmi pripojenia a tlačidlo Connect pri položke vytvorí inštanciu. Operátori, ktorí chcú surové objekty, používajú /api/mcp/catalog a /api/mcp/instances.

Ak server ešte nie je v katalógu, POST /api/mcp/discover prijme URL a vráti, čo o sebe server hovorí, a POST /api/mcp/library/import stiahne položku z verejnej knižnice serverov. Prvé pripojenie sa dá vytvoriť aj priamo z URL cez POST /api/apps/custom.

Prenosy

Nessie sa k vzdialeným serverom pripája cez HTTP. Fungujú dva prenosy: streamovateľný HTTP (aktuálny prenos MCP) a starší HTTP+SSE. Vyberte http, pokiaľ server neponúka iba sse.

Prenos stdio je odmietnutý pre konektory, ktoré napíšete vy. stdio znamená, že MCP server je lokálny proces, ktorý spúšťa hostiteľ, a spúšťanie ľubovoľných programov vnútri servera Nessie operátor zmysluplne posúdiť nemôže. Servery publikované len ako balík na lokálne spustenie sa z importov z knižnice vyraďujú z rovnakého dôvodu. Hodnota ws existuje v poli protokolu, no nie je implementovaná — pripojenie, ktoré ju použije, zlyhá, keď sa Nessie pokúsi ho otvoriť.

Ako sa Nessie autentifikuje voči serveru

Položka katalógu deklaruje jednu z piatich metód: none, api_key, bearer, basic alebo oauth2.

api_key je vkladanie hlavičky a položka povie, ktorá hlavička a aký prefix sa použije — takže Authorization: Bearer …, X-API-Key: … a X-Auth-Token: Token … sú tá istá metóda, len nastavená inak. Kľúč sa vloží raz cez POST /api/mcp/instances/:instanceId/secret a nikdy ho už nie je možné prečítať. Žiadna odpoveď z inštančných trás neobsahuje odkaz na poverenie.

oauth2 sa vyskytuje v dvoch tvaroch. Server s pevnými koncovými bodmi ich má v položke katalógu. Server, ktorý publikuje štandardné metadáta, nepotrebuje nič nastavovať: Nessie prečíta dokumenty chráneného zdroja a autorizačného servera a vytvorí si klienta buď cez dynamickú registráciu klienta, alebo cez dokument metadát ID klienta, ktorý publikuje na svojej well-known ceste. V oboch prípadoch prebieha handshake cez POST /api/mcp/instances/:instanceId/oauth/start a potom presmerovanie poskytovateľa späť na GET /api/mcp/oauth/callback. Stavový token sa používa iba raz, drží sa v databáze a platí desať minút. PKCE sa používa vždy.

Jedno pravidlo ľudí prekvapí: ani vlastník organizácie nemôže pripojiť osobný alebo OAuth token k niekomu inému. Zdieľané poverenie je možné len pri položke typu API kľúč, ktorá bola ako taká overená; všetko ostatné je odmietnuté. Poverenie, ktoré patrí osobe, zostáva povereniom tejto osoby.

Kde žijú poverenia

Tajomstvá konektorov a balíky OAuth tokenov sa ukladajú vo vašej vlastnej databáze Postgres, v účelovo viazaných obálkach AES-256-GCM pod nezávisle verzovaným kľúčovým kruhom šifrovania nasadenia, a sú adresované len nepriehľadnými odkazmi secret_*. Úmyselne nie sú vo externom trezore tajomstiev, ktorý drží ostatné tajomstvá Nessie. Produkčné nasadenie, ktoré nemá nastavený šifrovaný úložný priestor, odmietne spustenie namiesto toho, aby dokončilo OAuth handshake, ktorý by potom zahodilo.

Kam pripojenie dosiahne

Inštancia sa nainštaluje na jednom zo šiestich rozsahov: system, organization, project, team, channel alebo user. Rozsah je pevný strop toho, ktoré behy ho môžu použiť, a granty ho môžu len ďalej zúžiť, nikdy rozšíriť — takže konektor, ktorý ste nainštalovali vlastným účtom, sa nemôže nenápadne stať celoorganizačným.

Kto môže inštalovať kam, sa riadi rovnakým tvarom: vlastníci a správcovia organizácie spravujú inštalácie na ľubovoľnom rozsahu; ostatní inštalujú konektory na svojom vlastnom rozsahu user a vidia zdieľané inštalácie, ku ktorým majú prístup.

Dať agentovi nástroj

Pripojenie servera nikomu nedáva jeho nástroje. Pri inštalácii inštancie Nessie ju preskúma a každý nástroj, ktorý ohlási, premietne do registra nástrojov. Ten administrácia zobrazuje na /admin/advanced/tools — vstavané nástroje, nástroje MCP, nástroje balíkov a nástroje executora v jednom zozname, každý so svojím zdrojom a stavom.

Premietnutý nástroj má jeden z troch stavov: active, pending_review alebo disabled. Nástroje zo zdieľanej inštalácie prídu ako pending_review a na tej stránke ich musí niekto schváliť skôr, než ich agent uvidí. Nástroje z vašej vlastnej inštalácie v rozsahu user sú aktívne hneď, pretože jediná exponovaná osoba ste vy. Kontrola sa opakuje a nie je jednorazový obrad: ak neskoršia kontrola zistí, že sa popis alebo schéma nástroja posunula, nástroj sa vráti do stavu pending_review a prestane sa ponúkať, kým sa na zmenu niekto nepozrie.

O tom, ktorí agenti smú aktívny nástroj volať, sa rozhoduje dvoma spôsobmi:

• Pripojenie vytvorené cez App Store vyžaduje explicitné oprávnenie. Agent dostane nástroj iba vtedy, keď ho oprávnenie menuje, a oprávnenie sa overuje voči aktuálnemu odtlačku nástroja, takže zmenený nástroj potrebuje nové rozhodnutie.
• Inak je nástroj predvolene zapnutý pre agentov v dosahu jeho rozsahu a jednotlivých agentov vypnete na detailnom paneli nástroja.

Oprávnenie menuje presne jedného principála — rolu alebo agenta, nikdy oboje — a zákaz vždy prebíja povolenie. Pri pripojení v rozsahu user sa otázka nekladie: ktorýkoľvek agent, s ktorým ten človek hovorí, ho môže použiť, a jediné, čo ho zadrží, je výslovné vypnutie.

Jedna vec, ktorú je ľahké hľadať na zlom mieste: /settings/accounts v administrácii sú prepojené účty — Slack, poštové schránky, predplatné modelov a OAuth prepojenia na Linear, Jira, GitHub a Trello, ktoré napájajú externé tabule. Konektory MCP sú na /admin/apps a nástroje, ktoré produkujú, sú na /admin/advanced/tools.

Schvaľovacie brány pri volaniach nástrojov

Niektoré volania nástrojov sa zastavia a čakajú na človeka. Keď sa tak stane, beh nezlyhá: volanie sa zmrazí — názov nástroja, hash jeho argumentov a dosť stavu na pokračovanie — a žiadosť o schválenie sa objaví na /api/approvals, aby ju niekto zodpovedal. Pokračovanie je idempotentné, takže zdvojené schválenie nemôže volanie spustiť dvakrát. Osoba, ktorá rozhoduje, vidí ohraničené zhrnutie toho, čo sa žiada; presné argumenty a pôvodný beh zostávajú na serveri.

Existujú dve odlišné brány a nastavujú sa inak.

• Štrukturálne brány sú vlastnosťou určitých vstavaných nástrojov a nedajú sa konfigurovať. Odosielanie pošty zo schránky agenta alebo z pripojenej schránky, odoslanie konceptu Gmail, odpojenie poštového účtu, vytvorenie, zmena alebo zrušenie udalosti v kalendári a akcia v prehliadači, ktorá by zapisovala na stránku, do ktorej prehliadač nie je prihlásený, — všetko je takto bránené. Dostávajú 24-hodinové okno na odpoveď namiesto obvyklých 30 minút.
• Politické brány pochádzajú z pravidiel politiky na dvojici tool/invoke. Pravidlo, ktoré volanie povolí, môže niesť requiresApproval, a bez overeného schválenia hodnotenie vráti APPROVAL_REQUIRED namiesto spustenia. Pravidlá sa vyhodnocujú najprv zákazom a zoradené sú podľa rozsahu.

Ktorá obrazovka administrácie zapisuje pravidlo politiky requiresApproval pre nástroj, nevieme potvrdiť: dátový model aj vynucovanie sú na mieste, no obrazovku, ktorá takéto pravidlo zapisuje, sa nám nepodarilo overiť.

Pripojenie externého agenta k Nessie

Opačný smer. Nessie prevádzkuje vlastný MCP server na POST /mcp, cez streamovateľný HTTP, a je bezstavový: každé volanie nesie vlastné poverenie a rieši vlastného aktéra, takže neexistuje relácia, ktorá by klienta pripínala na jednu repliku. ChatGPT, Claude, Claude Code, Codex alebo agent na niečijom notebooku môžu pracovať s vašimi tabuľami, dokumentmi a zákazníkmi zvnútra nástroja, ktorý ten človek už používa. Postup krok za krokom pre každú aplikáciu je v Pripojenie ChatGPT, Claude a ďalších AI aplikácií.

Čo je spárované poverenie v skutočnosti

Túto časť treba pochopiť správne, pretože zjavný mentálny model — API kľúč s pripojenými oprávneniami — je nesprávny.

Spárované poverenie nikdy nie je identita. Označuje človeka a každé volanie nástroja beží ako tento človek, nad tými istými servisnými funkciami, ktoré volajú HTTP trasy. Agent preto nemôže dosiahnuť nič, čo by osoba, ktorá ho požičala, nemohla dosiahnuť kliknutím. Rozsahy ho len zužujú; neexistuje rozsah, ktorý by ho rozšíril.

Platnosť sa overuje pri každom jednotlivom volaní, nikdy sa neberie z tokenu: odvolanie, expirácia, verzia tokenu používateľa, členstvo v organizácii a aktuálna rola. Zníženie roly, deaktivácia alebo „odhlásiť ma zo všetkých zariadení“ sa prejavia pri ďalšom volaní agenta, nie až pri expirácii poverenia.

Token je nepriehľadný, s predponou nag1_, ukladá sa len ako hash SHA-256 a platí 90 dní. Na akejkoľvek inej trase než na endpointe MCP je odmietnutý špecifickou odpoveďou 403. Jeho predloženie inde nie je čiastočný úspech, ktorý by sa oplatilo zopakovať — a práve to zabraňuje tomu, aby „požičal som agentovi svoje tabule“ znamenalo „požičal som mu svoj účet“.

Dva spôsoby pripojenia

Aplikácia, ktorá dokáže otvoriť prehliadač — ChatGPT, Claude, Claude Code, Codex — používa profil autorizácie MCP: OAuth 2.1 s PKCE (S256), dynamickú registráciu klienta na POST /mcp/oauth/register, obnovovacie tokeny a indikátory zdroja. Aplikácia pošle človeka na /settings/security, ten si vyberie, čo smie robiť a ktoré z jeho tímov dosiahne, a prehliadač sa vráti do aplikácie s kódom. Jej prístupový token platí hodinu a obnovuje sa; pripojenie trvá 90 dní.

Príkazový agent neovláda prehliadač a nemôže hostiť URL na spätné volanie, takže sa páruje cez device authorization grant (RFC 8628).

1. Agent zavolá POST /mcp/auth/device s clientName a scopes, ktoré chce. Dostane späť device_code, krátky user_code, verification_uri a verification_uri_complete s kódom už v query, plus interval dopytovania interval a expires_in. Vypíše URI.
2. Osoba otvorí toto URI, keď je prihlásená, na /settings/security. Vidí, ktorý agent sa pýta, v čím účte by pracoval, dokedy a presne čo by mohol robiť — a vyberie Allow alebo Don’t allow.
3. Agent dopytuje POST /mcp/auth/token s deviceCode a rešpektuje authorization_pending, slow_down, expired_token a access_denied. Pri úspechu dostane { access_token, token_type, scope, expires_at }.

V každom prípade je tu krok pre človeka, lebo poverenie dedí oprávnenia osoby, takže sa osoba musí rozhodnúť, že ich požičia. Tu nevzniká prístup z ničoho. Pripájanie sa dá na úrovni celej organizácie vypnúť na /admin/security?tab=programs a táto odpoveď sa kontroluje vtedy, keď niekto pripojenie povolí, nie keď ho agent začne.

Vyhľadávanie

Neautentifikovaný POST /mcp odpovie 401 s hlavičkou WWW-Authenticate, ktorá ukazuje na /.well-known/oauth-protected-resource (RFC 9728) a pomenúva tento pôvod ako autorizačný server. Jeho metadáta na /.well-known/oauth-authorization-server (RFC 8414) pomenúvajú koncové body registrácie, autorizácie, tokenu a odvolania. Tento reťazec je všetko, čo klient potrebuje, keď má adresu. Aby agent zistil adresu z domény, prečíta /.well-known/ai-catalog.json, ktorý ukazuje na Server Card na /mcp/server-card (MCP Server Cards, SEP-2127). Koncové body device grantu sú vypísané v dokumente chráneného zdroja pod x-nessie-device-authorization.

Nasadenie môže odpovedať aj na druhej, kratšej adrese: https://nessie.works/mcp cloudovej verzie Nessie sa proxuje na API a klient, ktorý sa sem dostal, dostane túto adresu späť ako zdroj, zatiaľ čo prihlasovanie zostáva na API. Presmerovanie by nestačilo, pretože klient odmietne metadáta, ktoré pomenúvajú inú adresu, než akú dostal. Operátor tieto pôvody uvedie v NESSIE_MCP_ALIAS_ORIGINS.

Rozsahy a nástroje

Rozsahy sú úmyselne hrubé — rozsah, ktorý nikto nevysvetlí, nikto nenastaví správne. Pripojenie, ktoré dosiahne viac než jeden tím, ich vypíše pomocou nessie_team_list a každý ďalší nástroj potom uvedie svoj teamId.

Volanie bez rozsahu, ktorý potrebuje, sa vráti ako výsledok nástroja, ktorý pomenuje rozsah, o ktorý treba požiadať, a nie ako chyba prenosu. Model tak môže nahlásiť niečo užitočné namiesto opakovania proti stene.

Pre externé trackery neexistuje samostatná rodina nástrojov. Tabuľa je tabuľa bez ohľadu na to, či jej úlohy pochádzajú z Nessie, alebo sú zrkadlené z Linear, Jira, GitHub či Trello, takže jedna sada nástrojov pokrýva oboje a každá úloha hovorí, odkiaľ pochádza. Líši sa až zápis: tabuľa zrkadlená zo zdroja len na čítanie odmietne zápis s vysvetlením, že tiket vlastní iný systém a opakovanie nepomôže.

Publikovanie dokumentu je schválenie, nie rozsah

Agenti pripravujú koncepty; publikuje človek. Toto pravidlo sa pre agentov Nessie vynucuje tak, že agentského aktéra jednoducho odmietne. Spárované poverenie sa však rieši ako osoba, takže toto odmietnutie ho nemôže zachytiť. Brána musí byť inde.

Takže nessie_doc_publish nepublikuje. Otvorí schválenie knowledge.page.publish — rovnaké, aké otvorí agent Nessie — a vráti { status: "awaiting_approval", approvalId }. Dopytovanie vráti tú istú žiadosť namiesto toho, aby otvorilo druhú. Rozhodnutie sa robí tak, ako sa robia všetky ostatné rozhodnutia o publikovaní v Nessie: osobou, o tomto dokumente, v momente, keď existuje.

Úmyselne neexistuje žiadny rozsah pre publikovanie. Jeden bol — zaškrtnutie pri párovaní, ktoré hovorilo, že tento agent smie publikovať — a bol zrušený. Rozhodoval raz a na deväťdesiat dní o otázke, ktorú produkt inde kladie pri každom dokumente zvlášť, a rozhodoval ju skôr, než dokument existoval. Človek, ktorý ho zaškrtol, tak nemohol vedieť, čo schvaľuje na publikovanie. nessie_doc_publish potrebuje documents_write, pretože žiadať nie je zadarmo — prečíta stránku a predloží rozhodnutie niekomu — no tento rozsah neudeľuje nič o publikovaní.

Na žiadosti sa zaznamenávajú dve identity a rozdiel je zásadný. Žiadateľom je poverenie, nikdy človek, za ktorého koná. Vyžadovaný schvaľovateľ je tento človek a len on môže odpovedať. Ak by žiadosť uvádzala osobu ako žiadateľa, pravidlo, ktoré bráni schváleniu vlastnej žiadosti, by diskvalifikovalo jedinú osobu, ktorá má právo rozhodnúť.

Prehľad a odvolanie spárovaného

Osobné spárované agenty človeka sú vypísané na /settings/security, každý so štítkom a ovládaním na odvolanie. Vlastník alebo správca organizácie vidí každé poverenie v organizácii na /admin/security?tab=programs — ako sa volá, čo smie, či je živé a čí účet si požičiava — a môže ktorékoľvek odvolať. Osobný zoznam zostáva len pre vlastníka: zoznam živých poverení je zoznam opôr, nie všeobecné čítanie.

Zápisy urobené cez poverenie sú pripísané človeku, ktorý ho požičal, a v metadátach auditu nesú identifikátor poverenia. Záznam tak dokáže rozlíšiť vlastnú úpravu osoby od úpravy, ktorú za ňu urobil jej agent.

Čo ešte nie je dostupné

Hovoríme to otvorene, pretože medzera medzi možnosťami protokolu a možnosťami daného servera je miesto, kde dokumentácia zvyčajne klame:

• Chat, kanály, behy a správa agentov sa cez MCP nesprístupňujú.
• Program pripraví newsletter a odošle ho človek: nič neodosiela, neplánuje ani nemaže kampaň a samotný e-mail sa píše v dizajnéri.
• Prepájanie a zlučovanie kontaktov, zmeny schémy CRM, importy a nastavenie kanálov zostávajú na človeku v prehliadači.
• Prepínač pripájania je nastavenie na úrovni organizácie. Nastavenia na úrovni tímu a osobné prepisy zatiaľ nemôže nastaviť ani tím, ani osoba.