MCP in povezana orodja

Povežite Nessie s strežniki MCP in združite zunanjega agenta, da lahko dela v Nessie v vašem imenu.

Kaj je MCP

Model Context Protocol je majhna, odprta konvencija za opisovanje orodij jezikovnemu modelu in za klicanje teh orodij. Strežnik razglasi, kaj zmore — seznam poimenovanih orodij, vsako s shemo JSON za svoje argumente — odjemalec ta seznam odkrije in orodja kliče v imenu modela. Namenoma je skromen: vrednost je v tem, da ena enkrat napisana integracija deluje z vsakim modelom in vsakim izdelkom, ki ta jezik govori.

Nessie je na obeh straneh

To je vredno natančno povedati, ker se obe polovici zlahka zamenjata, živita pa na namenoma različnih poteh.

• Odhodno. Nessie je MCP odjemalec. Povežete strežnike, ki jih vodi nekdo drug, orodja, ki jih ti izpostavijo, pa postanejo orodja, ki jih vaši agenti lahko uporabljajo. Upravljavska površina je /api/mcp/*.
• Dohodno. Nessie je tudi MCP strežnik. Agent, ki teče drugje — Claude Code ali Codex na razvijalčevem računalniku — lahko kliče vaše table in dokumente. To krajišče je POST /mcp, namenoma zunaj /api, da dva nasprotna pomena nista drug od drugega oddaljena le za en segment poti.

Povezovanje strežnika MCP z Nessiejem

Vnosi v katalogu in primerki

Obstajata dva predmeta, razlika med njima je pomembna:

• Vnos v katalogu je opis strežnika — njegovo ime, prenos in način preverjanja pristnosti. Zapisan je enkrat in ga je mogoče deliti.
• Primerek je ta vnos, nameščen na eni ravni, z vpisnimi podatki, ki vodijo do strežnika. Namestitev istega vnosa za dve različni ekipi ustvari dva primerka.

Večina ljudi se ne dotakne nobenega neposredno. Vhod v skrbniškem vmesniku je aplikacijska trgovina na /admin/apps: prebrska isti katalog, podrobnosti povezave so skrite, gumb Connect na seznamu pa ustvari primerek. Upravljavci, ki želijo surove predmete, uporabljajo /api/mcp/catalog in /api/mcp/instances.

Če strežnika še ni v katalogu, POST /api/mcp/discover sprejme naslov in prebere, kaj strežnik sam o sebi pove, POST /api/mcp/library/import pa potegne vnos iz javne knjižnice strežnikov. Povezavo ob prvem zagonu lahko ustvarite tudi neposredno iz naslova prek POST /api/apps/custom.

Prenosi

Nessie se povezuje z oddaljenimi strežniki prek HTTP. Delujeta dva prenosa: pretočni HTTP (trenutni prenos MCP) in starejši prenos HTTP+SSE. Izberite http, razen če strežnik ponuja samo sse.

Prenos stdio je za konektorje, ki jih avtorizirate sami, zavrnjen. stdio pomeni, da je strežnik MCP lokalni proces, ki ga zažene gostitelj, zaganjanje poljubnih programov znotraj strežnika Nessie pa upravljavec ne more smiselno pregledati. Strežniki, objavljeni samo kot paket za lokalni zagon, so iz uvozov iz knjižnice izločeni iz istega razloga. Vrednost ws v polju protokola obstaja in ni implementirana — povezava, ki jo uporabi, pade, ko jo Nessie poskuša odpreti.

Kako se Nessie preverja pri strežniku

Vnos v katalogu razglasi eno od petih metod: none, api_key, bearer, basic ali oauth2.

api_key je vstavljanje glave, vnos pa pove, katera glava in kakšna predpona — tako so Authorization: Bearer …, X-API-Key: … in X-Auth-Token: Token … ista metoda, samo drugače nastavljena. Ključ se enkrat prilepi s POST /api/mcp/instances/:instanceId/secret in ga ni mogoče več prebrati; noben odgovor poti primerkov ne vsebuje sklica na poverilnico.

oauth2 pride v dveh oblikah. Strežnik s fiksnimi krajišči jih ima v svojem vnosu v katalogu. Strežnik, ki objavlja standardne metapodatke, ne potrebuje ničesar nastavljati: Nessie prebere dokumenta zaščitenega vira in strežnika za avtorizacijo ter si sam ustvari odjemalca prek dinamične registracije odjemalca ali prek dokumenta metapodatkov ID-ja odjemalca, ki ga objavi na svoji poti well-known. Rokovanje je v obeh primerih POST /api/mcp/instances/:instanceId/oauth/start, ki mu sledi preusmeritev ponudnika nazaj na GET /api/mcp/oauth/callback. Žeton stanja se uporabi samo enkrat, hrani se v bazi in velja deset minut, PKCE pa se vedno uporablja.

Eno pravilo preseneti marsikoga: tudi lastnik organizacije ne more pripeti osebnega ali OAuth žetona nekomu drugemu. Skupna poverilnica je mogoča samo za vnos z metodo api_key, ki je bil kot tak preverjen; vse drugo je zavrnjeno. Poverilnica, ki pripada osebi, ostane poverilnica te osebe.

Kje so shranjene poverilnice

Skrivnosti konektorjev in paketi OAuth žetonov se shranjujejo v vaši lastni bazi PostgreSQL, v namensko vezanih ovojnicah AES-256-GCM pod neodvisno različiciranim obročem šifrirnih ključev namestitve, do njih pa se dostopa samo prek neprozornih sklicev secret_*. Namerno niso v zunanjem trezorju skrivnosti, ki hrani druge skrivnosti Nessieja. Produkcijska namestitev, ki ni nastavila šifriranega skladišča, se raje ne zažene, kot da bi dokončala rokovanje OAuth, ki bi ga nato izgubila.

Kam sega povezava

Primerek je nameščen na enem od šestih obsegov: system, organization, project, team, channel ali user. Obseg je trda meja, katere zagoni lahko uporabijo primerek, dovoljenja pa jo lahko samo še zožijo, nikoli ne razširijo — tako konektor, ki ste ga namestili s svojim računom, ne more tiho postati konektor za vso organizacijo.

Kdo sme nameščati kje, sledi isti obliki: lastniki in skrbniki organizacije upravljajo namestitve na katerem koli obsegu; vsak drug namešča konektorje na svojem osebnem obsegu user in lahko vidi skupne namestitve, do katerih ima dostop.

Dajanje orodja agentu

Povezava strežnika ne izroči njegovih orodij nikomur. Ko je primerek nameščen, ga Nessie preveri in vsako orodje, ki ga oglasi, prenese v register orodij — ta je tisto, kar skrbniški vmesnik prikaže na /admin/advanced/tools: vgrajena orodja, orodja MCP, orodja paketov in orodja izvajalca na enem seznamu, vsako z virom in stanjem.

Preneseno orodje ima eno od treh stanj: active, pending_review ali disabled. Orodja iz namestitve na skupnem obsegu pridejo kot pending_review in jih je treba odobriti na tej strani, preden jih agent vidi; orodja iz vaše namestitve na obsegu user so takoj aktivna, ker ste v njej edina izpostavljena oseba. Pregled je ponavljajoč, ne enkraten obred: če kasnejše preverjanje pokaže, da se je opis ali shema orodja premaknila, se vrne v pending_review in ni več ponujeno, dokler nekdo ne pogleda spremembe.

Kateri agenti smejo klicati aktivno orodje, se odloča na dva načina:

• Povezava, ustvarjena prek aplikacijske trgovine, zahteva izrecno dovoljenje. Agent dobi orodje samo, kadar ga dovoljenje imenuje, dovoljenje pa se preveri glede na trenutni prstni odtis orodja, zato je spremenjeno orodje potrebno nove odločitve.
• Sicer je orodje privzeto vklopljeno za agente, ki dosežejo njegov obseg, posamezne agente pa lahko izklopite na podrobnostni plošči orodja.

Dovoljenje imenuje natanko enega nosilca — vlogo ali agenta, nikoli obojega — in zavrnitev premaga dovolitev. Pri povezavi z obsegom user vprašanje sploh ne nastane: lahko kliče vsak agent, s katerim se oseba pogovarja, edina stvar, ki ga zadrži, pa je izrecno izklopljeno stikalo.

Nekaj, kar je lahko iskati na napačnem mestu: /settings/accounts v skrbniškem vmesniku so povezani računi — Slack, poštni predali, naročnine na modele in povezave OAuth z Linear, Jira, GitHub in Trello, ki podpirajo zunanje table. Konektorji MCP so na /admin/apps, orodja, ki jih ustvarijo, pa na /admin/advanced/tools.

Zapore odobritve pri klicih orodij

Nekateri klici orodij se ustavijo in počakajo na osebo. Ko se, zagon ne spodleti: klic je zamrznjen — ime orodja, zgoščena vrednost njegovih argumentov in dovolj stanja za nadaljevanje — zahteva odobritve pa se pojavi na /api/approvals, kjer nanjo nekdo odgovori. Nadaljevanje je idempotentno, zato podvojena odobritev ne more izvesti klica dvakrat. Oseba, ki odloča, vidi omejen povzetek tega, o čemer se sprašuje; natančni argumenti in izvorni zagon ostanejo na strežniku.

Obstajata dve različni zapori, nastavljeni na različen način.

• Strukturne zapore so lastnost nekaterih vgrajenih orodij in niso nastavljive. Pošiljanje pošte iz predala agenta ali iz povezanega predala, pošiljanje osnutka Gmaila, odklop poštnega računa, ustvarjanje, spreminjanje ali preklic koledarskega dogodka ter dejanje brskalnika, ki bi pisalo na spletno mesto, v katerem brskalnik ni prijavljen, so vsi zaprti na ta način. Za odgovor imajo 24-urno okno namesto običajnih 30 minut.
• Pravilniške zapore prihajajo iz pravil politike na paru tool/invoke. Pravilo, ki dovoli klic, lahko nosi requiresApproval, brez preverjene odobritve pa ocena vrne APPROVAL_REQUIRED namesto da bi zagnala klic. Pravila se ocenjujejo najprej za zavrnitve in so urejena po obsegu.

Kateri zaslon v skrbniškem vmesniku napiše pravilo politike requiresApproval za orodje — model podatkov in uveljavitev sta na mestu, vendar nismo mogli potrditi zaslona, ki takšno pravilo zapiše.

Povezovanje zunanjega agenta z Nessiejem

Druga smer. Nessie ima svoj MCP strežnik na POST /mcp, prek pretočnega HTTP, in je brez stanja: vsak klic nosi svojo poverilnico in si sam določi akterja, zato ni seje, ki bi odjemalca pripela na eno repliko. ChatGPT, Claude, Claude Code, Codex ali agent na čigavem koli prenosniku lahko delajo z vašimi tablami, dokumenti in strankami znotraj orodja, ki ga ta oseba že uporablja. Podroben korak za vsako aplikacijo je v Povezava ChatGPT, Claude in drugih aplikacij z umetno inteligenco.

Kaj je dejansko seznanjena poverilnica

To je del, ki ga je treba prav razumeti, ker je očitni miselni model — API ključ z dovoljenji — napačen.

Seznanjena poverilnica nikoli ni identiteta. Imenuje človeka, vsak klic orodja pa teče kot ta človek, prek istih servisnih funkcij, ki jih kličejo HTTP poti. Agent zato ne more doseči ničesar, česar oseba, ki mu je posodila dostop, ne bi mogla doseči s klikom. Obsegi ta doseg vedno samo zožijo; ni obsega, ki bi ga razširil.

Veljavnost se ponovno prebere ob vsakem klicu, nikoli se ne jemlje iz žetona: preklic, potek, različica žetona uporabnika, članstvo v organizaciji in trenutna vloga. Degradacija, deaktivacija ali „odjavi me povsod“ učinkuje pri naslednjem klicu agenta, ne šele ob poteku poverilnice.

Žeton je neprozoren, ima predpono nag1_, hrani se samo kot zgoščena vrednost SHA-256 in živi 90 dni. Na katerikoli poti razen končne točke MCP je zavrnjen s posebnim 403 — predstavitev drugje ni delna uspešnost, ki bi jo bilo treba ponoviti, in prav to preprečuje, da bi „agentu sem posodil svoje table“ pomenilo „posodil sem mu svoj račun“.

Dva načina povezave

Aplikacija, ki lahko odpre brskalnik — ChatGPT, Claude, Claude Code, Codex — uporablja profil avtorizacije MCP: OAuth 2.1 s PKCE (S256), dinamično registracijo odjemalca na POST /mcp/oauth/register, osveževalne žetone in kazalce virov. Aplikacija osebo pošlje na /settings/security, ta izbere, kaj sme aplikacija početi in do katerih svojih ekip sme dostopati, brskalnik pa se vrne v aplikacijo s kodo. Dostopni žeton velja eno uro in se osvežuje; povezava živi 90 dni.

Agent v ukazni vrstici ne nadzoruje brskalnika in ne more gostiti povratnega URL-ja, zato se seznani z odobritvijo naprave (RFC 8628).

1. Agent pokliče POST /mcp/auth/device z clientName in scopes, ki jih želi. Dobi nazaj device_code, kratek user_code, verification_uri in verification_uri_complete s kodo že v poizvedbi ter interval poizvedovanja interval in expires_in. Izpiše URI.
2. Oseba, prijavljena, odpre ta URI na /settings/security. Vidi, kateri agent sprašuje, v imenu katerega računa bi deloval, do kdaj in natančno, kaj bi lahko počel — in izbere Dovoli ali Ne dovoli.
3. Agent poizveduje na POST /mcp/auth/token z deviceCode in upošteva authorization_pending, slow_down, expired_token in access_denied. Ob uspehu prejme { access_token, token_type, scope, expires_at }.

V vsakem primeru je vmes korak človeka, ker poverilnica podeduje pravice osebe, zato se mora oseba odločiti, da jo posodi. Tu nič ne izda dostopa iz nič. Povezovanje je mogoče za celotno organizacijo izklopiti na /admin/security?tab=programs, ta odgovor pa se preveri, ko nekdo dovoli povezavo, ne ko agent začne eno.

Odkrivanje

Neavtenticirani POST /mcp odgovori z 401 in glavo WWW-Authenticate, ki kaže na /.well-known/oauth-protected-resource (RFC 9728), ta pa navaja ta izvor kot strežnik za avtorizacijo; njegovi metapodatki na /.well-known/oauth-authorization-server (RFC 8414) navajajo krajišča za registracijo, avtorizacijo, žeton in preklic. Ta veriga je vse, kar odjemalec potrebuje, ko ima naslov. Da agent iz domene najde naslov, prebere /.well-known/ai-catalog.json, ki imenuje Server Card na /mcp/server-card (MCP Server Cards, SEP-2127). Krajišča naprave za odobritev so navedena v dokumentu zaščitenega vira pod x-nessie-device-authorization.

Namestitev lahko odgovarja tudi na drugem, krajšem naslovu: https://nessie.works/mcp, ki ga Nessie Cloud posreduje API-ju. Odjemalec, ki je prišel tako, dobi nazaj ta naslov kot vir, prijava pa ostane pri API-ju. Preusmeritev ne bi zadostovala, ker odjemalec zavrne metapodatke, ki navajajo drug naslov od tistega, ki mu je bil dan. Upravljavec te izvore navede v NESSIE_MCP_ALIAS_ORIGINS.

Obsegi in orodja

Obsegi so namenoma grobi — obseg, ki ga nihče ne zna razložiti, ga nihče ne nastavi pravilno. Povezava, ki seže do več ekip, jih našteje z nessie_team_list, vsako drugo orodje pa nato navede svoj teamId.

Klic brez obsega, ki ga potrebuje, se vrne kot rezultat orodja, ki navede obseg, za katerega je treba prositi, ne kot napaka prenosa, tako lahko model poroča nekaj uporabnega, namesto da bi ponavljal ob isti oviri.

Za zunanje sledilnike ne obstaja ločena družina orodij. Tabla je tabla, ne glede na to, ali njene naloge izvirajo v Nessieju ali so zrcaljene iz Linear, Jira, GitHub ali Trello, zato en nabor orodij pokrije oba, vsaka naloga pa pove, od kod je. Razlika je pri pisanju: tabla, zrcaljena iz vira, ki je samo za branje, zavrne zapis z besedo, pri čemer agentu pove, da ima drug sistem nalogo v lasti in da ponovno poskušanje ne bo pomagalo.

Objava dokumenta je odobritev, nikoli obseg

Agenti pripravljajo osnutke; objavi oseba. To pravilo za lastne agente Nessieja uveljavi tako, da agentovega akterja zavrne brez pogojev — ampak seznanjena poverilnica se razreši kot oseba, zato te zavrnitve ne more ujeti. Zapora mora biti nekje drugje.

Zato nessie_doc_publish ne objavi ničesar. Odpre odobritev knowledge.page.publish — isto, ki jo odpre agent Nessieja — in vrne { status: "awaiting_approval", approvalId }. Ponavljajoče poizvedovanje vrne isto zahtevo in ne odpre druge. Odločitev se sprejme na enak način kot vse druge odločitve o objavi v Nessieju: oseba, o tem dokumentu, v trenutku, ko obstaja.

Namenoma ni nobenega obsega za objavo. Nekoč je obstajal — potrditev ob seznanjanju, ki je rekla, da ta agent sme objavljati — in ukinjen je bil. Enkrat in za devetdeset dni je odločal o vprašanju, ki ga izdelek drugod vedno zastavlja za vsak dokument posebej, in je odločil pred obstojem dokumenta, zato oseba, ki je potrdila, ni mogla vedeti, kaj bo objavljeno. nessie_doc_publish potrebuje documents_write, ker prošnja ni brezplačna — prebere stran in osebi postavi odločitev pred oči — ta obseg pa ne daje ničesar glede objave.

Na zahtevi se zabeležita dve identiteti, razlika med njima pa je odločilna. Zahtevnik je poverilnica, nikoli oseba, v imenu katere deluje. Zahtevani odobritelj je ta oseba in samo ona lahko odgovori. Če bi zahteva navedla osebo kot zahtevnika, bi pravilo, ki preprečuje, da bi kdo odobril svojo zahtevo, diskvalificiralo edino osebo, ki sme odločati.

Pregled in preklic seznanjenega

Seznanjeni agenti osebe so navedeni na /settings/security, z oznako in gumbom za preklic pri vsakem. Lastnik ali skrbnik organizacije vidi vsako poverilnico v organizaciji na /admin/security?tab=programs — kako se imenuje, kaj sme početi, ali je živa in čigav račun si izposoja — in lahko katerokoli prekliče. Osebni seznam ostane samo za lastnika: seznam živih poverilnic je seznam opornih točk, ne splošno branje.

Zapisi, narejeni prek poverilnice, se pripišejo človeku, ki si je poverilnico izposodil, in nosijo id poverilnice v metapodatkih revizije, tako lahko dnevnik loči osebno urejanje od tistega, ki ga je zanjo naredil agent.

Kar še ni na voljo

Odkrito, ker je prav razlika med zmogljivostmi protokola in zmogljivostmi danega strežnika tam, kjer dokumentacija običajno laže:

• Klepet, kanali, zagoni in upravljanje agentov niso izpostavljeni prek MCP.
• Agent pripravi e-novico, oseba pa jo pošlje: nič ne pošlje, ne načrtuje in ne izbriše kampanje, samo e-poštno sporočilo je napisano v oblikovalniku.
• Povezovanje in združevanje stikov, spremembe sheme CRM, uvozi in nastavitev kanalov ostanejo pri osebi v brskalniku.
• Stikalo za povezovanje je nastavitev na ravni organizacije. Nastavitev na ravni ekipe in osebna odstopanja danes ne more nastaviti ne ekipa ne oseba.