MCP i povezani alati

Povežite Nessie sa MCP serverima i uparite spoljašnjeg agenta da radi u Nessie-ju u vaše ime.

Šta je MCP

Model Context Protocol je mala, otvorena konvencija za opisivanje alata jeziku modelu i za pozivanje tih alata. Server najavljuje šta može — spisak imenovanih alata, a svaki sa JSON šemom za svoje argumente — a klijent taj spisak otkriva i poziva alate u ime modela. Namerno je skroman: vrednost je u tome što jedna integracija, napisana jednom, radi sa svakim modelom i svakim proizvodom koji taj jezik govori.

Nessie je s obe strane

Vredi biti precizan u tome, jer se dve polovine lako mešaju, a žive na namerno različitim putanjama.

• Odlazno. Nessie je MCP klijent. Vi povezujete servere koje neko drugi pokreće, a alati koje oni izlažu postaju alati koje vaši agenti mogu da koriste. Površina za upravljanje je /api/mcp/*.
• Dolazno. Nessie je i MCP server. Agent koji radi negde drugde — Claude Code ili Codex na računaru programera — može da pristupi vašim tablama i dokumentima. Ta krajnja tačka je POST /mcp, namerno van /api, pa dva suprotna značenja nisu jedan segment putanje udaljena.

Povezivanje MCP servera sa Nessie-jem

Stavke kataloga i instance

Postoje dva objekta, a razlika je važna:

• Stavka kataloga je definicija servera — njegovo ime, transport i način autentifikacije. Piše se jednom i može se deliti.
• Instanca je ta stavka instalirana na jednom nivou, sa akreditivima kojima se dolazi do nje. Instaliranje iste stavke za dva različita tima daje dve instance.

Većina ljudi ih nikada direktno ne dira. Ulaz u admin je prodavnica aplikacija na /admin/apps: ona pregleda isti katalog sa skrivenim detaljima veze, a Connect na oglasu pravi instancu. Operateri koji žele sirove objekte koriste /api/mcp/catalog i /api/mcp/instances.

Ako server još nije u katalogu, POST /api/mcp/discover prima URL i vraća ono što server sam o sebi tvrdi, a POST /api/mcp/library/import povlači stavku iz javne biblioteke servera. Veza pri prvom pokretanju može se napraviti i direktno iz URL-a pomoću POST /api/apps/custom.

Transporti

Nessie se povezuje sa udaljenim serverima preko HTTP-a. Rade dva transporta: streamable HTTP (trenutni MCP transport) i stariji HTTP+SSE transport. Izaberite http, osim ako server nudi samo sse.

Transport stdio se odbija za konektore koje sami pišete. stdio znači da je MCP server lokalni proces koji pokreće domaćin, a izvršavanje proizvoljnih programa unutar Nessie servera operater ne može smisleno da pregleda. Serveri koji se objavljuju samo kao paket za lokalno pokretanje izostavljaju se iz uvoza iz biblioteke iz istog razloga. Vrednost ws postoji u polju protokola i nije implementirana — veza koja je koristi ne uspeva kada Nessie pokuša da je otvori.

Kako se Nessie autentifikuje kod servera

Stavka kataloga deklariše jedan od pet načina: none, api_key, bearer, basic ili oauth2.

api_key je ubacivanje zaglavlja, a stavka kaže koje zaglavlje i koji prefiks — pa su Authorization: Bearer …, X-API-Key: … i X-Auth-Token: Token … isti način, samo drugačije podešen. Sam ključ se jednom unosi pomoću POST /api/mcp/instances/:instanceId/secret i nikada nije ponovo čitljiv; nijedan odgovor iz ruta instance ne nosi referencu na akreditiv.

oauth2 dolazi u dva oblika. Server sa fiksnim krajnjim tačkama ih ima u svojoj stavci kataloga. Server koji objavljuje standardne metapodatke ne zahteva nikakvo podešavanje: Nessie čita dokumente zaštićenog resursa i servera za autorizaciju, pa sebi napravi klijenta preko dinamičke registracije klijenta ili preko dokumenta sa metapodacima ID-a klijenta, koji objavljuje na svojoj well-known putanji. U svakom slučaju rukovanje ide preko POST /api/mcp/instances/:instanceId/oauth/start, a zatim preusmeravanjem provajdera nazad na GET /api/mcp/oauth/callback. Token stanja koristi se jednom, čuva se u bazi i važi deset minuta, a PKCE se uvek koristi.

Jedno pravilo iznenađuje ljude: čak ni vlasnik organizacije ne može da veže lični ili OAuth token za nekog drugog. Deljeni akreditiv moguć je samo za stavku sa API ključem koja je validirana kao takva; sve ostalo se odbija. Akreditiv koji pripada osobi ostaje akreditiv koji pripada toj osobi.

Gde se akreditivi čuvaju

Tajne konektora i paketi OAuth tokena čuvaju se u vašoj sopstvenoj Postgres bazi, u AES-256-GCM omotnicama vezanim za svrhu, pod nezavisno verzionisanim prstenom ključeva za šifrovanje instalacije, a adresiraju se samo neprozirnim referencama secret_*. Namerno nisu u spoljnom sefu za tajne koji čuva ostale Nessie tajne. Produkcijska instalacija koja nije podesila šifrovano skladište odbija da se pokrene, umesto da završi OAuth rukovanje koje bi zatim bespovratno odbacila.

Dokle veza dopire

Instanca se instalira na jednom od šest opsega: system, organization, project, team, channel ili user. Opseg je tvrda granica za to koji tokovi rada je mogu koristiti, a dodele mogu samo da je sužavaju, nikada da je prošire — pa konektor koji ste instalirali sa sopstvenim nalogom ne može tiho postati konektor za celu organizaciju.

Ko sme gde da instalira prati isti obrazac: vlasnici i administratori organizacije upravljaju instalacijama na bilo kom opsegu; svi ostali instaliraju konektore na sopstvenom opsegu user i mogu da vide deljene instalacije do kojih imaju pravo pristupa.

Davanje alata agentu

Povezivanje servera ne predaje njegove alate nikome. Kada se instanca instalira, Nessie je proverava i prenosi svaki alat koji oglasi u registar alata, a to je ono što admin prikazuje na /admin/advanced/tools — ugrađeni alati, MCP alati, paketni alati i alati executora na jednoj listi, svaki sa svojim izvorom i statusom.

Preneti alat ima jedan od tri statusa: active, pending_review ili disabled. Alati iz deljene instalacije stižu kao pending_review i moraju biti odobreni na toj stranici pre nego što ih agent vidi; alati iz vaše instalacije na opsegu user aktivni su odmah, jer ste jedina izložena osoba. Pregled se ponavlja i nije jednokratna formalnost: ako kasnija provera utvrdi da su se opis ili šema alata promenili, on se vraća na pending_review i prestaje da se nudi dok neko ne pogleda promenu.

Koji agenti smeju da pozovu aktivan alat, odlučuje se na jedan od dva načina:

• Veza napravljena preko prodavnice aplikacija zahteva izričitu dodelu. Agent dobija alat samo kada ga dodela imenuje, a dodela se proverava prema trenutnom otisku alata, pa promenjen alat traži novu odluku.
• Inače je alat podrazumevano uključen za agente u dosegu njegovog opsega, a pojedinačni agenti se isključuju na panelu sa detaljima alata.

Dodela imenuje tačno jednog nosioca — ulogu ili agenta, nikada oboje — a zabrana ima prednost nad dozvolom. Za vezu na opsegu user pitanje se uopšte ne postavlja: svaki agent sa kojim ta osoba razgovara može da je koristi, a jedino što je uskraćuje jeste izričito isključivanje.

Jedna stvar koju je lako tražiti na pogrešnom mestu: /settings/accounts u adminu su povezani nalozi — Slack, poštanska sandučad, pretplate na modele i OAuth veze sa Linear, Jira, GitHub i Trello koje stoje iza spoljnih tabli. MCP konektori su na /admin/apps, a alati koje oni proizvode su na /admin/advanced/tools.

Kapije odobrenja na pozivima alata

Neki pozivi alata staju i čekaju osobu. Kada se to desi, tok ne propada: poziv se zamrzava — ime alata, heš njegovih argumenata i dovoljno stanja da se nastavi — a zahtev za odobrenje se pojavi na /api/approvals da ga neko reši. Nastavak je idempotentan, pa dupli odgovor ne može da izvrši poziv dvaput. Osoba koja odlučuje vidi ograničen sažetak onoga što se traži; tačni argumenti i tok koji ih je pokrenuo ostaju na serveru.

Postoje dve različite kapije, i podešavaju se na različite načine.

• Strukturne kapije su svojstvo određenih ugrađenih alata i ne mogu se podešavati. Slanje pošte sa sopstvenog poštanskog sandučeta agenta ili sa povezanog, slanje Gmail nacrta, raskidanje veze poštanskog naloga, kreiranje, izmena ili otkazivanje događaja u kalendaru i radnja u pregledaču koja bi pisala na sajt na koji pregledač nije prijavljen — sve su tako zaštićene. Za njih postoji prozor od 24 sata za odgovor, a ne uobičajenih 30 minuta.
• Kapije politike dolaze iz pravila politike na paru tool/invoke. Pravilo koje dozvoljava poziv može nositi requiresApproval, a bez proverenog odobrenja procena vraća APPROVAL_REQUIRED umesto da izvrši poziv. Pravila se procenjuju tako što zabrana ide prva, a poređaju se po opsegu.

Koji ekran u adminu piše pravilo politike requiresApproval za alat — model podataka i sprovođenje su oba na mestu, ali nismo mogli da potvrdimo ekran koji takvo pravilo upisuje.

Povezivanje spoljnog agenta sa Nessie-jem

Drugi smer. Nessie pokreće sopstveni MCP server na POST /mcp, preko streamable HTTP, i on je bez stanja: svaki poziv nosi sopstveni akreditiv i sam razrešava akter, pa nema sesije za koju bi klijent bio vezan za jednu repliku. ChatGPT, Claude, Claude Code, Codex ili agent na nečijem laptopu mogu da rade na vašim tablama, dokumentima i klijentima iz bilo kog alata koji ta osoba već koristi. Korak po korak za svaku aplikaciju nalazi se u Povežite ChatGPT, Claude i druge AI aplikacije.

Šta je upareni akreditiv

Ovo je deo koji treba dobro razumeti, jer je očigledan model — API ključ sa dozvolama dodeljenim uz njega — pogrešan.

Upareni akreditiv nikada nije identitet. On imenuje osobu, a svaki poziv alata radi kao ta osoba, nad istim servisnim funkcijama koje pozivaju HTTP rute. Agent zato ne može da dođe do ičega do čega osoba koja ga je ustupila ne bi mogla da dođe klikom. Opsezi samo sužavaju taj doseg; ne postoji opseg koji ga proširuje.

Važenje se proverava pri svakom pozivu, nikada se ne uzima iz tokena: opoziv, istek, verzija tokena osobe, članstvo u organizaciji i trenutna uloga. Degradacija, deaktivacija ili „odjavi me svuda“ stižu do agentovog sledećeg poziva, a ne tek kada akreditiv istekne.

Token je neproziran, počinje sa nag1_, čuva se samo kao SHA-256 heš i važi 90 dana. Na svakoj ruti osim MCP krajnje tačke odbija se posebnim 403 — predstavljanje na drugom mestu nije delimičan uspeh koji treba ponoviti, a upravo to sprečava da „pozajmio sam agentu svoje table“ znači „pozajmio sam mu svoj nalog“.

Dva načina povezivanja

Aplikacija koja može da otvori pregledač — ChatGPT, Claude, Claude Code, Codex — koristi MCP profil autorizacije: OAuth 2.1 sa PKCE (S256), dinamičku registraciju klijenta na POST /mcp/oauth/register, osveživanje tokena i indikatore resursa. Aplikacija šalje osobu na /settings/security, ona bira šta sme da radi i kojim svojim timovima pristupa, a pregledač se vraća aplikaciji sa kodom. Njen pristupni token traje sat vremena i osvežava se; veza traje 90 dana.

Agent iz komandne linije ne kontroliše pregledač i ne može da ima callback URL, pa se upari preko device authorization grant (RFC 8628).

1. Agent poziva POST /mcp/auth/device sa clientName i scopes koje želi. Dobija device_code, kratak user_code, verification_uri i verification_uri_complete sa kodom već u upitu, plus interval za proveru i expires_in. Ispisuje URI.
2. Osoba otvara taj URI dok je prijavljena, na /settings/security. Vidi koji agent traži pristup, na čiji nalog bi radio, dokle važi i tačno šta bi mogao da radi — pa bira Allow ili Don’t allow.
3. Agent proverava POST /mcp/auth/token sa deviceCode, poštujući authorization_pending, slow_down, expired_token i access_denied. Pri uspehu dobija { access_token, token_type, scope, expires_at }.

U oba slučaja postoji ljudski korak, jer akreditiv nasleđuje ovlašćenja osobe, pa osoba mora da izabere da ih ustupi. Ovde se pristup ne stvara iz ničega. Povezivanje se može isključiti za celu organizaciju na /admin/security?tab=programs, a taj odgovor se proverava kada neko dozvoli vezu, a ne kada agent počne da je pokreće.

Otkrivanje

Neautentifikovan POST /mcp odgovara sa 401 i zaglavljem WWW-Authenticate koje upućuje na /.well-known/oauth-protected-resource (RFC 9728), a ono imenuje ovaj izvor kao server za autorizaciju; njegovi metapodaci na /.well-known/oauth-authorization-server (RFC 8414) imenuju krajnje tačke za registraciju, autorizaciju, token i opoziv. Taj lanac je sve što klijentu treba kad ima adresu. Da bi agent od domena došao do adrese, čita /.well-known/ai-catalog.json, koji imenuje Server Card na /mcp/server-card (MCP Server Cards, SEP-2127). Krajnje tačke device grant-a navedene su u dokumentu zaštićenog resursa pod x-nessie-device-authorization.

Instalacija može da odgovara i na drugoj, kraćoj adresi: https://nessie.works/mcp Nessie Cloud-a prosleđuje se API-ju, a klijent koji je tako došao dobija tu adresu nazad kao resurs, dok se prijava i dalje odvija na API-ju. Preusmeravanje ne bi radilo, jer klijent odbija metapodatke koji imenuju bilo koju adresu osim one koju je dobio. Operater navodi te izvore u NESSIE_MCP_ALIAS_ORIGINS.

Opsezi i alati

Opsezi su namerno grubi — opseg koji niko ne može da objasni niko ne podešava ispravno. Veza koja dopire do više timova navodi ih pomoću nessie_team_list, a svaki drugi alat tada imenuje svoj teamId.

Poziv bez opsega koji mu treba vraća se kao rezultat alata koji imenuje opseg koji treba tražiti, a ne kao greška transporta, pa model može da prijavi nešto korisno umesto da ponavlja pokušaj u zid.

Za spoljne sisteme za praćenje ne postoji zasebna porodica alata. Tabla je tabla bez obzira na to da li zadaci nastaju u Nessie-ju ili se preslikavaju iz Linear, Jira, GitHub ili Trello, pa jedan skup alata pokriva oba, a svaki zadatak kaže odakle je. Razlika je u pisanju: tabla preslikana iz izvora samo za čitanje odbija upis rečima, javljajući agentu da zadatak poseduje drugi sistem i da ponovni pokušaj neće pomoći.

Objavljivanje dokumenta je odobrenje, nikada opseg

Agenti pišu nacrte; objavljuje osoba. Pravilo se za Nessie-ove sopstvene agente sprovodi tako što se akter-agent odbija bez izuzetka — ali upareni akreditiv se razrešava kao osoba, pa to odbijanje ne može da ga uhvati. Kapija mora biti negde drugde.

Zato nessie_doc_publish ne objavljuje. Otvara odobrenje knowledge.page.publish — isto koje otvara i Nessie agent — i vraća { status: "awaiting_approval", approvalId }. Provera vraća isti zahtev umesto da otvara drugi. Odluku donosi isti način kao svaku drugu odluku o objavi u Nessie-ju: osoba, o tom dokumentu, u trenutku kada on postoji.

Namerno ne postoji opseg za objavu. Postojao je — polje za štiklu u trenutku uparivanja koje kaže da ovaj agent sme da objavljuje — i ukinut je. Odlučivao je jednom i na devedeset dana o pitanju koje proizvod u svim ostalim slučajevima postavlja po dokumentu, i odlučivao je pre nego što je dokument postojao, pa osoba koja ga je štiklirala nije mogla da zna šta prihvata da se objavi. nessie_doc_publish zahteva documents_write, jer traženje nije besplatno — čita stranicu i stavlja odluku pred nekoga — ali taj opseg ne daje ništa u vezi sa objavom.

Na zahtevu se beleže dva identiteta, a razlika je presudna. Traživač je akreditiv, nikada osoba u čije ime radi. Obavezni odobravalac je ta osoba, i samo ona sme da odgovori. Da je zahtev imenovao osobu kao traživača, pravilo koje sprečava da bilo ko odobri sopstveni zahtev diskvalifikovalo bi jedinu osobu koja ima pravo da odluči.

Pregled i opoziv uparenih akreditiva

Lični upareni agenti osobe navedeni su na /settings/security, sa oznakom i dugmetom za opoziv za svaki. Vlasnik ili admin organizacije vidi svaki akreditiv u organizaciji na /admin/security?tab=programs — kako se zove, šta sme, da li je aktivan i čiji nalog pozajmljuje — i može da opozove bilo koji. Lični spisak ostaje samo za vlastiti nalog: spisak aktivnih akreditiva je spisak uporišta, a ne opšte čitanje.

Izmene napravljene preko akreditiva pripisuju se osobi koja ga je pozajmila i nose id akreditiva u metapodacima revizije, pa dnevnik može da razlikuje ličnu izmenu osobe od one koju je njen agent napravio za nju.

Šta još nije dostupno

Eksplicitno, jer je razmak između mogućnosti protokola i mogućnosti određenog servera mesto na kome dokumentacija obično laže:

• Ćaskanje, kanali, pokretanja i upravljanje agentima nisu izloženi preko MCP-a.
• Program priprema newsletter, a osoba ga šalje: ništa ne šalje, ne zakazuje niti briše kampanju, a sam imejl se piše u dizajneru.
• Povezivanje i spajanje kontakata, izmene šeme CRM-a, uvozi i podešavanje kanala ostaju kod osobe u pregledaču.
• Prekidač za povezivanje je podešavanje na nivou organizacije. Podešavanja na nivou tima i lična podešavanja tim ili osoba trenutno ne mogu da postave.