MCP i povezani alati

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

Što je MCP

Model Context Protocol je mala, otvorena konvencija za opisivanje alata jezičnom modelu i pozivanje tih alata. Poslužitelj objavljuje što može — popis imenovanih alata, svaki s JSON shemom za svoje argumente — a klijent taj popis otkriva i poziva alate u ime modela. Namjerno je jednostavan: vrijednost je u tome da jedna integracija, napisana jednom, radi sa svakim modelom i svakim proizvodom koji taj protokol govori.

Nessie je na obje strane

To treba biti precizno, jer se te dvije polovice lako miješaju, a žive na namjerno različitim putanjama.

• Odlazno. Nessie je MCP klijent. Povezujete poslužitelje koje netko drugi pokreće, 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 poslužitelj. Agent koji radi negdje drugdje — Claude Code ili Codex na računalu programera — može pozivati vaše ploče i dokumente. Ta krajnja točka je POST /mcp, namjerno izvan /api, kako dva suprotna značenja ne bi bila jedan segment putanje jedno od drugog.

Povezivanje MCP poslužitelja s Nessiejem

Unosi u katalogu i instance

Postoje dva objekta, a razlika je važna:

• Unos u katalogu je definicija poslužitelja — njegov naziv, prijenos i način autentifikacije. Piše se jednom i može se dijeliti.
• Instanca je taj unos instaliran na jednoj razini, s vjerodajnicama koje do njega dopiru. Instalacija istog unosa za dva različita tima stvara dvije instance.

Većina ljudi nikad izravno ne dira nijedno od toga. Ulaz u administraciji je aplikacijska trgovina na /admin/apps: pregledava isti katalog uz skrivene pojedinosti veze, a Connect na oglasu stvara instancu. Operatori koji žele sirove objekte koriste /api/mcp/catalog i /api/mcp/instances.

Ako poslužitelja još nema u katalogu, POST /api/mcp/discover prima URL i vraća ono što poslužitelj sam o sebi kaže, a POST /api/mcp/library/import povlači unos iz javne biblioteke poslužitelja. Prva veza može se stvoriti izravno iz URL-a i preko POST /api/apps/custom.

Prijenosi

Nessie se povezuje s udaljenim poslužiteljima preko HTTP-a. Rade dva prijenosa: streamable HTTP (trenutni MCP prijenos) i stariji HTTP+SSE prijenos. Odaberite http, osim ako poslužitelj nudi samo sse.

Prijenos stdio odbijen je za konektore koje sami pišete. stdio znači da je MCP poslužitelj lokalni proces koji pokreće domaćin, a pokretanje proizvoljnih programa unutar Nessie poslužitelja operator ne može smisleno pregledati. Poslužitelji objavljeni samo kao paket za lokalno pokretanje isključeni su iz uvoza iz biblioteke iz istog razloga. Vrijednost ws postoji u polju protokola i nije implementirana — veza koja je koristi pada kad je Nessie pokuša otvoriti.

Kako se Nessie autentificira na poslužitelju

Unos u katalogu deklarira jednu od pet metoda: none, api_key, bearer, basic ili oauth2.

api_key je umetanje zaglavlja, a unos kaže koje zaglavlje i koji prefiks — pa su Authorization: Bearer …, X-API-Key: … i X-Auth-Token: Token … sve ista metoda konfigurirana drukčije. Sam ključ se jednom unosi preko POST /api/mcp/instances/:instanceId/secret i nikad se više ne može pročitati; nijedan odgovor s ruta instance ne nosi referencu na vjerodajnicu.

oauth2 dolazi u dva oblika. Poslužitelj s fiksnim krajnjim točkama ima ih u svom unosu u katalogu. Poslužitelj koji objavljuje standardne metapodatke ne treba ništa konfigurirati: Nessie čita dokumente zaštićenog resursa i autorizacijskog poslužitelja i sam sebi stvara klijenta putem dinamičke registracije klijenta ili preko dokumenta metapodataka ID-a klijenta koji objavljuje na vlastitoj well-known putanji. Tako ili tako, rukovanje je POST /api/mcp/instances/:instanceId/oauth/start, a zatim preusmjeravanje pružatelja natrag na GET /api/mcp/oauth/callback. Token stanja je jednokratan, čuva se u bazi i vrijedi deset minuta, a PKCE se uvijek koristi.

Jedno pravilo iznenađuje ljude: čak ni vlasnik organizacije ne može priložiti osobni ili OAuth token nekome drugome. Zajednička vjerodajnica moguća je samo za unos s API ključem koji je validiran kao takav; sve ostalo se odbija. Vjerodajnica koja pripada osobi ostaje vjerodajnica te osobe.

Gdje se čuvaju vjerodajnice

Tajne konektora i paketi OAuth tokena pohranjeni su u vlastitoj Postgres bazi, u namjenski vezanim AES-256-GCM omotnicama pod neovisno verzioniranim prstenom ključeva za šifriranje instalacije, a adresiraju se samo neprozirnim referencama secret_*. Namjerno nisu u vanjskom sigurnosnom spremištu koje čuva ostale Nessie tajne. Produkcijska instalacija koja nije konfigurirala šifrirano spremište odbija se pokrenuti, umjesto da dovrši OAuth rukovanje koje bi zatim bez traga odbacila.

Gdje veza dopire

Instanca se instalira na jednoj od šest razina: system, organization, project, team, channel ili user. Ta razina je tvrdo ograničenje na to koja izvođenja je mogu koristiti, a dodjele je mogu samo dodatno suziti, nikad proširiti — pa konektor koji ste instalirali sa svojim računom ne može tiho postati konektor za cijelu organizaciju.

Tko smije što instalirati slijedi isti obrazac: vlasnici i administratori organizacije upravljaju instalacijama na bilo kojoj razini; svi ostali instaliraju konektore na vlastitoj razini user i mogu vidjeti zajedničke instalacije kojima smiju pristupiti.

Davanje alata agentu

Povezivanje poslužitelja ne predaje njegove alate nikome. Kad se instanca instalira, Nessie je provjerava i svaki alat koji oglašava projicira u registar alata — što administracija prikazuje na /admin/advanced/tools: ugrađeni alati, MCP alati, paketni alati i alati executora na jednom popisu, svaki sa svojim izvorom i statusom.

Projicirani alat ima jedan od tri statusa: active, pending_review ili disabled. Alati iz zajedničke instalacije stižu kao pending_review i moraju se odobriti na toj stranici prije nego ih agent vidi; alati iz vaše instalacije na razini user aktivni su odmah, jer ste jedina izložena osoba. Pregled se ponavlja i nije jednokratna formalnost: ako kasnija provjera utvrdi da se opis ili shema alata promijenila, alat se vraća u pending_review i prestaje se nuditi dok ga netko ne pregleda.

Koji agenti smiju pozvati aktivni alat odlučuje se na jedan od dva načina:

• Veza stvorena kroz aplikacijsku trgovinu zahtijeva eksplicitnu dodjelu. Agent dobiva alat samo kad ga dodjela imenuje, a dodjela se provjerava prema trenutnom otisku alata, pa promijenjeni alat treba novu odluku.
• Inače je alat uključen prema zadanim postavkama za agente u dosegu razine na kojoj je, a pojedinačni agenti isključuju se na detaljnom panelu alata.

Dodjela imenuje točno jedan subjekt — ulogu ili agenta, nikad oboje — a zabrana nadjačava dopuštenje. Za vezu na razini user pitanje se uopće ne postavlja: svaki agent s kojim ta osoba razgovara može je koristiti, a jedino što je uskraćuje jest eksplicitno isključivanje.

Jedna stvar koju ljudi lako traže na krivom mjestu: /settings/accounts u administraciji su povezani računi — Slack, poštanski sandučići, pretplate na modele i OAuth veze s Linearom, Jirom, GitHubom i Trellom koje podupiru vanjske ploče. MCP konektori su na /admin/apps, a alati koje proizvode na /admin/advanced/tools.

Kontrolne točke odobrenja za pozive alata

Neki pozivi alata zaustavljaju se i čekaju osobu. Kad se to dogodi, izvođenje ne propada: poziv se zamrzava — ime alata, hash njegovih argumenata i dovoljno stanja za nastavak — a zahtjev za odobrenje pojavljuje se na /api/approvals da ga netko odgovori. Nastavak je idempotentan, pa dvostruko odobrenje ne može izvršiti poziv dvaput. Osoba koja odlučuje vidi ograničen sažetak onoga što se traži; točni argumenti i izvođenje koje ih je pokrenulo ostaju na poslužitelju.

Postoje dvije različite kontrolne točke i konfiguriraju se različito.

• Strukturne kontrolne točke svojstvo su određenih ugrađenih alata i nisu podesive. Slanje pošte s vlastitog sandučića agenta ili s povezanog, slanje Gmail nacrta, odspajanje poštanskog računa, stvaranje, promjena ili otkazivanje kalendarskog događaja te radnja u pregledniku koja bi pisala na stranicu na kojoj preglednik nije prijavljen — sve su tako ograničeni. Imaju 24-satni prozor za odgovor umjesto uobičajenih 30 minuta.
• Kontrolne točke politike dolaze iz pravila politike na paru tool/invoke. Pravilo koje dopušta poziv može nositi requiresApproval, a bez provjerenog odobrenja evaluacija vraća APPROVAL_REQUIRED umjesto da izvrši poziv. Pravila se evaluiraju prvo po zabrani i poredana su po razini.

Koji zaslon administracije piše pravilo politike requiresApproval za alat — model podataka i provedba su oboje na mjestu, ali nismo mogli potvrditi koji zaslon takvo pravilo piše.

Povezivanje vanjskog agenta s Nessiejem

Drugi smjer. Nessie pokreće vlastiti MCP poslužitelj na POST /mcp, preko streamable HTTP-a, i ne čuva stanje: svaki poziv nosi vlastitu vjerodajnicu i sam razrješava svog aktera, pa nema sesije za koju bi se klijent morao vezati uz jednu repliku. ChatGPT, Claude, Claude Code, Codex ili agent na tuđem laptopu mogu raditi s vašim pločama, dokumentima i kupcima iz bilo kojeg alata koji ta osoba već koristi. Korak po korak za svaku aplikaciju je Povežite ChatGPT, Claude i druge AI aplikacije.

Što je zapravo uparena vjerodajnica

Ovo treba ispravno shvatiti, jer je očiti mentalni model — API ključ s dopuštenjima — pogrešan.

Uparena vjerodajnica nikad nije identitet. Ona imenuje osobu, a svaki poziv alata izvodi se kao ta osoba, nad istim servisnim funkcijama koje pozivaju HTTP rute. Agent zato ne može doseći ništa što osoba koja ga je posudila ne bi mogla doseći klikom. Opsezi samo sužavaju taj doseg; ne postoji opseg koji ga proširuje.

Živost se provjerava pri svakom pojedinačnom pozivu, nikad se ne vjeruje tokenu: opoziv, istek, verzija tokena korisnika, njegovo članstvo u organizaciji i trenutna uloga. Degradacija, deaktivacija ili „odjavi me svuda“ stižu do agentova sljedećeg poziva, a ne tek do isteka vjerodajnice.

Token je neproziran, s prefiksom nag1_, pohranjen samo kao SHA-256 hash, i živi 90 dana. Odbija se s određenim 403 na svakoj ruti osim MCP krajnje točke — predočiti ga drugdje nije djelomičan uspjeh koji treba ponoviti, a upravo to sprječava da „posudio sam agentu svoje ploče“ znači „posudio sam mu svoj račun“.

Dva načina povezivanja

Aplikacija koja može otvoriti preglednik — ChatGPT, Claude, Claude Code, Codex — koristi MCP profil autorizacije: OAuth 2.1 s PKCE-om (S256), dinamičku registraciju klijenta na POST /mcp/oauth/register, osvježavajuće tokene i indikatore resursa. Aplikacija šalje osobu na /settings/security, ona odabere što smije raditi i kojim timovima pristupa, a preglednik se vraća aplikaciji s kodom. Pristupni token vrijedi sat vremena i osvježava se; veza traje 90 dana.

Agent naredbenog retka ne kontrolira preglednik i ne može imati povratni URL, pa se umjesto toga uparuje putem device authorization granta (RFC 8628).

1. Agent poziva POST /mcp/auth/device s clientName i scopes koje želi. Dobiva natrag device_code, kratki user_code, verification_uri i verification_uri_complete s već upisanim kodom u upitu, uz interval ispitivanja (polling) i expires_in. Ispisuje URI.
2. Osoba otvara taj URI dok je prijavljena, na /settings/security. Vidi koji agent traži pristup, čiji bi račun radio u njegovo ime, do kada i točno što bi mogao raditi — i odabire Dopusti ili Ne dopusti.
3. Agent periodično ispituje POST /mcp/auth/token s deviceCode, poštujući authorization_pending, slow_down, expired_token i access_denied. Pri uspjehu dobiva { access_token, token_type, scope, expires_at }.

U oba slučaja postoji ljudski korak, jer vjerodajnica nasljeđuje ovlasti osobe, pa se osoba mora odlučiti da ih posudi. Ništa ovdje ne stvara pristup iz ničega. Povezivanje se može isključiti za cijelu organizaciju na /admin/security?tab=programs, a taj se odgovor provjerava kad netko dopusti vezu, a ne kad agent pokrene jednu.

Otkrivanje

Nepotvrđeni POST /mcp odgovara s 401 i zaglavljem WWW-Authenticate koje pokazuje na /.well-known/oauth-protected-resource (RFC 9728), a ono imenuje ovaj izvor kao autorizacijski poslužitelj; njegovi metapodaci na /.well-known/oauth-authorization-server (RFC 8414) imenuju krajnje točke za registraciju, autorizaciju, token i opoziv. Taj lanac je sve što klijentu treba kad ima adresu. Da bi agent iz domene pronašao adresu, čita /.well-known/ai-catalog.json, koji imenuje Server Card na /mcp/server-card (MCP Server Cards, SEP-2127). Krajnje točke device granta navedene su u dokumentu zaštićenog resursa pod x-nessie-device-authorization.

Instalacija može odgovarati i na drugoj, kraćoj adresi: https://nessie.works/mcp Nessie Clouda proksira se na API, a klijent koji je tako došao dobiva tu adresu natrag kao resurs, dok prijava ostaje na API-ju. Preusmjeravanje ne bi pomoglo, jer klijent odbija metapodatke koji imenuju bilo koju adresu osim one koju je dobio. Operator navodi te izvore u NESSIE_MCP_ALIAS_ORIGINS.

Opsezi i alati

Opsezi su namjerno grubi — opseg koji nitko ne može objasniti nitko ne postavlja ispravno. Veza koja doseže više timova navodi ih s 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 prijenosa, pa model može prijaviti nešto korisno umjesto da ponavlja pokušaje bez ishoda.

Za vanjske sustave za praćenje ne postoji zasebna obitelj alata. Ploča je ploča bez obzira na to potječu li njeni zadaci iz Nessiea ili se zrcale iz Lineara, Jire, GitHuba ili Trella, pa jedan skup alata pokriva oboje, a svaki zadatak kaže odakle dolazi. Razlika je u pisanju: ploča zrcaljena iz izvora samo za čitanje odbija pisanje riječima, govoreći agentu da drugi sustav posjeduje zadatak i da ponavljanje neće pomoći.

Objava dokumenta je odobrenje, nikad opseg

Agenti pišu nacrte; objavljuje osoba. To pravilo za Nessiejeve vlastite agente provodi se tako što se agentski akter odmah odbija — ali uparena vjerodajnica razrješava se kao osoba, pa to odbijanje ne može uhvatiti. Vrata moraju biti negdje drugdje.

Zato nessie_doc_publish ne objavljuje. Otvara odobrenje knowledge.page.publish — isto ono koje otvara Nessiejev agent — i vraća { status: "awaiting_approval", approvalId }. Ponovljeno ispitivanje vraća isti zahtjev, a ne otvara drugi. Odluku donosi osoba, kao i svaku drugu odluku o objavi u Nessieju: o tom dokumentu, u trenutku kad on postoji.

Namjerno ne postoji opseg za objavu. Nekad je postojao — kvačica pri uparivanju koja kaže da ovaj agent smije objavljivati — i ukinut je. Odlučivao je jednom i na devedeset dana o pitanju koje proizvod svugdje drugdje postavlja po dokumentu, a odlučivao je prije nego što je dokument postojao, pa osoba koja je kvačicu stavila nije mogla znati što odobrava za objavu. nessie_doc_publish treba documents_write, jer traženje nije besplatno — čita stranicu i stavlja odluku pred nekoga — ali taj opseg ništa ne daje za samu objavu.

Na zahtjevu se bilježe dva identiteta, a razlika je nosiva. Podnositelj je vjerodajnica, nikad osoba u čije ime ona djeluje. Potrebni odobravatelj je ta osoba, i samo ona smije odgovoriti. Da je osoba bila navedena kao podnositelj, pravilo koje sprječava da netko odobri vlastiti zahtjev diskvalificiralo bi jedinu osobu koja ima pravo odlučiti.

Pregled i opoziv onoga što je upareno

Osobni upareni agenti osobe navedeni su na /settings/security, s oznakom i kontrolom opoziva za svakog. Vlasnik ili administrator organizacije vidi svaku vjerodajnicu u organizaciji na /admin/security?tab=programs — kako se zove, što smije raditi, je li živa i čiji račun posuđuje — i može opozvati bilo koju. Osobni popis ostaje samo za vlastiti pregled: popis živih vjerodajnica je popis uporišta, a ne općenito čitanje.

Zapisi napravljeni preko vjerodajnice pripisuju se osobi koja ju je posudila i nose id vjerodajnice u metapodacima revizije, pa dnevnik može razlikovati osobnu izmjenu od one koju je agent napravio umjesto nje.

Što još nije dostupno

Eksplicitno, jer je razmak između mogućnosti protokola i mogućnosti danog poslužitelja mjesto na kojem dokumentacija obično laže:

• Chat, kanali, izvođenja 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 sama e-poruka piše se u dizajneru.
• Povezivanje i spajanje kontakata, promjene CRM sheme, uvoz i postavljanje kanala ostaju kod osobe u pregledniku.
• Prekidač povezivanja je postavka na razini organizacije. Postavke na razini tima i osobne iznimke trenutačno ne može postaviti ni tim ni osoba.