MCP dhe mjetet e lidhura

Lidhni Nessie me serverë MCP, dhe çiftoni një agjent të jashtëm që të mund të punojë në Nessie në emrin tuaj.

Çfarë është MCP

Model Context Protocol është një konvencion i vogël dhe i hapur për të përshkruar mjete për një model gjuhësor dhe për t'i thirrur ato. Një server deklaron çfarë mund të bëjë — një listë mjetesh të emërtuara, secila me një skemë JSON për argumentet e veta — dhe një klient e zbulon atë listë dhe i thërret mjetet në emër të modelit. Është qëllimisht e thjeshtë: vlera qëndron në faktin që një integrim i shkruar një herë funksionon me çdo model dhe me çdo produkt që e flet atë.

Nessie është në të dyja anët e tij

Kjo duhet thënë me saktësi, sepse dy gjysmat ngatërrohen lehtë dhe jetojnë në shtigje qëllimisht të ndryshme.

• Dalës. Nessie është një klient MCP. Ju lidhni servera që i drejton dikush tjetër, dhe mjetet që ata ekspozojnë bëhen mjete që agjentët tuaj mund t'i përdorin. Sipërfaqja e menaxhimit është /api/mcp/*.
• Hyrës. Nessie është gjithashtu një server MCP. Një agjent që ekzekutohet diku tjetër — Claude Code ose Codex në makinën e një zhvilluesi — mund të thërrasë brenda tabelave dhe dokumenteve tuaja. Ai endpoint është POST /mcp, jashtë /api me qëllim, që dy kuptimet e kundërta të mos jenë një segment shtegu larg njëri-tjetrit.

Lidhja e një serveri MCP me Nessie

Hyrjet e katalogut dhe instancat

Ka dy objekte, dhe dallimi ka rëndësi:

• Një hyrje katalogu është përkufizimi i një serveri — emri i tij, transporti i tij, mënyra si autentikohet. Shkruhet një herë dhe mund të ndahet.
• Një instancë është ajo hyrje e instaluar në një fushëveprim, me kredencialet që e arrijnë. Instalimi i së njëjtës hyrje për dy ekipe të ndryshme prodhon dy instanca.

Shumica e njerëzve nuk i prekin as njëra, as tjetra drejtpërdrejt. Hyrja në admin është dyqani i aplikacioneve te /admin/apps: ai shfleton të njëjtin katalog me detajet e lidhjes të fshehura, dhe Connect në një listim krijon një instancë. Operatorët që duan objektet e papërpunuara përdorin /api/mcp/catalog dhe /api/mcp/instances.

Nëse një server nuk është ende në katalog, POST /api/mcp/discover merr një URL dhe kthen atë që thotë serveri për vetveten, ndërsa POST /api/mcp/library/import tërheq një hyrje nga biblioteka publike e serverave. Një lidhje e parë mund të krijohet edhe direkt nga një URL me POST /api/apps/custom.

Transportet

Nessie lidhet me serverat e largët përmes HTTP. Funksionojnë dy transporte: HTTP i transmetueshëm (transporti aktual i MCP) dhe transporti më i vjetër HTTP+SSE. Zgjidhni http përveç nëse serveri ofron vetëm sse.

Transporti stdio refuzohet për lidhësit që ju shkruani. stdio do të thotë që serveri MCP është një proces lokal që host-i e nis, dhe ekzekutimi i programeve të çfarëdoshme brenda serverit të Nessie është diçka që një operator nuk mund ta rishikojë me kuptim. Serverat që publikohen vetëm si paketë për t'u ekzekutuar lokalisht hiqen nga importet e bibliotekës për të njëjtën arsye. Vlera ws ekziston në fushën e protokollit dhe nuk është e implementuar — një lidhje që e përdor dështon kur Nessie përpiqet ta hapë.

Si e autentikon Nessie veten te serveri

Një hyrje katalogu deklaron një nga pesë metodat: none, api_key, bearer, basic ose oauth2.

api_key është injektim i header-it, dhe hyrja thotë cilin header dhe çfarë prefiksi — kështu që Authorization: Bearer …, X-API-Key: … dhe X-Auth-Token: Token … janë e njëjta metodë e konfiguruar ndryshe. Vetë çelësi ngjitet një herë me POST /api/mcp/instances/:instanceId/secret dhe nuk lexohet më kurrë; asnjë përgjigje nga rrugët e instancës nuk mban një referencë kredenciali.

oauth2 ka dy forma. Një server me endpoint-e fikse i ka ato në hyrjen e vet të katalogut. Një server që publikon metadata standarde nuk kërkon asnjë konfigurim: Nessie lexon dokumentet e burimit të mbrojtur dhe të autorizimit, dhe krijon vetë një klient, ose përmes regjistrimit dinamik të klientit, ose përmes dokumentit të metadatave të ID-së së klientit që e publikon në shtegun e vet well-known. Në të dyja rastet, dorëzimi është POST /api/mcp/instances/:instanceId/oauth/start, e pas kësaj ridrejtimi i ofruesit mbrapsht te GET /api/mcp/oauth/callback. Token-i i gjendjes përdoret vetëm një herë, mbahet në bazën e të dhënave dhe vlen për dhjetë minuta, dhe PKCE përdoret gjithmonë.

Një rregull i habit shumë njerëz: edhe pronari i një organizate nuk mund t'i bashkëngjisë një token personal ose OAuth dikujt tjetër. Një kredencial i përbashkët është e mundur vetëm për një hyrje me çelës API që është validuar si e tillë; çdo gjë tjetër refuzohet. Një kredencial që i përket një personi mbetet kredencial i atij personi.

Ku ruhen kredencialet

Sekretet e lidhësve dhe paketat e token-ave OAuth ruhen në bazën tuaj të të dhënave Postgres, në mbështjellës AES-256-GCM me qëllim të caktuar, nën unazën e çelësave të enkriptimit të vendosjes, e cila version-ohet në mënyrë të pavarur, dhe adresohen vetëm me referenca të pazbërthyeshme secret_*. Ato nuk ndodhen qëllimisht në kasafortën e jashtme të sekreteve që mban sekretet e tjera të Nessie. Një vendosje në prodhim që nuk e ka konfiguruar depon e enkriptuar refuzon të nisë, në vend që të plotësojë një dorëzim OAuth që më pas do ta humbiste.

Ku arrin një lidhje

Një instancë instalohet në një nga gjashtë fushëveprimet: system, organization, project, team, channel ose user. Ai fushëveprim është një tavan i fortë për cilat ekzekutime mund ta përdorin, dhe lejet mund ta ngushtojnë atë më tej, kurrë ta zgjerojnë — kështu që një lidhës që keni instaluar me llogarinë tuaj nuk mund të bëhet heshtas një lidhës për gjithë organizatën.

Kush mund të instalojë ku ndjek të njëjtën formë: pronarët dhe administratorët e organizatës menaxhojnë instalimet në çdo fushëveprim; të tjerët instalojnë lidhës te fushëveprimi i tyre user, dhe mund të shohin instalimet e përbashkëta ku kanë të drejtë të arrijnë.

Dhënia e një mjeti një agjenti

Lidhja e një serveri nuk ua jep mjetet e tij askujt. Kur instalohet një instancë, Nessie e provon dhe e projekton çdo mjet që reklamon në regjistrin e mjeteve, dhe kjo është ajo që admin-i shfaq te /admin/advanced/tools — mjetet e integruara, mjetet MCP, mjetet e paketave dhe mjetet e ekzekutuesit në një listë të vetme, secila me burimin dhe statusin e vet.

Një mjet i projektuar ka një nga tre statuset: active, pending_review ose disabled. Mjetet nga një instalim me fushëveprim të përbashkët vijnë si pending_review dhe duhet të miratohen në atë faqe përpara se një agjent t'i shohë; mjetet nga instalimi juaj me fushëveprim user janë aktive menjëherë, sepse i vetmi person i ekspozuar jeni ju. Rishikimi është i përsëritur, jo një ceremoni e njëhershme: nëse një provë e mëvonshme gjen që përshkrimi ose skema e një mjeti është zhvendosur, ai kthehet në pending_review dhe pushon së qeni i ofruar derisa dikush ta shikojë ndryshimin.

Cilët agjentë mund ta thërrasin pastaj një mjet aktiv vendoset në dy mënyra:

• Një lidhje e krijuar përmes dyqanit të aplikacioneve kërkon një leje të qartë. Një agjent e merr mjetin vetëm kur një leje e emëron, dhe leja kontrollohet kundrejt gjurmës aktuale të mjetit, kështu që një mjet i ndryshuar kërkon një vendim të ri.
• Ndryshe, mjeti është i aktivizuar si parazgjedhje për agjentët brenda arritjes së fushëveprimit të saj, dhe agjentët individualë çaktivizohen në panelin e detajeve të mjetit.

Një leje emëron saktësisht një parim — një rol ose një agjent, kurrë të dyja — dhe një refuzim mposht një lejim. Për një lidhje me fushëveprim user pyetja nuk lind fare: çdo agjent me të cilin bisedon ai person mund ta përdorë, dhe një çaktivizim i qartë është e vetmja gjë që e mban jashtë.

Një gjë që është e lehtë të kërkohet në vendin e gabuar: /settings/accounts në admin janë llogaritë e lidhura — Slack, kutitë postare, abonimet e modeleve dhe lidhjet OAuth me Linear, Jira, GitHub dhe Trello që mbështesin tabelat e jashtme. Lidhësit MCP janë te /admin/apps, dhe mjetet që ata prodhojnë janë te /admin/advanced/tools.

Portat e miratimit për thirrjet e mjeteve

Disa thirrje mjetesh ndalen dhe presin një person. Kur ndodh kjo, ekzekutimi nuk dështon: thirrja mbetet e ngrirë — emri i mjetit, një hash i argumenteve të saj dhe mjaft gjendje për ta rifilluar — dhe një kërkesë miratimi shfaqet te /api/approvals, që dikush ta përgjigjë. Rifillimi është idempotent, kështu që një miratim i dyfishtë nuk mund ta ekzekutojë thirrjen dy herë. Personi që vendos sheh një përmbledhje të kufizuar të asaj që kërkohet; argumentet e sakta dhe ekzekutimi burimor qëndrojnë në server.

Ka dy porta të ndryshme, dhe konfigurohen ndryshe.

• Portat strukturore janë një veti e disa mjeteve të integruara dhe nuk konfigurohen. Dërgimi i postës nga kutia postare e një agjenti ose nga një e lidhur, dërgimi i një drafti Gmail, shkëputja e një llogarie emaili, krijimi, ndryshimi ose anulimi i një ngjarjeje kalendari, dhe një veprim shfletuesi që do të shkruante në një faqe ku shfletuesi nuk ka hyrë janë të gjitha të mbrojtura me portë në këtë mënyrë. Ato kanë një dritare 24-orëshe për t'u përgjigjur, jo 30 minutat e zakonshme.
• Portat e politikës vijnë nga rregullat e politikës mbi çiftin tool/invoke. Një rregull që lejon një thirrje mund të mbartë requiresApproval, dhe pa një miratim të verifikuar vlerësimi kthen APPROVAL_REQUIRED në vend që të ekzekutojë. Rregullat vlerësohen me refuzimin e parë dhe renditen sipas fushëveprimit.

Cili ekran i admin-it shkruan një rregull politike requiresApproval për një mjet — modeli i të dhënave dhe zbatimi janë të dyja në vend, por nuk e kemi konfirmuar ekranin që shkruan një rregull të tillë.

Lidhja e një agjenti të jashtëm me Nessie

Drejtimi tjetër. Nessie ekzekuton një server MCP të vet te POST /mcp, përmes HTTP të transmetueshëm, dhe është pa gjendje: çdo thirrje mban kredencialin e vet dhe e zgjidh vetë aktorin e vet, kështu që nuk ka sesion që ta lidhësh një klient me një replikë. ChatGPT, Claude, Claude Code, Codex ose një agjent në laptopin e dikujt mund të punojnë me tabelat, dokumentet dhe klientët tuaj nga brenda çdo mjet që ai person e përdor tashmë. Udhëzimi hap pas hapi për çdo aplikacion është Lidhni ChatGPT, Claude dhe aplikacione të tjera AI.

Çfarë është në të vërtetë një kredencial i çiftuar

Kjo është pjesa që duhet kuptuar drejt, sepse modeli mendor i dukshëm — një çelës API me leje të bashkangjitura — është i gabuar.

Një kredencial i çiftuar nuk është kurrë një identitet. Ai emëron një njeri, dhe çdo thirrje mjetesh ekzekutohet si ai njeri, kundër të njëjtave funksione shërbimi që thërrasin rrugët HTTP. Një agjent për këtë arsye nuk mund të arrijë asgjë që personi që ia huazoi nuk mund ta arrijë duke klikuar. Fushëveprimet vetëm e ngushtojnë atë arritje; nuk ekziston asnjë fushëveprim që e zgjeron atë.

Gjallëria lexohet në çdo thirrje të vetme, dhe nuk merret besë nga token-i: shfuqizimi, skadimi, versioni i token-it të përdoruesit, anëtarësia në organizatë dhe roli aktual. Një ulje gradë, një çaktivizim ose një “më nxirr kudo” zbret në thirrjen e ardhshme të agjentit, jo në skadimin e kredencialit.

Token-i është i pazbërthyeshëm, me prefiksin nag1_, ruhet vetëm si hash SHA-256, dhe jeton 90 ditë. Refuzohet me një 403 të veçantë në çdo rrugë tjetër përveç endpoint-it MCP — ta paraqesësh diku tjetër nuk është një sukses i pjesshëm që duhet riprovuar, gjë që e mban “i kam huazuar një agjenti tabelat e mia” larg nga “i kam huazuar llogarinë time”.

Dy mënyra për t'u lidhur

Një aplikacion që mund të hapë një shfletues — ChatGPT, Claude, Claude Code, Codex — përdor profilin e autorizimit MCP: OAuth 2.1 me PKCE (S256), regjistrim dinamik të klientit te POST /mcp/oauth/register, token-a rifreskimi dhe tregues burimi. Aplikacioni e dërgon personin te /settings/security, ai zgjedh çfarë mund të bëjë dhe cilat nga ekipet e veta arrin, dhe shfletuesi kthehet te aplikacioni me një kod. Token-i i tij i aksesit zgjat një orë dhe rifreskohet; lidhja zgjat 90 ditë.

Një agjent me rresht komandash nuk kontrollon asnjë shfletues dhe nuk mund të mbajë asnjë URL kthimi, ndaj çiftohet me grantin e autorizimit të pajisjes (RFC 8628) në vend të tij.

1. Agjenti thërret POST /mcp/auth/device me një clientName dhe scopes-et që dëshiron. Merr përsëri një device_code, një user_code të shkurtër, një verification_uri dhe një verification_uri_complete me kodin tashmë në pyetje, plus interval-in e sondazhit dhe një expires_in. Shtyp URI-në.
2. Një person e hap atë URI ndërsa ka hyrë në llogari, te /settings/security. Ai sheh cili agjent po kërkon, në emër të cilës llogarie do të punonte, deri kur, dhe saktësisht çfarë do të mund të bënte — dhe zgjedh Allow ose Don’t allow.
3. Agjenti sondon POST /mcp/auth/token me deviceCode, duke respektuar authorization_pending, slow_down, expired_token dhe access_denied. Në sukses merr { access_token, token_type, scope, expires_at }.

Në çdo rast ekziston një hap njerëzor, sepse kredenciali trashëgon të drejtat e një personi, kështu që një person duhet të zgjedhë ta huazojë. Asgjë këtu nuk krijon akses nga asgjëja. Lidhja mund të çaktivizohet edhe për një organizatë të tërë te /admin/security?tab=programs, dhe ajo përgjigje kontrollohet kur dikush lejon një lidhje, jo kur një agjent nis një.

Zbulimi

Një POST /mcp pa autentikim përgjigjet me 401 dhe një header WWW-Authenticate që tregon te /.well-known/oauth-protected-resource (RFC 9728), që emëron këtë origjinë si serverin e autorizimit; metadata e tij te /.well-known/oauth-authorization-server (RFC 8414) emëron endpoint-et e regjistrimit, autorizimit, token-it dhe shfuqizimit. Ky zinxhir është gjithçka që i duhet një klienti pasi ka adresën. Për të gjetur adresën nga një domain, një agjent lexon /.well-known/ai-catalog.json, që emëron kartën e serverit te /mcp/server-card (MCP Server Cards, SEP-2127). Endpoint-et e grantit të pajisjes janë të listuara në dokumentin e burimit të mbrojtur, nën x-nessie-device-authorization.

Një vendosje mund t'i përgjigjet edhe një adrese të dytë, më të shkurtër: https://nessie.works/mcp i Nessie Cloud proxy-het te API-ja, dhe një klient që erdhi kështu i kthehet ajo adresë si burim, ndërsa hyrja mbetet te API-ja. Një ridrejtim nuk do të mjaftonte, sepse një klient refuzon metadata që emërojnë çdo adresë tjetër përveç asaj që i është dhënë. Operatori i liston këto origjina te NESSIE_MCP_ALIAS_ORIGINS.

Fushëveprimet dhe mjetet

Fushëveprimet janë me qëllim të gjera — një fushëveprim që askush nuk mund ta shpjegojë është një fushëveprim që askush nuk e vendos saktë. Një lidhje që arrin më shumë se një ekip i liston ato me nessie_team_list, dhe çdo mjet tjetër pastaj emëron teamId-in e vet.

Një thirrje pa fushëveprimin që i nevojitet kthehet si rezultat mjetesh që emëron fushëveprimin për t'u kërkuar, jo si gabim transporti, kështu që modeli mund të raportojë diçka të dobishme në vend që të riprovojë drejt një muri.

Nuk ka një familje mjetesh të veçantë për gjurmuesit e jashtëm. Një tabelë është tabelë qoftë se detyrat e saj lindin në Nessie ose pasqyrohen nga Linear, Jira, GitHub ose Trello, kështu që një grup mjetesh mbulon të dyja, dhe çdo detyrë thotë cilës i përket. Ajo që ndryshon është shkrimi: një tabelë e pasqyruar nga një burim vetëm për lexim refuzon një shkrim me fjalë, duke i thënë agjentit se sistemi tjetër e zotëron detyrën dhe se riprovimi nuk do të ndihmojë.

Botimi i një dokumenti është një miratim, kurrë një fushëveprim

Agjentët hartojnë; një person boton. Ky rregull zbatohet për agjentët e vetë Nessie duke refuzuar drejtpërdrejt një aktor agjent — por një kredencial i çiftuar zgjidhet si person, kështu që ai refuzim nuk mund ta kapë. Porta duhet të jetë gjetkë.

Kështu që nessie_doc_publish nuk boton. Hap një miratim knowledge.page.publish — të njëjtin që hap edhe një agjent i Nessie — dhe kthen { status: "awaiting_approval", approvalId }. Sondazhimi kthen të njëjtën kërkesë në vend që të hapë një të dytë. Vendimi merret ashtu siç merren të gjitha vendimet e botimit në Nessie: nga një person, për atë dokument, në momentin kur ekziston.

Qëllimisht nuk ekziston asnjë fushëveprim botimi. Pati një — një kuti e shënuar në kohën e çiftimit që thoshte se ky agjent mund të botojë — dhe u hoq. Vendoste një herë dhe për nëntëdhjetë ditë një pyetje që produkti e bën për çdo dokument gjetkë, dhe e vendoste atë para se dokumenti të ekzistonte, kështu që personi që e shënonte nuk mund të dinte çfarë po pranonte të botohej. nessie_doc_publish kërkon documents_write, sepse kërkimi nuk është pa kosto — lexon faqen dhe vë një vendim përpara dikujt — por ai fushëveprim nuk jep asgjë për botimin.

Dy identitete regjistrohen në kërkesë, dhe dallimi është me peshë. Kërkuesi është kredenciali, kurrë njeriu në emër të të cilit vepron. Miratuesi i kërkuar është ai njeri, dhe vetëm ai mund të përgjigjet. Nëse kërkesa do ta emëronte personin si kërkues, rregulli që ndalon dikë të miratojë kërkesën e vet do ta përjashtonte pikërisht personin që ka të drejtë të vendosë.

Shikimi dhe shfuqizimi i asaj që është çiftuar

Agjentët e çiftuar të një personi listohen te /settings/security, me një etiketë dhe një kontroll shfuqizimi për secilin. Një pronar ose admin i organizatës sheh çdo kredencial në organizatë te /admin/security?tab=programs — si quhet secili, çfarë mund të bëjë, nëse është aktiv, dhe në llogarinë e kujt hua — dhe mund t'i shfuqizojë ato. Lista personale mbetet vetëm për vete: një listë kredencialesh aktive është një listë pikash mbështetjeje, jo një lexim i përgjithshëm.

Shkrimet e bëra përmes një kredenciali i atribuohen njeriut që e huazon dhe mbajnë id-në e kredencialit në metadatat e auditimit, kështu që regjistri mund ta dallojë ndryshimin e vet të një personi nga një që agjenti i tij e bëri për të.

Çfarë nuk është e disponueshme ende

Të qartë, sepse hendeku midis aftësive të një protokolli dhe të një serveri të caktuar është vendi ku dokumentimi zakonisht gënjen:

• Biseda, kanalet, ekzekutimet dhe menaxhimi i agjentëve nuk ekspozohen përmes MCP.
• Një program përgatit një buletin dhe një person e dërgon: asgjë nuk dërgon, nuk planifikon dhe nuk fshin një fushatë, dhe vetë emaili shkruhet në dizajnues.
• Lidhja dhe bashkimi i kontakteve, ndryshimet e skemës CRM, importet dhe konfigurimi i kanaleve mbeten te një person në shfletues.
• Ndërrimi i lidhjes është një cilësim i nivelit të organizatës. Mbivendosjet e nivelit të ekipit dhe ato personale nuk janë diçka që një ekip ose një person mund ta vendosë sot.