Siirry sisältöön
Tarkistettu

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:

claude mcp add
claude mcp add --transport http xuda https://xuda.ai/mcp

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

claude mcp add
claude mcp add --transport http xuda https://xuda.ai/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

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 -avaimilla on lisätyökaluja

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:

json
{ "jsonrpc": "2.0", "error": { "code": -32000, "message": "Bad Request: Invalid Api key" }, "id": null }

Seuraavaksi