MCP ja ühendatud tööriistad

Ühendage Nessie MCP-serveritega ja siduge väline agent, et see saaks Nessies teie nimel töötada.

Mis on MCP

Model Context Protocol on väike ja avatud kokkulepe tööriistade kirjeldamiseks keelemudelile ning nende väljakutsumiseks. Server kuulutab välja, mida ta oskab — nimega tööriistade loendi, millest igaühel on argumentide JSON-skeem — ning klient avastab selle loendi ja kutsub tööriistu mudeli nimel. See on tahtlikult tagasihoidlik: väärtus seisneb selles, et üks kord kirjutatud integratsioon töötab iga mudeli ja iga tootega, mis seda keelt räägib.

Nessie on mõlemal pool

Seda tasub täpselt lahti seletada, sest need kaks poolt on kergesti segamini aetavad ja nad asuvad tahtlikult erinevatel teedel.

• Väljaminev. Nessie on MCP klient. Te ühendate servereid, mida keegi teine käitab, ning nende avaldatud tööriistad saavad teie agentide kasutada. Haldusliides on /api/mcp/*.
• Sissetulev. Nessie on ka MCP server. Mõni teine agent — Claude Code või Codex arendaja masinal — saab kutsuda teie tahvleid ja dokumente. See lõpp-punkt on POST /mcp, tahtlikult väljaspool /api-t, et kaks vastandlikku tähendust ei oleks üksteisest ühe teeosa kaugusel.

MCP-serveri ühendamine Nessie’ga

Kataloogikirjed ja eksemplarid

Objekte on kaks ja erinevus on oluline:

• Kataloogikirje on serveri definitsioon — selle nimi, transport ja see, kuidas see autentib. See kirjutatakse üks kord ja seda võib jagada.
• Eksemplar on see kirje, paigaldatuna ühele ulatusele koos mandaatidega, mis sinna ligi pääsevad. Sama kirje paigaldamine kahele erinevale meeskonnale annab kaks eksemplari.

Enamik inimesi ei puuduta kumbagi otse. Adminis on sissepääs rakenduste poes aadressil /admin/apps: see sirvib sama kataloogi, peites ühenduse üksikasjad, ning Connect loendil loob eksemplari. Operaatorid, kes soovivad toorobjekte, kasutavad /api/mcp/catalog ja /api/mcp/instances.

Kui server ei ole veel kataloogis, võtab POST /api/mcp/discover URL-i ja tagastab selle, mida server iseenda kohta ütleb, ning POST /api/mcp/library/import toob kirje avalikust serverite raamatukogust. Esmakordse ühenduse saab luua otse URL-ist ka POST /api/apps/custom kaudu.

Transpordid

Nessie ühendub kaugserveritega HTTP kaudu. Töötavad kaks transporti: voogedastav HTTP (praegune MCP transport) ja vanem HTTP+SSE transport. Valige http, välja arvatud juhul, kui server pakub ainult sse.

Transport stdio on teie kirjutatud konnektorite puhul keelatud. stdio tähendab, et MCP server on kohalik protsess, mille käivitab host, ja suvaliste programmide käitamist Nessie serveri sees ei saa operaator mõistlikult üle vaadata. Serverid, mida avaldatakse ainult kohaliku käivitamise paketina, jäetakse raamatukogu importidest samal põhjusel välja. Väärtus ws eksisteerib protokolli väljas, kuid seda ei ole rakendatud — seda kasutav ühendus ebaõnnestub, kui Nessie proovib selle avada.

Kuidas Nessie serverisse autentib

Kataloogikirje kuulutab välja ühe viiest meetodist: none, api_key, bearer, basic või oauth2.

api_key on päisesse süstimine ja kirje ütleb, millise päise ning millise eesliitega — nii et Authorization: Bearer …, X-API-Key: … ja X-Auth-Token: Token … on kõik sama meetod, erinevalt seadistatud. Võti kleebitakse üks kord sisse lõpp-punktiga POST /api/mcp/instances/:instanceId/secret ja seda ei saa enam kunagi lugeda; ükski eksemplari marsruudi vastus ei sisalda mandaadiviidet.

oauth2 tuleb kahes vormis. Fikseeritud lõpp-punktidega server on need kataloogikirjes. Server, mis avaldab standardse metaandmestiku, ei vaja midagi seadistada: Nessie loeb kaitstud ressursi ja autoriseerimisserveri dokumente ning loob ise kliendi dünaamilise kliendiregistreerimise kaudu või kliendi-ID metaandmete dokumendi kaudu, mille ta avaldab oma well-known teel. Kummalgi juhul on käepigistus POST /api/mcp/instances/:instanceId/oauth/start, millele järgneb pakkuja suunamine tagasi aadressile GET /api/mcp/oauth/callback. Olekutõend on ühekordne, hoitakse andmebaasis ja kehtib kümme minutit ning PKCE on alati kasutusel.

Üks reegel üllatab inimesi: isegi organisatsiooni omanik ei saa isiklikku ega OAuth-tokenit kellegi teise külge kinnitada. Jagatud mandaat on võimalik ainult API-võtme kirjele, mis on valideeritud kui selline; kõik muu keeldutakse. Inimesele kuuluv mandaat jääb inimesele kuuluvaks.

Kus mandaadid elavad

Konnektori saladused ja OAuth-tokenite paketid salvestatakse teie enda Postgresi andmebaasi, eesmärgipõhistes AES-256-GCM ümbrikes, juurutuse sõltumatult versioonitud krüptovõtmerõnga all, ning neile viidatakse ainult läbipaistmatute secret_* viidetega. Need ei ole tahtlikult välises saladuste hoidlas, kus asuvad teised Nessie saladused. Tootmisjuurutus, mis pole krüptositu poodi seadistanud, keeldub käivitumast, selle asemel et lõpetada OAuth-käepigistus, mille ta seejärel kaotaks.

Kuhu ühendus ulatub

Eksemplar paigaldatakse ühele kuuest ulatusest: system, organization, project, team, channel või user. See ulatus on kõva lagi sellele, millised käitused seda kasutada saavad, ja õigused saavad seda ainult kitsendada, mitte laiendada — nii et konnektor, mille paigaldasite oma kontoga, ei saa vaikselt muutuda organisatsioonihõlmavaks.

Kes kuhu paigaldada tohib, järgib sama kuju: organisatsiooni omanikud ja adminid haldavad eksemplare igal ulatusel; kõik muud paigaldavad konnektorid oma isikliku user-ulatusse ning näevad jagatud eksemplare, millele neil on juurdepääs.

Agendile tööriista andmine

Serveri ühendamine ei anna selle tööriistu kellelegi. Kui eksemplar paigaldatakse, sondeerib Nessie seda ja projitseerib iga reklaamitud tööriista tööriistaregistrisse, mida admin kuvab aadressil /admin/advanced/tools — sisseehitatud tööriistad, MCP-tööriistad, pakettööriistad ja täitmistööriistad ühel loendis, igaüks oma allika ja olekuga.

Projitseeritud tööriistal on üks kolmest olekust: active, pending_review või disabled. Jagatud ulatusega paigaldusest pärinevad tööriistad saabuvad olekuga pending_review ja need tuleb sellel lehel heaks kiita, enne kui agent neid näeb; teie enda user-ulatuse paigaldusest pärinevad tööriistad on kohe aktiivsed, sest ainus inimene, keda need puudutavad, olete teie. Ülevaatus on korduv, mitte ühekordne tseremoonia: kui hilisem probe leiab, et tööriista kirjeldus või skeem on nihkunud, läheb see tagasi olekusse pending_review ja seda ei pakuta enam, kuni keegi muudatust ei vaata.

Seda, millised agendid võivad aktiivset tööriista siis kutsuda, otsustatakse kahel viisil:

• Rakenduste poe kaudu loodud ühendus nõuab selget õigust. Agent saab tööriista ainult siis, kui õigus seda nimetab, ja õigust kontrollitakse tööriista praeguse sõrmejäljega, nii et muutunud tööriist vajab uut otsust.
• Muidu on tööriist vaikimisi sisse lülitatud agentidele, kes jäävad selle ulatuse ulatusse, ning üksikud agendid lülitatakse tööriista detailpaneelil välja.

Õigus nimetab täpselt ühe adressaadi — rolli või agendi, mitte kumbagi koos — ja keeld võidab loa. user-ulatuse ühenduse puhul küsimust ei teki: iga agent, millega see isik räägib, saab seda kasutada, ja ainus asi, mis seda hoiab, on selge väljalülitamine.

Üks asi, mida on lihtne valesti otsida: admini /settings/accounts on ühendatud kontod — Slack, postkastid, mudelitellimused ja OAuth-lingid Linear, Jira, GitHubi ja Trello jaoks, mis toetavad väliseid tahvleid. MCP konnektorid asuvad aadressil /admin/apps ja nende tekitatud tööriistad aadressil /admin/advanced/tools.

Heakskiidu tõkked tööriistakutsetel

Mõned tööriistakutsed peatuvad ja ootavad inimest. Kui see juhtub, käitus ei ebaõnnestu: kutse külmutatakse — tööriista nimi, tema argumentide räsi ja piisavalt olekut jätkamiseks — ning heakskiidutaotlus ilmub aadressil /api/approvals, et keegi seda vastaks. Jätkamine on idempotentne, nii et topeltheakskiit ei saa kutset kaks korda käivitada. Otsustaja näeb piiratud kokkuvõtet, mida küsitakse, ja täpsed argumendid ning algne käitus jäävad serveri poolele.

On kaks eraldi tõket ja neid seadistatakse erinevalt.

• Struktuursed tõkked on teatud sisseehitatud tööriistade omadus ja neid ei saa seadistada. Kirjade saatmine agendi enda postkastist või ühendatud postkastist, Gmaili mustandi saatmine, postkasti ühenduse katkestamine, kalendrisündmuse loomine, muutmine või tühistamine ning brauseritoiming, mis kirjutaks saidile, kuhu brauser pole sisse logitud, on kõik nii tõkestatud. Neile antakse vastamiseks 24-tunnine aken, mitte tavaline 30 minutit.
• Poliitikatõkked tulevad tool/invoke paari poliitikareeglitest. Reegel, mis lubab kutse, võib kanda requiresApproval, ja ilma kehtiva heakskiiduta tagastab hindamine APPROVAL_REQUIRED, selle asemel et käivitada. Reegleid hinnatakse esmalt keeldudes ja järjestatakse ulatuse järgi.

Milline admini ekraan kirjutab tööriistale requiresApproval-poliitikareegli — andmemudel ja jõustamine on mõlemad olemas, kuid me ei suutnud kinnitada ekraani, mis sellise reegli kirjutab.

Väline agent Nessie’ga ühendamine

Teine suund. Nessie käitab oma MCP serverit aadressil POST /mcp voogedastava HTTP kaudu ja see on olekuta: iga päring kannab oma mandaati ja lahendab oma tegija, seega puudub seanss, mille külge klienti replikal kinnitada. ChatGPT, Claude, Claude Code, Codex või agent kellegi sülearvutis saab töötada teie tahvlite, dokumentide ja klientidega selle tööriista seest, mida see inimene juba kasutab. Samm-sammuline juhend iga rakenduse kohta on Ühenda ChatGPT, Claude ja teised AI-rakendused.

Mis on sidumise mandaat tegelikult

See osa tuleb õigesti mõista, sest ilmne mõttemudel — API-võti koos õigustega — on vale.

Seotud mandaat ei ole kunagi identiteet. See nimetab inimest ja iga tööriistakutse käib selle inimese nimel, samu teenusefunktsioone kasutades, mida kutsuvad HTTP-marsruudid. Agent ei saa seetõttu ligi millelegi, millele inimene, kes selle laenas, ei pääseks klõpsates. Ulatused ainult kitsendavad seda ulatust; ükski ulatus ei laienda seda.

Elusust loetakse igal kutsel uuesti, mitte ei usaldata tokenist: tühistamine, aegumine, kasutaja tokeni versioon, tema organisatsiooniliikmelisus ja praegune roll. Degradeerimine, deaktiveerimine või „logi mind kõikjalt välja“ jõustub agendi järgmise kutsega, mitte mandaadi aegumisel.

Token on läbipaistmatu, prefiksiga nag1_, salvestatakse ainult SHA-256 räsina ja kehtib 90 päeva. Seda keeldutakse konkreetse 403-ga igal muul marsruudil kui MCP lõpp-punkt — selle esitamine mujal ei ole osaline edu, mida uuesti proovida, ja see hoiab ära, et „laenasin agendile oma tahvlid“ ei tähendaks „laenasin talle oma konto“.

Kaks viisi ühendada

Rakendus, mis suudab brauseri avada — ChatGPT, Claude, Claude Code, Codex — kasutab MCP autoriseerimisprofiili: OAuth 2.1 PKCE-ga (S256), dünaamilist kliendi registreerimist aadressil POST /mcp/oauth/register, värskendustokeneid ja ressursi indikaatoreid. Rakendus suunab inimese aadressile /settings/security, kus nad valivad, mida see tohib teha ja milliste oma meeskondadeni see ulatub, ning brauser tagastab rakendusele koodi. Selle juurdepääsutoken kehtib tund ja seda värskendatakse; ühendus kestab 90 päeva.

Käsurea agent ei kontrolli brauserit ega saa majutada tagasihelistamise URL-i, seega ta paarib end seadme autoriseerimisgrandi (RFC 8628) kaudu.

1. Agent kutsub POST /mcp/auth/device välja koos clientName-i ja soovitud scopes-ega. Tagasi tuleb device_code, lühike user_code, verification_uri ja verification_uri_complete, kus kood on päringus juba olemas, ning küsitlusintervall interval ja expires_in. Agent prindib URI.
2. Inimene avab selle URI-i sisse logituna aadressil /settings/security. Nad näevad, milline agent küsib, mille konto nime all see töötaks, kui kaua ja täpselt, mida see suudaks teha — ning valivad Luba või Ära luba.
3. Agent küsitleb POST /mcp/auth/token koos deviceCode-iga, arvestades authorization_pending, slow_down, expired_token ja access_denied. Edukalt saab ta { access_token, token_type, scope, expires_at }.

Mõlemal juhul on inimese samm, sest mandaat pärib inimese õigused, seega peab inimene valima selle laenamise. Siin ei teki juurdepääsu millestki tühjast. Ühendamise saab organisatsiooni jaoks terve välja lülitada aadressil /admin/security?tab=programs ja see vastus kontrollitakse siis, kui keegi ühenduse lubab, mitte siis, kui agent selle alustab.

Avastamine

Autentimata POST /mcp vastab 401-ga ja päisega WWW-Authenticate, mis osutab aadressile /.well-known/oauth-protected-resource (RFC 9728) ja nimetab selle päritolu autoriseerimisserveriks; selle metaandmed aadressil /.well-known/oauth-authorization-server (RFC 8414) nimetavad registreerimise, autoriseerimise, tokeni ja tühistamise lõpp-punktid. See ahel on kõik, mida klient vajab, kui tal on aadress. Domeenist aadressi leidmiseks loeb agent faili /.well-known/ai-catalog.json, mis nimetab Server Card’i aadressil /mcp/server-card (MCP Server Cards, SEP-2127). Seadmegrandi lõpp-punktid on loetletud kaitstud ressursi dokumendis võtme x-nessie-device-authorization all.

Juurutus võib vastata ka teisel, lühemal aadressil: Nessie Cloudi https://nessie.works/mcp suunatakse API-le ja klient, kes tuli sisse nii, saab selle aadressi tagasi ressursina, samas kui sisselogimine jääb API-sse. Ümbersuunamine ei toimiks, sest klient keeldub metaandmetest, mis nimetavad mõnda muud aadressi kui selle, mille ta sai. Operaator loetleb need päritolud muutujas NESSIE_MCP_ALIAS_ORIGINS.

Ulatused ja tööriistad

Ulatused on tahtlikult üldised — ulatust, mida keegi ei oska selgitada, ei seadistata õigesti. Ühendus, mis ulatub mitme meeskonnani, loetleb need käsuga nessie_team_list ja iga muu tööriist nimetab siis oma teamId.

Kutse ilma vajaliku ulatuseta tuleb tagasi tööriistatulemusena, mis nimetab ulatust, mida küsida, mitte transpordivigana, nii et mudel saab teatada kasuliku asja, selle asemel et korduvalt samasse müüri joosta.

Väliste jälgijate jaoks ei ole eraldi tööriistaperekonda. Tahvel on tahvel, olenemata sellest, kas tema ülesanded pärinevad Nessie’st või peegeldatakse need Linearist, Jirast, GitHubist või Trellost, nii et üks tööriistakomplekt katab mõlemad ning iga ülesanne ütleb, millest ta pärineb. Erinevus on kirjutamises: lugemiseks peegeldatud tahvel keeldub kirjutamisest sõnadega, öeldes agendile, et teine süsteem omab tööülesannet ja uuesti proovimine ei aita.

Dokumendi avaldamine on heakskiit, mitte ulatus

Agendid koostavad mustandeid; avaldab inimene. Seda reeglit jõustatakse Nessie enda agentide puhul, keeldudes agendi tegijast täielikult — kuid seotud mandaat lahendatakse isikuna, seega see keeldumine ei saa seda tabada. Värav peab asuma mujal.

Seega nessie_doc_publish ei avalda. See avab knowledge.page.publish heakskiidu — sama, mille avab Nessie agent — ja tagastab { status: "awaiting_approval", approvalId }. Küsitlemine tagastab sama taotluse, mitte ei ava teist. Otsuse teeb sama viisiga, nagu Nessies tehakse iga teine avaldamisotsus: inimene, selle dokumendi kohta, siis, kui see on olemas.

Avaldamise ulatust tahtlikult ei ole. See oli olemas — linnuke sidumise ajal, mis ütles, et see agent võib avaldada — ja see kaotati. See otsustas korraga ja üheksakümneks päevaks küsimuse, mida toode mujal iga dokumendi kohta küsib, ning otsustas selle enne, kui dokument olemas oli, seega ei saanud linnukese panev inimene teada, mida ta avaldamisele nõustub. nessie_doc_publish nõuab documents_write, sest küsimine ei ole tasuta — see loeb lehe ja paneb otsuse kellegi ette — kuid see ulatus ei anna avaldamise kohta mitte midagi.

Taotlusele salvestatakse kaks identiteeti ja erinevus on oluline. Taotleja on mandaat, mitte inimene, kelle nimel see tegutseb. Nõutav heakskiitja on see inimene ja ainult tema võib vastata. Kui taotlusel nimetataks isik taotlejaks, diskvalifitseeriks reegel, mis takistab kedagi oma taotlust heaks kiitmast, just selle ühe inimese, kellel on õigus otsustada.

Mida on seotud, näha ja tühistada

Inimese enda seotud agendid on loetletud aadressil /settings/security, koos sildi ja tühistamisnupuga iga kohta. Omanik või organisatsiooni admin näeb iga organisatsiooni mandaati aadressil /admin/security?tab=programs — mida igaüks nimetatakse, mida ta tohib, kas ta on elus ja kelle kontot ta laenab — ning saab neist igaühe tühistada. Isiklik loend jääb ainult enda omaks: elavate mandaatide loend on pigem sissepääsude nimekiri kui üldine lugemisvara.

Mandaadi kaudu tehtud muudatused omistatakse laenanud inimesele ja kannavad auditi metaandmetes mandaadi id-d, nii et logi saab eristada inimese enda muudatuse sellest, mille tema agent tema eest tegi.

Mis pole veel saadaval

Ütleme selgelt, sest protokolli võimekuse ja konkreetse serveri võimekuse vahe on koht, kus dokumentatsioon tavaliselt valetab:

• Vestlused, kanalid, käitused ja agentide haldus ei ole MCP kaudu avatud.
• Programm koostab uudiskirja ja inimene saadab selle: miski ei saada, ajasta ega kustuta kampaaniat ning e-kiri ise kirjutatakse disaineris.
• Kontaktide sidumine ja ühendamine, CRM-i skeemi muudatused, impordid ja kanalite seadistamine jäävad brauseris inimese hooleks.
• Ühendamise lüliti on organisatsioonitasemel seadistus. Meeskonna- ja isiklikke alistusi ei saa meeskond ega inimene praegu seada.