MCP
Sama API-avain, tarjottuna tekoälyagentille yhtenä tyypitettynä työkaluna jokaista sallittua metodia kohti.
Xudalla on Model Context Protocol -palvelin osoitteessa /mcp, /cpi:n vieressä. Yhdistä MCP:tä tukeva agentti
siihen kirjautumalla tai API-avaimella, ja jokainen metodi, jonka kyseinen avain saa kutsua, näkyy
tyypitettynä työkaluna. Tekoälyagenteille ei tarvitse kirjoittaa erillistä integraatiota.
Yhdistäminen
Sisään pääsee kahdella tavalla, ja molemmat päätyvät samaan paikkaan: API-avaimen oikeuksiin.
Kirjaudu sisään (Clauden yhteydet ja muut OAuth-asiakkaat)
Lisää https://xuda.ai/mcp mukautettuna yhteytenä Claudessa (Settings, Connectors, Add
custom connector), jätä OAuth-asiakastunnus ja salaisuus tyhjiksi ja paina Yhdistä. Claude avaa
Xudan: kirjaudu sisään, jos et jo ole, ja dashboardin ikkuna kysyy, minkä API-avaimistasi nimissä yhteys
toimii. Valitse yksi ja paina Yhdistä. Claude verkossa, työpöydällä, mobiilissa ja Coworkissa
jakavat saman yhteyden, ja mikä tahansa toinen Claude-tili lisää sen samalla tavalla. Dashboardin
Kehittäjät, MCP-välilehti näyttää liitettävän osoitteen, nämä vaiheet ja kaiken alla olevan.
Claude Code kirjautuu samalla tavalla, kun lisäät palvelimen ilman otsikkoa, ja sitten ajat /mcp ja
valitset Authenticate:
Yhteydellä ei koskaan ole omia oikeuksia. Jokainen työkalukutsu ajetaan valitsemasi avaimen nimissä, joten avaimen käyttötila, sallittujen luettelo ja peruminen ovat myös yhteyden: peru avain kohdassa Kehittäjät, API-avaimet, ja yhteys lakkaa, ja seuraava kirjautuminen pyytää toista avainta. Sivu listaa vain omat aktiiviset avaimesi. Jos niitä ei ole, luo ensin yksi.
Asiakasohjelmien kehittäjille: palvelin noudattaa MCP:n valtuutusspesifikaatiota:
Kutsu osoitteeseen /mcp ilman käyttökelpoista tunnusta vastaa 401 ja WWW-Authenticate: Bearer resource_metadata="...", mistä asiakas löytää loput. Käyttöoikeustunnukset kestävät tunnin, päivitystunnukset
90 päivää, ja ne korvataan jokaisella käytöllä. Loopback-uudelleenohjaus-URI (http://localhost tai
http://127.0.0.1) täsmää millä tahansa portilla.
API-avain otsikossa
Avain menee Authorization: Bearer -otsikkoon, sama avain, jota käyttäisit api_key-parametrina
osoitteessa /cpi. Erillistä MCP-tunnistetta ei ole. Pyyntö ilman Authorization-otsikkoa tai avaimella, joka
ei ratkea aktiiviseksi xuda_api_keys-dokumentiksi, evätään vastauksella 401, ennen kuin yhtään työkalua
rekisteröidään.
Istunnot
Kuljetus on suoratoistettava HTTP: ensimmäinen pyyntö on MCP:n initialize-kutsu, joka avaa
istunnon ja palauttaa mcp-session-id-otsikon. Jokainen yhteyden seuraava pyyntö sisältää
saman otsikon ja saman tunnisteen. Istunto sulkeutuu 10 minuutin jälkeen ilman pyyntöä. Pyyntö
suljetulla istunnolla vastaa 404, ja MCP-asiakas aloittaa tällöin itse uuden istunnon.
Mistä tulee työkalu
Työkalut rekisteröidään istunnon alussa samasta käyttötilasta, joka avaimella jo on:
- Täysi käyttöoikeus: jokainen luettelon metodi, joka ei ole
private, rekisteröidään työkaluksi, ratkaistuna yhdistettäessä, joten avaimen luomisen jälkeen lisätty metodi on käytettävissä ilman muutoksia itse avaimeen. - Mukautettu käyttöoikeus: vain avaimen sallittujen luettelon metodit rekisteröidään.
Käynnissä oleva istunto pysyy avaimensa mukana: se tarkistaa avaimen minuutin välein ja sen takana olevat moduulit ja
liitännäiset viiden minuutin välein, ja kun työkalujoukko on muuttunut, se lähettää
notifications/tools/list_changed. Asiakas, joka kuuntelee (Claude kuuntelee), lukee uuden luettelon
yhdistämättä uudelleen, joten avaimelle sallimasi metodi tavoittaa jo yhdistetyn agentin.
Jokainen työkalu säilyttää metodin oman muodon: työkalun nimi on metodin nimi (get_account_projects,
dbs_read, ...), sen otsikko on metodin nimi Title Case -muodossa, sen kuvaus on metodin oma
description ja sen syöteskeema rakennetaan kenttä kerrallaan metodin fields-kentistä: pakolliset
kentät pysyvät pakollisina, kaikki muu on valinnaista. Kenttä, jolla ei ole tunnistettua tyyppiä, muuttuu silti
sallivaksi työkaluargumentiksi sen sijaan, että rikkoisi koko istunnon, joten yksi oudosti määritelty metodi
ei koskaan vie muuta luetteloa mukanaan.
Full Stack VPS:ään rajattu avain tarjoaa myös koneen asennetut liitännäistyökalut yllä olevien ekosysteemimetodien rinnalla, joten agentti tavoittaa sekä alustan että sen, mitä kehittäjä on koneelle rakentanut, yhdessä istunnossa. Katso Full Stack VPS.
Työkalun kutsuminen
Agentti kutsuu työkalua samoilla argumenteilla, jotka metodin kentät kuvaavat. Xuda vastaa
kutsumalla metodia sisäisesti, samalla tavalla kuin /cpi/<method> kutsuisi, ja palauttaa työkalulle metodin
{code, data}-rakenteen tekstinä. Epäonnistunut kutsu palautuu silti normaalisti MCP-kerroksessa: koodi
-1 ja sitä pienemmät näkyvät työkalun tuloksessa täsmälleen kuten tavallisessa REST-kutsussa, joten agentti lukee
sen samalla tavalla kuin oma virheenkäsittelysi. Katso Virheet.
Pyyntö, joka epäonnistuu ennen kuin yhtään työkalua ajetaan, eli puuttuva tai evätty tunniste (401), suljettu
istunto (404, koodi -32001) tai virheellinen MCP-viesti, palautuu JSON-RPC-virheenä
työkalun tuloksen sijaan: