MCP i povezani alati

Povežite Nessie s MCP serverima i uparite vanjskog agenta da može raditi u Nessieju u vaše ime.

Šta je MCP

Model Context Protocol je mala, otvorena konvencija za opisivanje alata jezičkom modelu i pozivanje tih alata. Server prijavljuje šta može — spisak imenovanih alata, svaki s JSON šemom za svoje argumente — a klijent otkriva taj spisak i poziva alate u ime modela. Namjerno je dosadan: vrijednost je u tome da jedna integracija, napisana jednom, radi sa svakim modelom i svakim proizvodom koji ga podržava.

Nessie je s obje strane

Vrijedi biti precizan oko toga, jer se dvije polovine lako mješaju, a žive na namjerno različitim putanjama.

• Odlazno. Nessie je MCP klijent. Povezujete servere koje pokreće neko drugi, a alati koje oni izlažu postaju alati koje vaši agenti mogu koristiti. Površina za upravljanje je /api/mcp/*.
• Dolazno. Nessie je i MCP server. Agent koji radi negdje drugo — Claude Code ili Codex na računaru developera — može pristupiti vašim tablama i dokumentima. Ta krajnja tačka je POST /mcp, namjerno van /api, pa dva suprotna značenja ne dijele jedan segment putanje.

Povezivanje MCP servera s Nessiejem

Stavke kataloga i instance

Postoje dva objekta, a razlika je bitna:

• Stavka kataloga je definicija servera — njegovo ime, transport i način autentifikacije. Piše se jednom i može se dijeliti.
• Instanca je ta stavka instalirana na jednom opsegu, s vjerodajnicama koje do nje dopiru. Instaliranje iste stavke za dva različita tima daje dvije instance.

Većina ljudi ih nikada ne dira direktno. Ulaz u adminu je aplikacijska prodavnica na /admin/apps: pregleda isti katalog sa skrivenim detaljima povezivanja, a Connect na stavci kreira 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 kaže, a POST /api/mcp/library/import povlači stavku iz javne biblioteke servera. Prvo povezivanje može se napraviti i direktno iz URL-a pomoću POST /api/apps/custom.

Transporti

Nessie se povezuje na udaljene servere preko HTTP-a. Rade dva transporta: streamable HTTP (trenutni MCP transport) i stariji HTTP+SSE transport. Birajte http, osim ako server nudi samo sse.

Transport stdio je odbijen za konektore koje sami pišete. stdio znači da je MCP server lokalni proces koji pokreće domaćin, a pokretanje proizvoljnih programa unutar Nessie servera operater ne može smisleno pregledati. Serveri objavljeni samo kao paket za lokalno pokretanje isključuju se iz uvoza iz biblioteke iz istog razloga. Vrijednost ws postoji u polju protokola i nije implementirana — veza koja je koristi pada čim Nessie pokuša da je otvori.

Kako se Nessie autentifikuje na server

Stavka kataloga deklariše jednu od pet metoda: none, api_key, bearer, basic ili oauth2.

api_key je ubacivanje zaglavlja, a stavka kaže koje zaglavlje i koji prefiks — tako su Authorization: Bearer …, X-API-Key: … i X-Auth-Token: Token … ista metoda samo drugačije konfigurisana. Ključ se jednom unosi preko POST /api/mcp/instances/:instanceId/secret i nikada se više ne može pročitati; nijedan odgovor iz ruta instanci ne nosi referencu na vjerodajnicu.

oauth2 dolazi u dva oblika. Server s fiksnim krajnjim tačkama ih ima u svojoj stavci kataloga. Server koji objavljuje standardne metapodatke ne treba ništa konfigurisati: Nessie čita dokumente zaštićenog resursa i autorizacijskog servera, a sam sebi napravi klijenta, kroz dinamičku registraciju klijenta ili kroz dokument s metapodacima ID-a klijenta koji objavljuje na vlastitoj well-known putanji. U svakom slučaju rukovanje je POST /api/mcp/instances/:instanceId/oauth/start, zatim preusmjeravanje pružatelja nazad na GET /api/mcp/oauth/callback. State token se koristi jednom, čuva se u bazi i važi deset minuta, a PKCE se uvijek koristi.

Jedno pravilo iznenađuje ljude: čak ni vlasnik organizacije ne može vezati lični ili OAuth token za nekog drugog. Zajednička vjerodajnica moguća je samo za stavku s API ključem koja je validirana kao takva; sve drugo se odbija. Vjerodajnica koja pripada osobi ostaje vjerodajnica te osobe.

Gdje žive vjerodajnice

Tajne konektora i OAuth paketi tokena čuvaju se u vašoj vlastitoj Postgres bazi, u AES-256-GCM omotačima vezanim za namjenu, pod ključ-prstenom za šifrovanje koji postavljanje nezavisno verzioniše, i adresiraju se samo neprozirnim referencama secret_*. Namjerno nisu u vanjskom trezoru tajni koji čuva ostale Nessie tajne. Produkcijsko postavljanje koje nije konfigurisalo šifrovano skladište odbija da se pokrene, umjesto da završi OAuth rukovanje koje bi zatim ispustilo.

Dokle dopire veza

Instanca je instalirana na jednom od šest opsega: system, organization, project, team, channel ili user. Taj opseg je tvrda granica za to koja izvršavanja je mogu koristiti, a dodjele je mogu samo dodatno suziti, nikada proširiti — pa konektor koji ste instalirali svojim nalogom ne može tiho postati organizacijski.

Ko smije instalirati gdje slijedi isti oblik: vlasnici i admini organizacije upravljaju instalacijama na bilo kojem opsegu; svi ostali instaliraju konektore na vlastitom opsegu user i mogu vidjeti zajedničke instalacije kojima imaju pravo pristupa.

Dodjela alata agentu

Povezivanje servera ne predaje njegove alate nikome. Kada se instanca instalira, Nessie je provjerava i projektuje svaki alat koji oglašava u registar alata — to admin prikazuje na /admin/advanced/tools: ugrađeni alati, MCP alati, paketni alati i alati izvršnog okruženja na jednom spisku, svaki sa svojim izvorom i statusom.

Projektovani alat ima jedan od tri statusa: active, pending_review ili disabled. Alati iz zajedničke instalacije stižu kao pending_review i moraju biti odobreni na toj stranici prije nego ih agent ikada vidi. Alati iz vaše instalacije na opsegu user su odmah aktivni, jer je jedina izložena osoba vi. Pregled je stalan, a ne jednokratan ceremonijal: ako kasnija provjera utvrdi da se opis ili šema alata promijenila, alat se vraća u pending_review i prestaje da se nudi dok neko ne pogleda promjenu.

Koji agenti onda smiju pozvati aktivan alat, odlučuje se na jedan od dva načina:

• Veza kreirana kroz aplikacijsku prodavnicu zahtijeva eksplicitnu dodjelu. Agent dobija alat samo kada ga dodjela imenuje, a dodjela se provjerava prema trenutnom otisku alata, pa promijenjen alat traži novu odluku.
• Inače je alat podrazumijevano uključen za agente u dosegu njegovog opsega, a pojedinačni agenti se isključuju na panelu s detaljima alata.

Dodjela imenuje tačno jednog nosioca — ulogu ili agenta, nikada oboje — a zabrana nadjačava dozvolu. Za vezu na opsegu user pitanje se ne postavlja: svaki agent s kojim ta osoba razgovara može je koristiti, a jedino što je uskraćuje jeste eksplicitno isključivanje.

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

Provjere odobrenja za pozive alata

Neki pozivi alata se zaustavljaju i čekaju osobu. Kada se to desi, izvršavanje ne pada: poziv se zamrzava — ime alata, heš njegovih argumenata i dovoljno stanja za nastavak — a zahtjev za odobrenje se pojavljuje na /api/approvals da ga neko odgovori. Nastavak je idempotentan, pa dupli odobrenje ne može pokrenuti poziv dvaput. Osoba koja odlučuje vidi ograničen sažetak onoga što se traži; tačni argumenti i izvorno izvršavanje ostaju na serveru.

Postoje dvije različite provjere, i konfigurisane su različito.

• Strukturne provjere su svojstvo određenih ugrađenih alata i nisu konfigurabilne. Slanje pošte iz poštanskog sandučeta agenta ili povezanog, slanje Gmail nacrta, odspajanje poštanskog naloga, kreiranje, izmjena ili otkazivanje kalendarskog događaja, te radnja u pregledniku koja bi pisala na web stranicu na kojoj preglednik nije prijavljen — sve su tako kontrolisane. Za njih važi prozor od 24 sata za odgovor, a ne uobičajenih 30 minuta.
• Provjere politike dolaze iz pravila politike na paru tool/invoke. Pravilo koje dozvoljava poziv može nositi requiresApproval, a bez provjerenog odobrenja evaluacija vraća APPROVAL_REQUIRED umjesto da pokrene poziv. Pravila se evaluiraju prvo po zabrani i poredana su po opsegu.

Koji ekran admina piše pravilo politike requiresApproval za alat — model podataka i provođenje su oba na mjestu, ali nismo mogli potvrditi koji ekran ga piše.

Povezivanje vanjskog agenta s Nessiejem

Drugi smjer. Nessie pokreće vlastiti MCP server na POST /mcp, preko streamable HTTP, i on je bez stanja: svaki poziv nosi vlastitu vjerodajnicu i sam razrješava svog aktera, pa nema sesije za koju bi klijent bio vezan za jednu repliku. ChatGPT, Claude, Claude Code, Codex ili agent na nečijem laptopu mogu raditi s vašim tablama, dokumentima i klijentima iz bilo kojeg alata koji ta osoba već koristi. Korak po korak za svaku aplikaciju je Povežite ChatGPT, Claude i druge AI aplikacije.

Šta je zapravo uparena vjerodajnica

Ovo treba ispravno razumjeti, jer je očigledni mentalni model — API ključ s pridruženim dozvolama — pogrešan.

Uparena vjerodajnica nikada nije identitet. Ona imenuje čovjeka, a svaki poziv alata izvršava se kao taj čovjek, nad istim servisnim funkcijama koje pozivaju HTTP rute. Agent zato ne može doći do ničega do čega osoba koja ga je posudila ne bi mogla doći klikom. Opsezi samo sužavaju taj doseg; ne postoji opseg koji ga proširuje.

Aktivnost se provjerava pri svakom pojedinačnom pozivu, nikada se ne uzima iz tokena: opoziv, istek, verzija tokena korisnika, njegovo članstvo u organizaciji i trenutna uloga. Smanjenje uloge, deaktivacija ili „odjavi me svuda“ stižu na sljedeći poziv agenta, a ne tek na istek vjerodajnice.

Token je neproziran, s prefiksom nag1_, čuva se samo kao SHA-256 heš i živi 90 dana. Odbija se sa specifičnim 403 na svakoj ruti osim MCP krajnje tačke — predstavljanje na drugom mjestu nije djelimičan uspjeh koji treba ponoviti, a upravo to sprječava da „posuditi agentu svoje table“ znači „posuditi mu svoj nalog“.

Dva načina povezivanja

Aplikacija koja može otvoriti preglednik — ChatGPT, Claude, Claude Code, Codex — koristi MCP profil autorizacije: OAuth 2.1 s PKCE (S256), dinamičku registraciju klijenta na POST /mcp/oauth/register, refresh tokene i resource indikatore. Aplikacija šalje osobu na /settings/security, ona bira šta smije raditi i kojim timovima pristupa, a preglednik se vraća u aplikaciju s kodom. Njen access token traje sat i osvježava se; veza traje 90 dana.

Agent u komandnoj liniji ne kontroliše preglednik i ne može imati callback URL, pa se umjesto toga uparuje preko device authorization granta (RFC 8628).

1. Agent poziva POST /mcp/auth/device s clientName i scopes koje želi. Dobija device_code, kratak user_code, verification_uri i verification_uri_complete s kodom već u upitu, plus interval provjere (interval) i expires_in. Ispisuje URI.
2. Osoba otvara taj URI dok je prijavljena, na /settings/security. Vidi koji agent traži pristup, u čije ime bi radio, do kada i tačno šta bi mogao raditi — pa bira Dozvoli ili Ne dozvoli.
3. Agent provjerava POST /mcp/auth/token s deviceCode, poštujući authorization_pending, slow_down, expired_token i access_denied. Pri uspjehu dobija { access_token, token_type, scope, expires_at }.

U svakom slučaju postoji ljudski korak, jer vjerodajnica nasljeđuje prava osobe, pa osoba mora odlučiti da ih posudi. Ništa ovdje ne izvodi pristup iz ničega. Povezivanje se može isključiti i za cijelu organizaciju na /admin/security?tab=programs, a taj odgovor se provjerava kada neko odobri vezu, a ne kada agent počne jednu.

Otkrivanje

Neautentifikovan POST /mcp odgovara s 401 i zaglavljem WWW-Authenticate koje upućuje na /.well-known/oauth-protected-resource (RFC 9728); ono imenuje ovaj origin kao autorizacijski server. 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 kada ima adresu. Da bi agent iz domena pronašao adresu, čita /.well-known/ai-catalog.json, koji imenuje Server Card na /mcp/server-card (MCP Server Cards, SEP-2127). Krajnje tačke device granta navedene su u dokumentu zaštićenog resursa pod x-nessie-device-authorization.

Postavljanje može odgovarati i na drugoj, kraćoj adresi: https://nessie.works/mcp u Nessie Cloudu proksira se na API, a klijent koji je tako došao dobija tu adresu nazad kao resurs, dok se prijava odvija na API-ju. Preusmjeravanje ne bi pomoglo, jer klijent odbija metapodatke koji imenuju bilo koju adresu osim one koju je dobio. Operater navodi ove origine u NESSIE_MCP_ALIAS_ORIGINS.

Opsezi i alati

Opsezi su namjerno grubi — opseg koji niko ne može objasniti 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 zatražiti, a ne kao greška transporta, pa model može prijaviti nešto korisno umjesto da ponovo udara u zid.

Za vanjske trackere ne postoji zasebna porodica alata. Tabla je tabla bez obzira na to potiču li zadaci iz Nessieja 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 riječima, govoreći agentu da zadatak posjeduje drugi sistem i da ponovni pokušaj neće pomoći.

Objava dokumenta je odobrenje, nikada opseg

Agenti pišu nacrte; objavljuje osoba. Ovo pravilo Nessiejevi agenti provode tako što se agent-akter odbija bez izuzetka — ali uparena vjerodajnica se razrješava kao osoba, pa to odbijanje ne može uhvatiti. Provjera mora biti negdje drugdje.

Zato nessie_doc_publish ne objavljuje. Otvara knowledge.page.publish odobrenje — isto koje otvara i Nessiejev agent — i vraća { status: "awaiting_approval", approvalId }. Provjera vraća isti zahtjev umjesto da otvori drugi. Odluku donosi osoba, kao što se sve odluke o objavi u Nessieju donose: o tom dokumentu, u trenutku kada on postoji.

Namjerno ne postoji opseg za objavu. Nekada je postojao — oznaka pri uparivanju da ovaj agent smije objavljivati — 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 prije nego što je dokument postojao, pa osoba koja ga je označila nije mogla znati šta odobrava da se objavi. nessie_doc_publish traži documents_write, jer traženje nije besplatno — čita stranicu i stavlja odluku pred nekoga — ali taj opseg ne daje ništa u vezi s objavom.

Dva identiteta se bilježe na zahtjevu, a razlika je nosiva. Podnosilac je vjerodajnica, nikada čovjek u čije ime djeluje. Obavezni odobravalac je taj čovjek, i samo on smije odgovoriti. Da je osoba bila navedena kao podnosilac, pravilo koje sprječava da bilo ko odobri vlastiti zahtjev diskvalifikovalo bi jedinu osobu koja ima pravo da odluči.

Pregled i opoziv onoga što je upareno

Uparene agente osobe prikazane su na /settings/security, sa oznakom i kontrolom za opoziv za svakog. Vlasnik ili admin organizacije vidi svaku vjerodajnicu u organizaciji na /admin/security?tab=programs — kako se zove, šta smije raditi, je li aktivna i čiji nalog posuđuje — i može opozvati bilo koju. Lični spisak ostaje samo za vlastiti pregled: spisak aktivnih vjerodajnica je spisak uporišta, a ne opšte čitanje.

Izmjene napravljene preko vjerodajnice pripisuju se osobi čiji nalog se posuđuje i nose id vjerodajnice u metapodacima revizije, pa dnevnik može razlikovati vlastitu izmjenu 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 datog servera mjesto na kojem dokumentacija obično laže:

• Razgovori, kanali, izvršavanja i upravljanje agentima nisu izloženi preko MCP-a.
• Vanjski program priprema newsletter, a osoba ga šalje: ništa ne šalje, ne zakazuje niti briše kampanju, a sam e-mail se piše u dizajneru.
• Povezivanje i spajanje kontakata, izmjene CRM šeme, uvozi i podešavanje kanala ostaju kod osobe u pregledniku.
• Prekidač povezivanja je postavka na nivou organizacije. Timska i lična odstupanja trenutno ne može podesiti ni tim ni osoba.