MCP ir prijungti įrankiai

Prijunkite Nessie prie MCP serverių ir susiekite išorinį agentą, kad jis galėtų dirbti Nessie jūsų vardu.

Kas yra MCP

Modelio konteksto protokolas (Model Context Protocol) yra mažas, atviras susitarimas, kaip aprašyti įrankius kalbos modeliui ir juos iškviesti. Serveris paskelbia, ką moka – pavadintų įrankių sąrašą, kiekvienas su JSON schema argumentams – o klientas šį sąrašą atranda ir iškviečia modelio vardu. Jis tyčia paprastas: vertė tame, kad vieną kartą parašyta integracija veikia su kiekvienu modeliu ir kiekvienu produktu, kuris kalba tuo protokolu.

Nessie yra abiejose pusėse

Tai verta nurodyti tiksliai, nes dvi pusės lengvai painiojamos, be to, jos tyčia gyvena skirtingais keliais.

• Išeinantis. Nessie yra MCP klientas. Jūs prijungiate serverius, kuriuos kas nors kitas valdo, o jų siūlomi įrankiai tampa įrankiais, kuriuos naudoja jūsų agentai. Valdymo paviršius yra /api/mcp/*.
• Įeinantis. Nessie yra ir MCP serveris. Kitur veikiantis agentas – Claude Code ar Codex kūrėjo kompiuteryje – gali kreiptis į jūsų lentas ir dokumentus. Tas galinis taškas yra POST /mcp, tyčia už /api ribų, kad dvi priešingos reikšmės nebūtų viena nuo kitos vieno kelio segmento atstumu.

Kaip prijungti MCP serverį prie Nessie

Katalogo įrašai ir egzemplioriai

Yra du objektai, ir skirtumas svarbus:

• Katalogo įrašas yra serverio apibrėžimas – jo pavadinimas, transportas, tai, kaip jis autentifikuojasi. Jis parašomas vieną kartą ir gali būti bendrinamas.
• Egzempliorius yra tas įrašas, įdiegtas vienoje apimtyje su prieigos duomenimis, kurie į jį patenka. Tą patį įrašą įdiegus dviem skirtingoms komandoms, susidaro du egzemplioriai.

Dauguma žmonių nei vieno, nei kito tiesiogiai netvarko. Įėjimas administravimo sąsajoje yra programų parduotuvė adresu /admin/apps: ji naršo tą patį katalogą, paslėpus prijungimo detales, o paspaudus Connect ant skelbimo sukuriamas egzempliorius. Operatoriai, norintys neapdorotų objektų, naudoja /api/mcp/catalog ir /api/mcp/instances.

Jei serverio katalogo dar nėra, POST /api/mcp/discover priima URL ir nuskaito, ką serveris apie save sako, o POST /api/mcp/library/import įtraukia įrašą iš viešosios serverių bibliotekos. Pirmojo paleidimo prijungimą galima sukurti tiesiai iš URL su POST /api/apps/custom.

Transportai

Nessie jungiasi prie nuotolinių serverių per HTTP. Veikia du transportai: srautinis HTTP (dabartinis MCP transportas) ir senesnis HTTP+SSE transportas. Rinkitės http, nebent serveris siūlo tik sse.

stdio transportas atmetamas jūsų kuriamoms jungtims. stdio reiškia, kad MCP serveris yra vietinis procesas, kurį paleidžia šeimininkas, o savavališkų programų vykdymas Nessie serveryje nėra dalykas, kurį operatorius gali prasmingai peržiūrėti. Serveriai, kurie skelbiami tik kaip paketas vietiniam paleidimui, dėl to paties pašalinami iš bibliotekos importų. Protokolo lauke yra reikšmė ws, bet ji neįgyvendinta – jungtis su ja nepavyksta, kai Nessie bando ją atidaryti.

Kaip Nessie autentifikuojasi serveryje

Katalogo įrašas deklaruoja vieną iš penkių metodų: none, api_key, bearer, basic arba oauth2.

api_key yra antraštės įterpimas, o įrašas nurodo, kuri antraštė ir koks priešdėlis – taigi Authorization: Bearer …, X-API-Key: … ir X-Auth-Token: Token … yra tas pats metodas, tik skirtingai sukonfigūruotas. Raktas įklijuojamas vieną kartą su POST /api/mcp/instances/:instanceId/secret ir daugiau niekada neperskaitomas; jokia egzempliorių maršrutų atsakymas neperduoda prisijungimo duomenų nuorodos.

oauth2 turi dvi formas. Serveris su fiksuotais galiniais taškais juos turi katalogo įraše. Serveris, kuris skelbia standartinius metaduomenis, nieko konfigūruoti neturi: Nessie perskaito išteklių ir autorizacijos serverio dokumentus ir pati susikuria klientą per dinaminę kliento registraciją arba per kliento ID metaduomenų dokumentą, kurį paskelbia savo well-known kelyje. Abiem atvejais rankos paspaudimas yra POST /api/mcp/instances/:instanceId/oauth/start, po kurio tiekėjas nukreipia atgal į GET /api/mcp/oauth/callback. Būsenos žetonas vienkartinis, saugomas duomenų bazėje ir galioja dešimt minučių, o PKCE visada naudojamas.

Viena taisyklė daugelį nustemba: net organizacijos savininkas negali priskirti asmeninio ar OAuth žetono kitam asmeniui. Bendrą prisijungimo duomenį galima turėti tik API raktų įrašui, kuris patvirtintas kaip toks; visa kita atmetama. Žmogui priklausantys prisijungimo duomenys lieka to žmogaus duomenimis.

Kur laikomi prisijungimo duomenys

Jungčių paslaptys ir OAuth žetonų rinkiniai saugomi jūsų pačių Postgres duomenų bazėje, AES-256-GCM apvalkaluose, kuriuos apibrėžia diegimo nepriklausomai versijuojamas šifravimo raktų žiedas, ir pasiekiami tik per neskaidrias nuorodas secret_*. Jie tyčia nėra išorinėje paslapčių saugykloje, kurioje laikomos kitos Nessie paslaptys. Gamybinis diegimas, kuris nesukonfigūravo šifruotos saugyklos, paleidimo metu nutrūksta, o ne baigia OAuth rankos paspaudimą, kurį paskui tiesiog prarastų.

Kur pasiekia jungtis

Egzempliorius įdiegiamas vienoje iš šešių apimčių: system, organization, project, team, channel arba user. Ta apimtis yra griežta riba tam, kurie paleidimai gali ją naudoti, o suteikimai gali ją tik siaurinti, niekada plėsti – todėl jungtis, kurią įdiegėte su savo paskyra, negali tyliai tapti visos organizacijos jungtimi.

Kas ir kur gali diegti, seka tą pačią formą: organizacijos savininkai ir administratoriai valdo diegimus bet kurioje apimtyje; visi kiti diegia jungtis savo user apimtyje ir mato bendrus diegimus, kuriuos turi teisę pasiekti.

Agento įrankio suteikimas

Prijungus serverį, jo įrankiai niekam automatiškai neperduodami. Įdiegus egzempliorių, Nessie jį patikrina ir kiekvieną jo skelbiamą įrankį įtraukia į įrankių registrą – tai, ką administravimo sąsaja rodo adresu /admin/advanced/tools: įmontuoti įrankiai, MCP įrankiai, paketų (bundle) įrankiai ir vykdytojo įrankiai viename sąraše, kiekvienas su savo šaltiniu ir būsena.

Projektuojamas įrankis turi vieną iš trijų būsenų: active, pending_review arba disabled. Įrankiai iš bendros apimties diegimo atkeliauja kaip pending_review ir prieš agentui juos matant turi būti patvirtinti tame puslapyje; įrankiai iš jūsų user apimties diegimo iš karto aktyvūs, nes vienintelis čia matomas asmuo esate jūs. Peržiūra nėra vienkartinis formalumas, o pasikartojantis: jei vėlesnis patikrinimas nustato, kad įrankio aprašymas ar schema pasikeitė, jis grįžta į pending_review ir nebesiūlomas, kol kas nors pažiūri į pakeitimą.

Tai, kurie agentai gali kviesti aktyvų įrankį, nustatoma dviem būdais:

• Jungtis, sukurta per programų parduotuvę, reikalauja aiškaus suteikimo. Agentas gauna įrankį tik tada, kai suteikimas jį nurodo, o suteikimas tikrinamas pagal dabartinį įrankio pirštų atspaudą (fingerprint), todėl pakeistam įrankiui reikia naujo sprendimo.
• Kitaip įrankis pagal numatytuosius nustatymus įjungtas agentams, pasiekiamiems pagal jo apimtį, o atskiri agentai išjungiami įrankio detalių skydelyje.

Suteikimas nurodo tiksliai vieną principalą – vaidmenį arba agentą, bet niekada abu – o draudimas nugali leidimą. user apimties jungčiai klausimas nekyla: bet kuris agentas, su kuriuo tas asmuo kalba, gali ją naudoti, o tik aiškus išjungimas tai sustabdo.

Dalykas, kurį lengva ieškoti netinkamoje vietoje: administravimo sąsajos /settings/accounts yra susietos paskyros – Slack, pašto dėžutės, modelių prenumeratos ir OAuth nuorodos į Linear, Jira, GitHub ir Trello, kurios palaiko išorines lentas. MCP jungtys yra adresu /admin/apps, o jų sukurti įrankiai – adresu /admin/advanced/tools.

Patvirtinimo vartai įrankių iškvietimams

Kai kurie įrankių iškvietimai sustoja ir laukia žmogaus. Tada paleidimas nenutrūksta: iškvietimas užšaldomas – įrankio pavadinimas, jo argumentų maiša ir pakankama būsena tęsti – o patvirtinimo prašymas atsiranda adresu /api/approvals, kad kas nors į jį atsakytų. Tęsimas idempotentiškas, todėl pasikartojantis patvirtinimas negali iškviesti to paties dalyko du kartus. Sprendimą priimantis asmuo mato ribotą santrauką to, ko prašoma; tikslūs argumentai ir paleidimas, iš kurio jie atėjo, lieka serverio pusėje.

Yra du skirtingi vartai, ir jie konfigūruojami skirtingai:

• Struktūriniai vartai yra tam tikrų įmontuotų įrankių savybė ir nekonfigūruojami. Siuntimas laišku iš agento paštinės dėžutės arba iš prijungtos, Gmail juodraščio siuntimas, pašto paskyros atjungimas, kalendoriaus įvykio kūrimas, keitimas ar atšaukimas ir naršyklės veiksmas, kuris rašytų į svetainę, kurioje naršyklė neprisijungusi, – visi taip saugomi. Atsakymui jiems skiriamas 24 valandų langas, o ne įprastos 30 minučių.
• Politikos vartai ateina iš politikos taisyklių poros tool/invoke. Taisyklė, leidžianti iškvietimą, gali turėti requiresApproval, o be patikrinto patvirtinimo vertinimas grąžina APPROVAL_REQUIRED, o ne vykdo. Taisyklės vertinamos pradedant nuo draudimų ir surikiuotos pagal apimtį.

Nepatvirtinome, kuris administravimo ekranas sukuria requiresApproval politikos taisyklę įrankiui – duomenų modelis ir vykdymas abu įdiegti, tačiau ekranas, kuris tokią taisyklę įrašo, nepavyko patvirtinti.

Išorinio agento prijungimas prie Nessie

Kita kryptis. Nessie turi savo MCP serverį adresu POST /mcp, per srautinį HTTP, ir jis be būsenos: kiekviena užklausa turi savo prisijungimo duomenis ir pati nustato savo veikėją, todėl nėra sesijos, kurią reikėtų prisegti prie vienos replikos. ChatGPT, Claude, Claude Code, Codex ar agentas kieno nors nešiojamame kompiuteryje gali dirbti su jūsų lentomis, dokumentais ir klientais iš to įrankio, kurį tas asmuo jau naudoja. Žingsnis po žingsnio kiekvienai programai – Prijunkite ChatGPT, Claude ir kitas DI programas.

Ką iš tikrųjų reiškia susieti prisijungimo duomenys

Tai reikia suprasti teisingai, nes akivaizdus mąstymo modelis – API raktas su pridėtomis teisėmis – yra neteisingas.

Susieti prisijungimo duomenys niekada nėra tapatybė. Jie nurodo žmogų, ir kiekvienas įrankio iškvietimas vykdomas to žmogaus vardu, prieš tas pačias paslaugų funkcijas, kurias iškviečia HTTP maršrutai. Todėl agentas negali pasiekti nieko, ko asmuo, kuris jį įgaliojo, negalėtų pasiekti spustelėdamas. Apimtys tik siaurina tą pasiekiamumą; nėra apimties, kuri jį plėstų.

Gyvumas tikrinamas kiekvieno iškvietimo metu, o ne patikimas iš žetono: atšaukimas, galiojimo pabaiga, naudotojo žetono versija, jo narystė organizacijoje ir dabartinis vaidmuo. Pažeminimas, deaktyvavimas ar „atsijungti visur“ pasiekia agento kitą iškvietimą, o ne laukia prisijungimo duomenų galiojimo pabaigos.

Žetonas yra neskaidrus, turi priešdėlį nag1_, saugomas tik kaip SHA-256 maiša ir galioja 90 dienų. Jis atmetamas su konkrečiu 403 bet kuriame maršrute, išskyrus MCP galinį tašką – pateikus jį kitur, tai nėra dalinė sėkmė, kurios reikėtų kartoti; būtent taip užtikrinama, kad „paskolinau agentui savo lentas“ nereiškia „paskolinau jam savo paskyrą“.

Du būdai prisijungti

Programa, kuri gali atverti naršyklę – ChatGPT, Claude, Claude Code, Codex – naudoja MCP autorizacijos profilį: OAuth 2.1 su PKCE (S256), dinaminę kliento registraciją adresu POST /mcp/oauth/register, atnaujinimo žetonus ir resursų nurodymus (resource indicators). Programa siunčia asmenį į /settings/security, jis pasirenka, ką programa gali daryti ir kurias jo komandas pasiekia, o naršyklė grįžta į programą su kodu. Jos prieigos žetonas galioja valandą ir atnaujinamas; jungtis galioja 90 dienų.

Komandinės eilutės agentas nevaldo naršyklės ir negali priimti atgalinio iškvietimo URL, todėl vietoj to susiejama per įrenginio autorizacijos suteikimą (RFC 8628).

1. Agentas kviečia POST /mcp/auth/device su clientName ir norimomis scopes. Atsakymu gauna device_code, trumpą user_code, verification_uri ir verification_uri_complete, kuriame kodas jau nurodytas užklausoje, taip pat apklausos interval ir expires_in. Agentas išspausdina URI.
2. Asmuo atidaro tą URI prisijungęs, adresu /settings/security. Jis mato, kuris agentas prašo, kieno paskyra jis veiktų, iki kada ir kiek tiksliai jis galėtų daryti – ir pasirenka Leisti arba Neleisti.
3. Agentas apklausia POST /mcp/auth/token su deviceCode, paisydamas authorization_pending, slow_down, expired_token ir access_denied reikšmių. Sėkmės atveju gauna { access_token, token_type, scope, expires_at }.

Abiem atvejais yra žmogaus žingsnis, nes prisijungimo duomenys paveldi asmens teises, todėl asmuo turi nuspręsti juos suteikti. Čia niekas nesukuria prieigos iš nieko. Prijungimą visai organizacijai galima išjungti adresu /admin/security?tab=programs, o šis atsakymas tikrinamas tada, kai kas nors leidžia jungtį, o ne tada, kai agentas ją pradeda.

Atradimas

Neautentifikuota POST /mcp užklausa atsako 401 su antrašte WWW-Authenticate, nukreipiančia į /.well-known/oauth-protected-resource (RFC 9728); tas dokumentas nurodo šį kilmės serverį kaip autorizacijos serverį. Jo metaduomenys adresu /.well-known/oauth-authorization-server (RFC 8414) nurodo registracijos, autorizacijos, žetonų ir atšaukimo galinius taškus. Tai viskas, ko klientui reikia, kai jis turi adresą. Norėdamas iš domeno rasti adresą, agentas skaito /.well-known/ai-catalog.json, kuris nurodo serverio kortelę adresu /mcp/server-card (MCP Server Cards, SEP-2127). Įrenginio suteikimo galiniai taškai išvardyti išteklių dokumente po x-nessie-device-authorization.

Diegimas taip pat gali atsakyti antru, trumpesniu adresu: Nessie Cloud https://nessie.works/mcp peradresuojamas į API, o klientas, atėjęs tuo keliu, gauna tą adresą atgal kaip išteklių – prisijungimas vis tiek vyksta API adresu. Peradresavimas čia netiktų, nes klientas atmeta metaduomenis, kuriuose nurodomas kitas adresas nei tas, kurį jis gavo. Operatorius tokias kilmes išvardija NESSIE_MCP_ALIAS_ORIGINS.

Apimtys ir įrankiai

Apimtys tyčia plačios – apimtis, kurios niekas negali paaiškinti, niekas nenustato teisingai. Jungtis, pasiekianti daugiau nei vieną komandą, jas išvardija su nessie_team_list, o kiekvienas kitas įrankis tada nurodo savo teamId.

Iškvietimas be reikalingos apimties grąžina įrankio rezultatą, kuriame nurodoma, kokios apimties prašyti, o ne perdavimo klaida, todėl modelis gali pateikti naudingą atsakymą, o ne kartoti bandymus į sieną.

Išorinių sekimo sistemų įrankiams atskiros įrankių šeimos nėra. Lenta yra lenta, nesvarbu, ar jos užduotys kilo Nessie, ar sinchronizuotos iš Linear, Jira, GitHub ar Trello, todėl vieną įrankių rinkinį naudoja abu, o kiekviena užduotis nurodo, iš kur ji. Skiriasi rašymas: lenta, sinchronizuojama iš tik skaitomo šaltinio, žodžiais atmeta rašymą – agentui sakoma, kad užduotį valdo kita sistema, ir bandyti dar kartą nėra prasmės.

Dokumento paskelbimas yra patvirtinimas, o ne apimtis

Agentai rengia juodraščius; paskelbia asmuo. Ši taisyklė Nessie savo agentams įgyvendinama atmetant agento veikėją be išlygų, bet susieti prisijungimo duomenys veikia kaip asmuo, todėl šis atmetimas jų nepagautų. Vartai turi būti kitur.

Todėl nessie_doc_publish neskelbia. Jis atidaro knowledge.page.publish patvirtinimą – tą patį, kurį atidaro Nessie agentas – ir grąžina { status: "awaiting_approval", approvalId }. Kartotinis kvietimas grąžina tą patį prašymą, o ne atidaro antrą. Sprendimas priimamas taip, kaip priimami visi kiti Nessie publikavimo sprendimai: asmens, dėl to konkretaus dokumento, tą akimirką, kai jis egzistuoja.

Publikavimo apimties tyčia nėra. Ji buvo – varnelė susiejant porą sakė, kad šis agentas gali publikuoti – ir ji panaikinta. Ji vieną kartą ir devyniasdešimčiai dienų nusprendė klausimą, kurį produktas visur kitur klausia pagal dokumentą, ir nusprendė jį dar prieš tai, kai dokumentas egzistavo, todėl asmuo, pažymėjęs varnelę, negalėjo žinoti, ką sutinka paskelbti. nessie_doc_publish reikalauja documents_write, nes klausti nėra nemokama – jis perskaito puslapį ir sprendimą pateikia kažkam – tačiau ta apimtis nesuteikia jokios teisės dėl publikavimo.

Prašyme įrašomos dvi tapatybės, ir skirtumas yra esminis. Prašytojas yra prisijungimo duomenys, o ne žmogus, kurio vardu jie veikia. Reikalaujamas tvirtintojas yra tas žmogus, ir tik jis gali atsakyti. Jei prašytoju būtų nurodytas asmuo, taisyklė, neleidžianti kam nors patvirtinti savo prašymo, diskvalifikuotų vienintelį asmenį, turintį teisę spręsti.

Matyti ir atšaukti tai, kas susieta

Asmens susieti agentai rodomi adresu /settings/security, su pavadinimu ir atšaukimo valdikliu kiekvienam. Savininkas ar organizacijos administratorius mato kiekvieną organizacijos prisijungimo duomenį adresu /admin/security?tab=programs – kaip jis vadinasi, ką gali daryti, ar jis dar galioja ir kieno paskyra jį skolinasi – ir gali atšaukti bet kurį. Asmens sąrašas lieka tik savo: gyvų prisijungimo duomenų sąrašas yra įsitvirtinimo taškų sąrašas, o ne bendra informacija.

Įrašai, atlikti per prisijungimo duomenis, priskiriami asmeniui, kuris prisijungimo duomenis skolina, ir turi prisijungimo duomenų ID audito metaduomenyse, todėl žurnalas gali atskirti asmens paties pakeitimą nuo to, kurį jo agentas atliko jo vardu.

Ko dar nėra

Aiškiai, nes atotrūkis tarp protokolo galimybių ir konkretaus serverio galimybių yra vieta, kur dokumentacija paprastai meluoja:

• Pokalbiai, kanalai, paleidimai ir agentų valdymas per MCP neatskleidžiami.
• Programa parengia naujienlaiškį, o asmuo jį siunčia: niekas nesiunčia, nesuplanuoja ir neištrina kampanijos, o pats laiškas rašomas dizaineryje.
• Kontaktų sujungimas ir susiejimas, CRM schemos pakeitimai, importai ir kanalų nustatymas lieka asmens naršyklėje.
• Prijungimo jungiklis yra organizacijos lygio nustatymas. Komandų lygio ir asmeniniai perrašymai šiuo metu nėra nustatomi nei komandos, nei asmens.