MCP a propojené nástroje

Propojte Nessie s MCP servery a sparujte externího agenta, aby mohl v Nessie pracovat jako vy.

Co je MCP

Model Context Protocol je malá, otevřená konvence pro popisování nástrojů jazykovému modelu a pro jejich volání. Server oznámí, co umí — seznam pojmenovaných nástrojů, každý s JSON schématem svých argumentů — a klient tento seznam zjistí a nástroje volá jménem modelu. Je záměrně prostý: přínos spočívá v tom, že jedna integrace napsaná jednou funguje se všemi modely a všemi produkty, které tento protokol mluví.

Nessie stojí na obou stranách

Stojí za to být přesný, protože ty dvě poloviny se snadno pletou a žijí na záměrně odlišných cestách.

• Odchozí. Nessie je MCP klient. Připojujete servery, které provozuje někdo jiný, a nástroje, které vystavují, se stanou nástroji, které vaši agenti mohou používat. Rozhraní pro správu je /api/mcp/*.
• Příchozí. Nessie je také MCP server. Agent běžící jinde — Claude Code nebo Codex na počítači vývojáře — může sáhnout do vašich nástěnek a dokumentů. Tento endpoint je POST /mcp, záměrně mimo /api, aby se dva protichůdné významy nelišily jen o jeden segment cesty.

Připojení MCP serveru k Nessie

Položky katalogu a instance

Jsou tu dva objekty a rozdíl mezi nimi je důležitý:

• Položka katalogu je definice serveru — jeho název, přenosový protokol a způsob ověřování. Zapíše se jednou a lze ji sdílet.
• Instance je tato položka nainstalovaná v jednom rozsahu, s přihlašovacími údaji, které se k ní dostanou. Instalace stejné položky pro dva různé týmy vytvoří dvě instance.

Většina lidí se žádného z nich nedotkne přímo. Vstupní bod v administraci je aplikační obchod na /admin/apps: prochází stejný katalog se skrytými připojovacími údaji a Connect u výpisu vytvoří instanci. Operátoři, kteří chtějí surové objekty, používají /api/mcp/catalog a /api/mcp/instances.

Pokud server v katalogu ještě není, POST /api/mcp/discover přijme URL a vrátí, co server o sobě říká, a POST /api/mcp/library/import stáhne položku z veřejné knihovny serverů. Připojení při prvním spuštění lze vytvořit přímo z URL přes POST /api/apps/custom.

Přenosové protokoly

Nessie se k vzdáleným serverům připojuje přes HTTP. Fungují dva přenosy: streamable HTTP (aktuální přenos MCP) a starší přenos HTTP+SSE. Zvolte http, pokud server nenabízí jen sse.

Přenos stdio se odmítá u konektorů, které sami píšete. stdio znamená, že MCP server je lokální proces, který spouští hostitel, a spouštět libovolné programy uvnitř serveru Nessie není něco, co může operátor smysluplně zkontrolovat. Servery publikované pouze jako balíček pro lokální běh se ze knihovních importů ze stejného důvodu vynechávají. Hodnota ws v poli protokolu existuje, ale není implementována — připojení, které ji použije, selže ve chvíli, kdy se ho Nessie pokusí otevřít.

Jak se Nessie ověřuje vůči serveru

Položka katalogu deklaruje jednu z pěti metod: none, api_key, bearer, basic nebo oauth2.

api_key je vkládání hlavičky a položka uvádí, kterou hlavičku a jaký prefix — takže Authorization: Bearer …, X-API-Key: … a X-Auth-Token: Token … jsou tatáž metoda nastavená jinak. Klíč se vloží jednou přes POST /api/mcp/instances/:instanceId/secret a už se nikdy nedá přečíst; žádná odpověď z endpointů instancí neobsahuje odkaz na přihlašovací údaj.

oauth2 přichází ve dvou podobách. Server s pevnými koncovými body je má v položce katalogu. Server, který publikuje standardní metadata, nevyžaduje nic nastavovat: Nessie přečte dokumenty chráněného zdroje a autorizačního serveru a vytvoří si klienta buď dynamickou registrací klienta, nebo přes dokument metadat ID klienta, který publikuje na vlastní well-known cestě. Tak či tak je handshake POST /api/mcp/instances/:instanceId/oauth/start, následovaný přesměrováním poskytovatele zpět na GET /api/mcp/oauth/callback. Stavový token je jednorázový, držen v databázi a platný deset minut, a PKCE se vždy používá.

Jedno pravidlo lidi překvapí: ani vlastník organizace nemůže připojit osobní nebo OAuth token k někomu jinému. Sdílený přihlašovací údaj je možný jen u položky s API klíčem, která byla jako takový ověřena; cokoli jiného se odmítne. Údaj, který patří osobě, zůstává údajem, který patří té osobě.

Kde jsou přihlašovací údaje uloženy

Tajemství konektorů a balíčky OAuth tokenů jsou uloženy ve vaší vlastní databázi Postgres, v obálkách AES-256-GCM vázaných na účel, pod nezávisle verzovaným šifrovacím klíčovým kruhem nasazení, a adresovány jsou jen neprůhlednými odkazy secret_*. Záměrně nejsou v externím trezoru tajemství, ve kterém jsou ostatní tajemství Nessie. Produkční nasazení, které nemá nastavený šifrovaný úložiště, se odmítne spustit, místo aby dokončilo handshake OAuth, který by pak stejně zahodilo.

Kam připojení dosahuje

Instance se instaluje v jednom ze šesti rozsahů: system, organization, project, team, channel nebo user. Rozsah je pevný strop toho, které běhy ji mohou použít, a granty ho mohou jen dál zužovat, nikdy rozšiřovat. Konektor, který jste nainstalovali svým vlastním účtem, se tak nemůže tiše stát konektorem pro celou organizaci.

Kdo smí instalovat kam, má stejný tvar: vlastníci a správci organizace spravují instalace v libovolném rozsahu; každý ostatní instaluje konektory do svého vlastního rozsahu user a vidí sdílené instalace, na které má nárok.

Jak dát agentovi nástroj

Připojení serveru nepředává jeho nástroje nikomu. Když se instance nainstaluje, Nessie ji prozkoumá a každý nástroj, který nabízí, promítne do registru nástrojů. Ten administrace ukazuje na /admin/advanced/tools — vestavěné nástroje, nástroje MCP, nástroje balíčků a nástroje executoru v jednom seznamu, každý se svým zdrojem a stavem.

Promítnutý nástroj má jeden ze tří stavů: active, pending_review nebo disabled. Nástroje ze sdílené instalace přicházejí jako pending_review a musí být na této stránce schváleny, než je agent uvidí. Nástroje z vaší vlastní instalace v rozsahu user jsou aktivní hned, protože jediná osoba, která je vystavena, jste vy. Kontrola se opakuje; není to jednorázový obřad. Pokud pozdější prozkoumání zjistí, že popis nebo schéma nástroje se změnilo, vrátí se do pending_review a přestane být nabízen, dokud se někdo na změnu nepodívá.

O tom, které agenty smějí aktivní nástroj volat, se rozhoduje jedním ze dvou způsobů:

• Připojení vytvořené přes aplikační obchod vyžaduje explicitní grant. Agent dostane nástroj jen tehdy, když ho grant jmenuje, a grant se kontroluje proti aktuálnímu otisku nástroje, takže změněný nástroj potřebuje nové rozhodnutí.
• Jinak je nástroj ve výchozím stavu zapnutý pro agenty v dosahu jeho rozsahu a jednotlivé agenty lze vypnout na detailním panelu nástroje.

Grant jmenuje přesně jednoho principála — roli nebo agenta, nikdy obojí — a zákaz přebíjí povolení. U připojení v rozsahu user se otázka vůbec nekladě: kterýkoli agent, se kterým ta osoba mluví, ho může použít, a jediná věc, která ho odebere, je výslovné vypnutí.

Jedna věc, kterou je snadné hledat na špatném místě: /settings/accounts v administraci jsou připojené účty — Slack, poštovní schránky, předplatná modelů a odkazy OAuth na Linear, Jira, GitHub a Trello, které pohánějí externí nástěnky. Konektory MCP jsou na /admin/apps a nástroje, které vytvářejí, jsou na /admin/advanced/tools.

Schvalovací brány u volání nástrojů

Některá volání nástrojů se zastaví a čekají na člověka. Když se tak stane, běh neselže: volání se zmrazí — jméno nástroje, hash jeho argumentů a dost stavu k obnovení — a žádost o schválení se objeví na /api/approvals, aby ji někdo zodpověděl. Obnovení je idempotentní, takže zdvojené schválení nemůže zavolat nástroj dvakrát. Rozhodující osoba vidí omezený souhrn toho, co se žádá; přesné argumenty a původní běh zůstávají na serveru.

Existují dvě odlišné brány a nastavují se jinak.

• Strukturální brány jsou vlastností některých vestavěných nástrojů a nejdou nastavit. Odeslání pošty z vlastní schránky agenta nebo z připojené, odeslání konceptu Gmailu, odpojení poštovního účtu, vytvoření, změna nebo zrušení události v kalendáři a akce v prohlížeči, která by zapisovala na web, do kterého prohlížeč není přihlášen, jsou všechny takto bránovány. Na odpověď mají 24hodinové okno místo obvyklých 30 minut.
• Politické brány pocházejí z pravidel zásad na dvojici tool/invoke. Pravidlo, které volání povoluje, může nést requiresApproval, a bez ověřeného schválení vyhodnocení vrací APPROVAL_REQUIRED místo spuštění. Pravidla se vyhodnocují nejdřív zákazy a řadí se podle rozsahu.

Která obrazovka administrace zapisuje pravidlo zásad requiresApproval pro nástroj — datový model i vynucení jsou na místě, ale nepodařilo se nám ověřit obrazovku, která takové pravidlo zapisuje.

Připojení externího agenta k Nessie

Opačný směr. Nessie provozuje vlastní MCP server na POST /mcp, přes streamable HTTP, a je bezstavový: každé volání nese vlastní přihlašovací údaj a samo určuje svůj účet, takže není žádná relace, kterou by bylo třeba připnout k jedné replice. ChatGPT, Claude, Claude Code, Codex nebo agent na notebooku nějakého člověka mohou pracovat s vašimi boardy, dokumenty a zákazníky z kteréhokoli nástroje, který ta osoba už používá. Podrobný postup pro každou aplikaci je v Připojení ChatGPT, Claude a dalších AI aplikací.

Co vlastně je spárovaný přihlašovací údaj

Tohle musíte pochopit správně, protože nabízený mentální model — API klíč s přidanými oprávněními — je špatný.

Spárovaný přihlašovací údaj nikdy není identitou. Pojmenovává člověka a každé volání nástroje běží jako tento člověk, proti stejným servisním funkcím, které volají HTTP rozhraní. Agent proto nemůže dosáhnout na nic, na co by se osoba, která mu ho půjčila, nedostala kliknutím. Rozsahy mohou dosah jen zužovat; neexistuje žádný rozsah, který by ho rozšířil.

Platnost se ověřuje při každém jednotlivém volání, nikdy se nevěří tokenu: zrušení, expirace, verze tokenu uživatele, jeho členství v organizaci a jeho aktuální role. Degradace, deaktivace nebo „odhlásit mě všude“ se projeví při dalším volání agenta, ne až na konci platnosti přihlašovacího údaje.

Token je neprůhledný, s prefixem nag1_, uložen jen jako hash SHA-256 a platí 90 dní. Na jakékoli trase jiné než endpoint MCP je odmítnut konkrétní odpovědí 403. Jeho předložení jinde není částečný úspěch, který by bylo třeba zkusit znovu, a právě to zajišťuje, že „půjčil jsem agentovi své nástěnky“ neznamená „půjčil jsem mu svůj účet“.

Dva způsoby připojení

Aplikace, která umí otevřít prohlížeč — ChatGPT, Claude, Claude Code, Codex — používá profil autorizace MCP: OAuth 2.1 s PKCE (S256), dynamickou registraci klienta na POST /mcp/oauth/register, obnovovací tokeny a indikátory zdrojů. Aplikace pošle osobu na /settings/security, ta zvolí, co smí dělat a které z jejích týmů dosáhne, a prohlížeč se vrátí do aplikace s kódem. Její přístupový token platí hodinu a obnovuje se; připojení žije 90 dní.

Agent pro příkazový řádek neovládá prohlížeč a nemůže hostit callback URL, takže se páruje přes device authorization grant (RFC 8628).

1. Agent zavolá POST /mcp/auth/device s clientName a scopes, které chce. Dostane zpět device_code, krátký user_code, verification_uri a verification_uri_complete s kódem už v dotazu, plus interval dotazování interval a expires_in. Vytiskne URI.
2. Osoba otevře tu URI, když je přihlášena, na /settings/security. Vidí, který agent se ptá, za jaký účet by pracoval, do kdy a přesně co by mohl dělat — a zvolí Povolit nebo Nepovolit.
3. Agent se dotazuje POST /mcp/auth/token s deviceCode, respektuje authorization_pending, slow_down, expired_token a access_denied. Při úspěchu dostane { access_token, token_type, scope, expires_at }.

V obou případech je tu krok pro člověka, protože přihlašovací údaj dědí oprávnění osoby, takže se člověk musí rozhodnout, že mu je půjčí. Nic tu nevzniká z ničeho. Připojení lze navíc vypnout pro celou organizaci na /admin/security?tab=programs a tato odpověď se kontroluje, když někdo připojení povoluje, ne když agent nějaké zahajuje.

Objevování

Neověřený POST /mcp odpoví 401 s hlavičkou WWW-Authenticate, která ukazuje na /.well-known/oauth-protected-resource (RFC 9728) a jmenuje tento původ jako autorizační server. Jeho metadata na /.well-known/oauth-authorization-server (RFC 8414) pojmenovávají endpointy registrace, autorizace, tokenu a odvolání. Ten řetězec je vše, co klient potřebuje, jakmile má adresu. Aby agent našel adresu z domény, přečte /.well-known/ai-catalog.json, který odkazuje na Server Card na /mcp/server-card (MCP Server Cards, SEP-2127). Endpointy device grantu jsou uvedeny v dokumentu chráněného zdroje pod x-nessie-device-authorization.

Nasazení může odpovídat také na druhé, kratší adrese: Nessie Cloud proxuje https://nessie.works/mcp na API a klient, který přišel touto cestou, dostane zpět tuto adresu jako zdroj, zatímco přihlašování zůstává na API. Přesměrování by nestačilo, protože klient odmítne metadata, která jmenují jinou adresu, než jakou dostal. Provozovatel tyto původy uvádí v NESSIE_MCP_ALIAS_ORIGINS.

Rozsahy a nástroje

Rozsahy jsou záměrně hrubé — rozsah, který nikdo nedokáže vysvětlit, nikdo nenastaví správně. Připojení, které dosahuje na více týmů, je jmenuje přes nessie_team_list a každý další nástroj pak uvádí svůj teamId.

Volání bez rozsahu, který potřebuje, se vrátí jako výsledek nástroje, který jmenuje rozsah, o který je třeba požádat, ne jako chyba přenosu. Model tak může nahlásit něco užitečného, místo aby opakoval pokus proti zdi.

Pro externí trackery neexistuje samostatná rodina nástrojů. Nástěnka je nástěnka, ať její úkoly vznikly v Nessie, nebo jsou zrcadleny z Linear, Jira, GitHubu nebo Trello. Jedna sada nástrojů proto pokrývá obojí a každý úkol říká, odkud je. Liší se pouze zápis: nástěnka zrcadlená ze zdroje jen pro čtení zápis odmítne slovy, že úkol vlastní jiný systém a opakování nepomůže.

Publikování dokumentu je schválení, nikdy ne rozsah

Agenti navrhují; publikuje člověk. Pravidlo se pro agenty Nessie vynucuje tak, že se agentský aktér úplně odmítne. Spárovaný přihlašovací údaj se ale řeší jako osoba, takže toto odmítnutí ho nemůže zachytit. Brána musí být jinde.

Proto nessie_doc_publish nepublikuje. Otevře schvalovací žádost knowledge.page.publish — tu samou, jakou otevírá agent Nessie — a vrátí { status: "awaiting_approval", approvalId }. Dotaz vrací tu samou žádost místo toho, aby otevřel druhou. O rozhodnutí se rozhoduje stejně jako každé jiné rozhodnutí o publikování v Nessie: člověk, o tom dokumentu, v okamžiku, kdy existuje.

Záměrně neexistuje žádný rozsah pro publikování. Jeden byl — zaškrtnutí při párování říkající, že tento agent smí publikovat — a byl zrušen. Jednou provždy a na devadesát dní rozhodoval o otázce, kterou produkt všude jinde klade u každého dokumentu, a rozhodoval ji dřív, než dokument existoval. Osoba, která to zaškrtla, tak nemohla vědět, co schvaluje k publikování. nessie_doc_publish potřebuje documents_write, protože žádat není zadarmo: čte stránku a klade rozhodnutí před někoho. Ten rozsah ale nedává nic k samotnému publikování.

Na žádosti se zaznamenávají dvě identity a rozdíl je podstatný. Žadatelem je přihlašovací údaj, nikdy člověk, jehož jménem jedná. Požadovaným schvalovatelem je ten člověk a jen on smí odpovědět. Kdyby žádost jmenovala osobu jako žadatele, pravidlo, které brání tomu, aby kdokoli schvaloval vlastní žádost, by vyloučilo jediného člověka, který má právo rozhodnout.

Přehled a odvolání spárovaného přístupu

Spárované agenty osoby jsou uvedeny na /settings/security, každý s označením a ovládacím prvkem pro odvolání. Vlastník nebo správce organizace vidí každý přihlašovací údaj v organizaci na /admin/security?tab=programs — jak se jmenuje, co smí dělat, zda je aktivní a čí účet si půjčuje — a může kterýkoli z nich odvolat. Osobní seznam zůstává jen pro vlastníka: seznam živých přihlašovacích údajů je seznam opěrných bodů, ne obecné čtení.

Zápisy provedené přes přihlašovací údaj se přičítají člověku, který ho půjčil, a nesou id přihlašovacího údaje v metadatech auditu. Záznam tak dokáže rozlišit vlastní úpravu osoby od úpravy, kterou za ni provedl její agent.

Co zatím není dostupné

Říkáme to výslovně, protože mezera mezi schopnostmi protokolu a schopnostmi daného serveru je místo, kde dokumentace obvykle lže:

• Chat, kanály, běhy a správa agentů nejsou přes MCP vystaveny.
• Program připraví newsletter a člověk ho odešle: nic newsletter neodesílá, neplánuje ani nemaže kampaň, a samotný e-mail se píše v návrháři.
• Propojování a slučování kontaktů, změny schématu CRM, importy a nastavení kanálů zůstávají u člověka v prohlížeči.
• Přepínač připojování je nastavení na úrovni organizace. Nastavení na úrovni týmu a osobní přepsání zatím nemůže nastavit ani tým, ani osoba.