MCP ja yhdistetyt työkalut

Yhdistä Nessie MCP-palvelimiin ja liitä ulkopuolinen agentti, jotta se voi työskennellä Nessiessä puolestasi.

Mikä MCP on

Model Context Protocol on pieni, avoin tapa kuvata työkaluja kielimallille ja kutsua niitä. Palvelin ilmoittaa, mitä se osaa: nimettyjen työkalujen luettelon, jossa jokaisella on JSON-skeema argumenteilleen. Asiakas löytää luettelon ja kutsuu työkaluja mallin puolesta. Protokolla on tarkoituksella tylsä: sen arvo on siinä, että kerran kirjoitettu integraatio toimii jokaisen mallin ja jokaisen tuotteen kanssa, joka puhuu protokollaa.

Nessie on molemmilla puolilla

Tämä kannattaa tarkentaa, koska kaksi puolta sekoitetaan helposti, ja ne kulkevat tarkoituksella eri polkuja pitkin.

• Ulospäin. Nessie on MCP-asiakas. Yhdistät palvelimia, joita joku muu ylläpitää, ja niiden tarjoamat työkalut tulevat agenttiesi käyttöön. Hallintapinta on /api/mcp/*.
• Sisäänpäin. Nessie on myös MCP-palvelin. Muualla ajettava agentti, kuten Claude Code tai Codex kehittäjän koneella, voi kutsua taulujasi ja dokumenttejasi. Päätepiste on POST /mcp, /api-polun ulkopuolella tarkoituksella, jotta kaksi vastakkaista merkitystä eivät ole yhden polkusegmentin päässä toisistaan.

MCP-palvelimen yhdistäminen Nessieen

Luettelomerkinnät ja instanssit

Objekteja on kaksi, ja ero on tärkeä:

• Luettelomerkintä on palvelimen määritelmä: sen nimi, yhteystapa ja tapa, jolla se tunnistautuu. Se kirjoitetaan kerran, ja sen voi jakaa.
• Instanssi on tuo luettelomerkintä asennettuna yhdelle laajuudelle sen tunnistetietojen kanssa, joilla palvelimeen päästään. Saman merkinnän asentaminen kahdelle eri tiimille tuottaa kaksi instanssia.

Useimmat eivät kosketa kumpaakaan suoraan. Adminin sisäänkäynti on sovelluskauppa osoitteessa /admin/apps: se selaa samaa luetteloa piilotetuin yhteystiedoin, ja listauksen Connect-painike luo instanssin. Ylläpitäjät, jotka haluavat raakaobjektit, käyttävät päätepisteitä /api/mcp/catalog ja /api/mcp/instances.

Jos palvelinta ei ole vielä luettelossa, POST /api/mcp/discover ottaa URL-osoitteen ja palauttaa sen, mitä palvelin kertoo itsestään. POST /api/mcp/library/import hakee merkinnän julkisesta palvelinkirjastosta. Ensimmäisen käynnistyksen yhteyden voi luoda suoraan URL-osoitteesta päätepisteellä POST /api/apps/custom.

Yhteystavat

Nessie yhdistää etäpalvelimiin HTTP:n yli. Kaksi yhteystapaa toimii: striimattava HTTP (nykyinen MCP-yhteystapa) ja vanhempi HTTP+SSE. Valitse http, ellei palvelin tarjoa vain sse-tapaa.

stdio-yhteystapa hylätään itse kirjoittamillesi liittimille. stdio tarkoittaa, että MCP-palvelin on paikallinen prosessi, jonka isäntä käynnistää, eikä operaattori voi järkevästi tarkistaa mielivaltaisten ohjelmien ajamista Nessie-palvelimen sisällä. Palvelimet, jotka on julkaistu vain paikallisesti ajettavana pakettina, pudotetaan kirjastotuonneista samasta syystä. Protokollan kentässä on arvo ws, mutta sitä ei ole toteutettu: sitä käyttävä yhteys epäonnistuu, kun Nessie yrittää avata sen.

Miten Nessie tunnistautuu palvelimelle

Luettelomerkintä ilmoittaa yhden viidestä tavasta: none, api_key, bearer, basic tai oauth2.

api_key on otsikon lisäystä, ja merkintä kertoo, mikä otsikko ja mikä etuliite on kyseessä. Näin Authorization: Bearer …, X-API-Key: … ja X-Auth-Token: Token … ovat kaikki sama tapa eri asetuksilla. Avaimen liität kerran päätepisteeseen POST /api/mcp/instances/:instanceId/secret, eikä sitä voi lukea enää koskaan. Instanssireittien vastaukset eivät sisällä tunnistetiedon viitettä.

oauth2 tulee kahdessa muodossa. Palvelimella, jolla on kiinteät päätepisteet, ne ovat sen luettelomerkinnässä. Palvelin, joka julkaisee vakiometatiedot, ei vaadi mitään määritystä: Nessie lukee suojatun resurssin ja valtuutuspalvelimen asiakirjat ja luo itselleen asiakkaan joko dynaamisella asiakasrekisteröinnillä tai asiakas-ID-metatietoasiakirjan kautta, jonka se julkaisee omalla well-known-polullaan. Molemmissa tapauksissa kättely kulkee päätepisteen POST /api/mcp/instances/:instanceId/oauth/start kautta, ja palveluntarjoaja ohjaa selaimen takaisin päätepisteeseen GET /api/mcp/oauth/callback. Tilatunnus on kertakäyttöinen, sitä säilytetään tietokannassa, ja se on voimassa kymmenen minuuttia. PKCE:tä käytetään aina.

Yksi sääntö yllättää ihmisiä: edes organisaation omistaja ei voi liittää henkilökohtaista tai OAuth-tokenia toisen henkilön tiliin. Jaettu tunnistetieto on mahdollinen vain API-avainmerkinnälle, joka on validoitu sellaiseksi, ja kaikki muu hylätään. Henkilölle kuuluva tunnistetieto pysyy henkilölle kuuluvana.

Missä tunnistetiedot ovat

Liitinsalaisuudet ja OAuth-tokenipaketit tallennetaan omaan Postgres-tietokantaasi AES-256-GCM-kääreisiin. Kääreet on salattu käyttöönoton erikseen versioidulla salausavainrenkaalla, ja niihin viitataan vain läpinäkymättömillä secret_*-viitteillä. Ne eivät ole tarkoituksella samassa ulkoisessa salaisuusvarastossa, joka pitää muut Nessien salaisuudet. Tuotantokäyttöönotto, jossa salattua varastoa ei ole määritetty, ei käynnisty sen sijaan, että suorittaisi OAuth-kättelyn, jonka se sitten jättäisi kesken.

Mihin yhteys ulottuu

Instanssi asennetaan yhteen kuudesta laajuudesta: system, organization, project, team, channel tai user. Laajuus on kova yläraja sille, mitkä ajot voivat käyttää instanssia, ja myöntöt voivat vain kaventaa sitä, eivät laajentaa. Oman tilisi kanssa asennettu liitin ei siis voi hiljaa muuttua organisaatiolaajuiseksi.

Kuka saa asentaa mihin, noudattaa samaa muotoa: organisaation omistajat ja ylläpitäjät hallitsevat asennuksia kaikilla laajuuksilla, ja kaikki muut asentavat liittimet omaan user-laajuuteensa ja näkevät jaetut asennukset, joihin heillä on oikeus.

Työkalun antaminen agentille

Palvelimen yhdistäminen ei anna sen työkaluja kenellekään. Kun instanssi asennetaan, Nessie tutkii sen ja projisoi jokaisen ilmoittamansa työkalun työkalurekisteriin. Admin näyttää rekisterin osoitteessa /admin/advanced/tools: sisäänrakennetut työkalut, MCP-työkalut, pakettityökalut ja suoritintyökalut yhdessä luettelossa, jokaisen lähteen ja tilan kanssa.

Projisoidulla työkalulla on yksi kolmesta tilasta: active, pending_review tai disabled. Jaetun laajuuden asennuksen työkalut saavat tilan pending_review, ja ne on hyväksyttävä tuolla sivulla, ennen kuin agentti näkee ne. Oman user-laajuuden asennuksen työkalut ovat heti aktiivisia, koska ainoa henkilö, johon ne ulottuvat, olet sinä. Tarkistus on jatkuva rutiini, ei kertaluonteinen toimenpide: jos myöhempi tutkimus huomaa työkalun kuvauksen tai skeeman muuttuneen, työkalu palaa tilaan pending_review, eikä sitä tarjota ennen kuin joku katsoo muutoksen.

Sen, mitkä agentit voivat sitten kutsua aktiivista työkalua, ratkaisee yksi kahdesta tavasta:

• Sovelluskaupan kautta luotu yhteys vaatii erillisen myöntön. Agentti saa työkalun vain, jos myöntö nimeää sen, ja myöntö tarkistetaan työkalun nykyistä sormenjälkeä vasten. Muuttunut työkalu vaatii siis uuden päätöksen.
• Muuten työkalu on oletuksena päällä niille agenteille, jotka ulottuvat sen laajuuteen, ja yksittäiset agentit kytketään pois päältä työkalun tietopaneelista.

Myöntö nimeää täsmälleen yhden kohteen — roolin tai agentin, ei kumpaakin — ja kielto voittaa sallinnan. user-laajuuden yhteydessä kysymystä ei synny: mikä tahansa agentti, jonka kanssa tuo henkilö puhuu, voi käyttää yhteyttä, ja ainoa asia, joka sen estää, on nimenomainen kytkeminen pois päältä.

Yhtä asiaa etsitään helposti väärästä paikasta: adminin /settings/accounts on yhdistetyt tilit — Slack, postilaatikot, mallitilaukset sekä OAuth-linkit Linearille, Jiralle, GitHubille ja Trellolle, jotka tukevat ulkoisia tauluja. MCP-liittimet ovat osoitteessa /admin/apps, ja niiden tuottamat työkalut osoitteessa /admin/advanced/tools.

Hyväksyntäportit työkalukutsuissa

Osa työkalukutsuista pysähtyy odottamaan ihmistä. Kun niin käy, ajo ei epäonnistu: kutsu jäädytetään — työkalun nimi, tiiviste sen argumenteista ja tarpeeksi tilaa jatkamiseen — ja hyväksyntäpyyntö ilmestyy osoitteeseen /api/approvals, jossa joku vastaa siihen. Jatkaminen on idempotenttia, joten kaksoishyväksyntä ei voi suorittaa kutsua kahdesti. Päättäjä näkee rajatun yhteenvedon siitä, mitä kysytään. Tarkat argumentit ja alkuperäinen ajo pysyvät palvelimella.

Portteja on kahdenlaisia, ja ne määritellään eri tavoin.

• Rakenteelliset portit ovat tiettyjen sisäänrakennettujen työkalujen ominaisuus, eikä niitä voi määrittää. Agentin omasta tai yhdistetystä postilaatikosta lähetetty posti, Gmail-luonnoksen lähetys, postitilin irrottaminen, kalenteritapahtuman luominen, muuttaminen tai peruminen sekä selaintoiminto, joka kirjoittaisi sivustolle, johon selain ei ole kirjautunut, ovat kaikki tällä tavalla portitettuja. Niille annetaan 24 tunnin vastausaika tavallisen 30 minuutin sijaan.
• Käytäntöportit tulevat tool/invoke-parin käytäntösäännöistä. Sääntö, joka sallii kutsun, voi sisältää merkinnän requiresApproval, ja ilman varmennettua hyväksyntää arviointi palauttaa APPROVAL_REQUIRED eikä aja kutsua. Säännöt arvioidaan ensin kiellot, ja ne järjestetään laajuuden mukaan.

Emme ole pystyneet varmistamaan, mikä adminin näkymä kirjoittaa työkalulle requiresApproval-käytäntösäännön. Tietomalli ja valvonta ovat molemmat paikallaan.

Ulkopuolisen agentin yhdistäminen Nessieen

Toiseen suuntaan. Nessie ajaa omaa MCP-palvelintaan osoitteessa POST /mcp striimattavan HTTP:n yli. Se on tilaton: jokainen kutsu kantaa oman tunnistetietonsa ja ratkaisee oman toimijansa, joten istuntoa ei tarvitse kiinnittää yhteen replikaan. ChatGPT, Claude, Claude Code, Codex tai agentti jonkun kannettavalla voi työskennellä taulujesi, dokumenttiesi ja asiakkaidesi kanssa siitä työkalusta käsin, jota tuo henkilö jo käyttää. Vaiheittaiset ohjeet kullekin sovellukselle ovat kohdassa Yhdistä ChatGPT, Claude ja muut tekoälysovellukset.

Mikä paritettu tunnistetieto oikeastaan on

Tämä on se osa, joka pitää ymmärtää oikein, koska ilmeinen mielikuva — API-avain, johon on liitetty oikeuksia — on väärä.

Paritettu tunnistetieto ei ole koskaan identiteetti. Se nimeää ihmisen, ja jokainen työkalukutsu ajetaan tuon ihmisen nimissä samoja palvelufunktioita vasten, joita HTTP-reitit kutsuvat. Agentti ei siis voi päästä mihinkään, mihin henkilö, joka sen lainasi, ei pääsisi klikkaamalla. Laajuudet voivat vain kaventaa tätä ulottuvuutta; mikään laajuus ei laajenna sitä.

Elinkelpoisuus luetaan jokaisesta kutsusta uudelleen eikä sitä luoteta tokeniin: peruutus, vanheneminen, käyttäjän tokenversio, organisaatiojäsenyys ja nykyinen rooli. Alennus, käytöstä poisto tai ”kirjaudu ulos kaikkialta” osuu agentin seuraavaan kutsuun, eikä vasta tunnistetiedon vanhenemisessa.

Token on läpinäkymätön ja etuliitteeltään nag1_. Sitä säilytetään vain SHA-256-tiivisteenä, ja se on voimassa 90 päivää. Muussa reitissä kuin MCP-päätepisteessä sitä hylätään erityisellä 403-vastauksella. Sen esittäminen muualla ei ole osittainen onnistuminen, jota kannattaisi yrittää uudelleen. Juuri tämä estää sen, että ”lainasin agentille taulujani” tarkoittaisi ”lainasin sille tilini”.

Kaksi tapaa yhdistää

Sovellus, joka voi avata selaimen — ChatGPT, Claude, Claude Code, Codex — käyttää MCP-valtuutusprofiilia: OAuth 2.1 PKCE:llä (S256), dynaaminen asiakasrekisteröinti osoitteessa POST /mcp/oauth/register, päivitystokenit ja resurssi-indikaattorit. Sovellus lähettää henkilön osoitteeseen /settings/security. Hän valitsee, mitä sovellus saa tehdä ja mihin hänen tiimeihinsä se ulottuu, ja selain palaa sovellukseen koodin kanssa. Käyttötoken on voimassa tunnin ja sitä uusitaan. Yhteys on voimassa 90 päivää.

Komentoriviagentti ei hallitse selainta eikä voi isännöidä takaisinkutsu-URL-osoitetta, joten se parittuu laitevaltuutuksen (RFC 8628) kautta.

1. Agentti kutsuu päätepistettä POST /mcp/auth/device arvoilla clientName ja scopes, joita se haluaa. Se saa takaisin device_code-arvon, lyhyen user_code-koodin, osoitteet verification_uri ja verification_uri_complete — jälkimmäisessä koodi on jo kyselyssä — sekä kyselyvälin interval-arvon ja ajan expires_in. Agentti tulostaa osoitteen.
2. Henkilö avaa osoitteen kirjautuneena osoitteessa /settings/security. Hän näkee, mikä agentti kysyy, kenen tilillä se toimisi, mihin asti ja tasan mitä se voisi tehdä — ja valitsee Salli tai Älä salli.
3. Agentti kysyy päätepisteestä POST /mcp/auth/token arvolla deviceCode ja kunnioittaa virheitä authorization_pending, slow_down, expired_token ja access_denied. Onnistuessaan se saa { access_token, token_type, scope, expires_at }.

Molemmilla tavoilla on ihmisen vaihe, koska tunnistetieto perii henkilön oikeudet, joten henkilön on valittava lainata ne. Mitään ei synny tyhjästä. Yhdistäminen voidaan kytkeä pois päältä koko organisaatiolta osoitteessa /admin/security?tab=programs, ja tuo vastaus tarkistetaan, kun joku sallii yhteyden, ei kun agentti aloittaa sen.

Löytäminen

Tunnistautumaton POST /mcp vastaa 401-virheellä ja WWW-Authenticate-otsikolla, joka osoittaa osoitteeseen /.well-known/oauth-protected-resource (RFC 9728). Se nimeää tämän originin valtuutuspalvelimeksi. Sen metatiedot osoitteessa /.well-known/oauth-authorization-server (RFC 8414) nimeävät rekisteröinnin, valtuutuksen, tokenin ja peruutuksen päätepisteet. Tämä ketju on kaikki, mitä asiakas tarvitsee, kun sillä on osoite. Osoitteen löytämiseksi verkkotunnuksesta agentti lukee tiedoston /.well-known/ai-catalog.json, joka nimeää Server Cardin osoitteessa /mcp/server-card (MCP Server Cards, SEP-2127). Laitevaltuutuksen päätepisteet on listattu suojatun resurssin asiakirjassa kentän x-nessie-device-authorization alla.

Käyttöönotto voi vastata myös toisessa, lyhyemmässä osoitteessa. Nessie Cloudin https://nessie.works/mcp välitetään APIlle, ja asiakas, joka tuli sitä kautta, saa takaisin tuon osoitteen resurssina, kun taas kirjautuminen pysyy APIssa. Uudelleenohjaus ei riittäisi, koska asiakas hylkää metatiedot, jotka nimeävät muun osoitteen kuin sen, jonka se sai. Operaattori listaa nämä originit kohdassa NESSIE_MCP_ALIAS_ORIGINS.

Laajuudet ja työkalut

Laajuudet ovat tarkoituksella karkeita. Laajuus, jota kukaan ei osaa selittää, on laajuus, jonka kukaan ei aseta oikein. Yhteys, joka ulottuu useampaan tiimiin, listaa tiimit komennolla nessie_team_list, ja jokainen muu työkalu nimeää sitten teamId-arvon.

Kutsu ilman tarvitsemaansa laajuutta palautuu työkalun tuloksena, joka nimeää pyydettävän laajuuden, eikä siirtovirheenä. Näin malli voi kertoa jotain hyödyllistä eikä yritä uudelleen seinää vasten.

Ulkoisille seurantatyökaluille ei ole erillistä työkalujoukkoa. Taulu on taulu riippumatta siitä, ovatko sen tehtävät peräisin Nessiestä vai peilattu Linearista, Jirasta, GitHubista tai Trellosta. Yksi työkalujoukko kattaa siis molemmat, ja jokainen tehtävä kertoo lähteensä. Kirjoittamisessa on ero: vain luettavasta lähteestä peilattu taulu hylkää kirjoituksen sanallisesti ja kertoo agentille, että toinen järjestelmä omistaa tiketin eikä uudelleen yrittäminen auta.

Dokumentin julkaiseminen on hyväksyntä, ei laajuus

Agentit luonnostelevat, henkilö julkaisee. Nessien omille agenteille tämä sääntö on pakotettu hylkäämällä agenttitoimijan pyynnöt suoraan. Paritettu tunnistetieto ratkaistaan kuitenkin henkilöksi, joten hylkäys ei voi siihen kohdistua. Portin on oltava jossain muualla.

Siksi nessie_doc_publish ei julkaise. Se avaa hyväksynnän knowledge.page.publish — saman, jonka Nessien oma agentti avaa — ja palauttaa { status: "awaiting_approval", approvalId }. Kysely palauttaa saman pyynnön eikä avaa toista. Päätöksen tekee henkilö samalla tavalla kuin kaikki muut Nessien julkaisupäätökset: tuosta dokumentista sillä hetkellä, kun se on olemassa.

Julkaisemiselle ei ole tarkoituksella laajuutta. Sellainen oli: parituksen aikana oli valintaruutu, jolla agentin sai julkaista. Se poistettiin. Valintaruutu päätti kerran ja yhdeksänkymmeneksi päiväksi kysymyksen, jonka tuote muualla kysyy jokaisesta dokumentista erikseen. Se päätti sen myös ennen kuin dokumenttia oli olemassa, joten valintaruudun rastittanut ei voinut tietää, mitä hän hyväksyi julkaistavaksi. nessie_doc_publish vaatii laajuuden documents_write, koska pyytäminen ei ole ilmaista: se lukee sivun ja asettaa päätöksen jonkun eteen. Tuo laajuus ei kuitenkaan anna mitään julkaisusta.

Pyyntöön tallennetaan kaksi identiteettiä, ja ero on olennainen. Pyytäjä on tunnistetieto, ei ihminen, jonka nimissä se toimii. Vaadittu hyväksyjä on tuo ihminen, ja vain hän saa vastata. Jos pyyntö nimeäisi henkilön pyytäjäksi, sääntö, joka estää ketään hyväksymästä omaa pyyntöään, sulkisi pois juuri sen henkilön, jolla on oikeus päättää.

Parituksen näkeminen ja peruminen

Henkilön omat paritetut agentit näkyvät osoitteessa /settings/security, ja jokaisella on nimi ja peruutuspainike. Omistaja tai organisaation ylläpitäjä näkee osoitteessa /admin/security?tab=programs kaikki organisaation tunnistetiedot: mikä kukin on, mitä se saa tehdä, onko se elossa ja kenen tiliä se lainaa. Hän voi perua minkä tahansa. Henkilökohtainen luettelo pysyy vain omana tietonaan, koska elävien tunnistetietojen luettelo on luettelo jalansijoista eikä yleistä luettavaa.

Tunnistetietojen kautta tehdyt muutokset kirjataan lainaavalle ihmiselle, ja tarkastustietoihin tallennetaan tunnistetiedon tunnus. Loki erottaa siksi henkilön oman muokkauksen sellaisesta, jonka hänen agenttinsa teki hänen puolestaan.

Mitä ei ole vielä saatavilla

Sanotaan suoraan, koska ero protokollan ominaisuuksien ja tietyn palvelimen ominaisuuksien välillä on paikka, jossa dokumentaatio yleensä valehtelee:

• Keskustelua, kanavia, ajoja ja agenttien hallintaa ei ole julkaistu MCP:n kautta.
• Ulkoinen ohjelma valmistelee uutiskirjeen ja henkilö lähettää sen. Mikään ei lähetä, ajasta tai poista kampanjaa, ja itse sähköposti kirjoitetaan suunnittelijassa.
• Yhteystietojen linkitys ja yhdistäminen, CRM-skeeman muutokset, tuonnit ja kanavien määritys jäävät henkilölle selaimeen.
• Yhdistämisen kytkin on organisaatiotason asetus. Tiimi- tai henkilökohtaisia ohituksia ei voi tällä hetkellä asettaa.