Naar de inhoud springen
Geverifieerd

MCP

Dezelfde API-sleutel, voor een AI-agent beschikbaar gemaakt als één getypeerde tool per toegestane methode.

Xuda draait een Model Context Protocol-server op /mcp, naast /cpi. Verbind er een MCP-compatibele agent mee, door in te loggen of met een API-sleutel, en elke methode die die sleutel mag aanroepen verschijnt als een getypeerde tool. Je hoeft geen aparte integratie voor AI-agents te schrijven.

Verbinden

Er zijn twee manieren om binnen te komen, en beide eindigen op hetzelfde punt: de rechten van een API-sleutel.

Inloggen (Claude-koppelingen en andere OAuth-clients)

Voeg https://xuda.ai/mcp toe als aangepaste koppeling in Claude (Instellingen, Koppelingen, Aangepaste connector toevoegen), laat de OAuth-client-ID en het geheim leeg en druk op Verbinden. Claude opent Xuda: log in als je dat nog niet bent, en een venster in het dashboard vraagt namens welke van je API-sleutels de verbinding handelt. Kies er een en druk op Verbinden. Claude op het web, Desktop, mobiel en Cowork delen die verbinding, en elk ander Claude-account voegt hem op dezelfde manier toe. Het tabblad Ontwikkelaars, MCP van het dashboard toont het adres om te plakken, deze stappen en alles hieronder.

Claude Code logt op dezelfde manier in als je de server zonder header toevoegt, en daarna /mcp uitvoert en Authenticate kiest:

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

De verbinding heeft nooit eigen rechten. Elke toolaanroep draait als de sleutel die je hebt gekozen, dus de toegangsmodus, de toegestane lijst en het intrekken van de sleutel gelden ook voor de verbinding: trek de sleutel in onder Ontwikkelaars, API-sleutels en de verbinding stopt, en bij de volgende keer inloggen wordt om een andere sleutel gevraagd. De pagina toont alleen je eigen actieve sleutels. Heb je er geen, maak er dan eerst een.

Voor clientontwikkelaars: de server volgt de MCP-autorisatiespecificatie:

Een aanroep naar /mcp zonder bruikbaar token antwoordt met 401 en WWW-Authenticate: Bearer resource_metadata="...", waarmee een client de rest vindt. Toegangstokens gelden een uur, refreshtokens 90 dagen en worden bij elk gebruik vervangen. Een loopback-redirect-URI (http://localhost of http://127.0.0.1) komt op elke poort overeen.

Een API-sleutel in een header

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

De sleutel gaat in een header Authorization: Bearer, dezelfde sleutel die je als api_key op /cpi zou gebruiken. Er is geen aparte MCP-referentie. Een verzoek zonder header Authorization, of met een sleutel die niet naar een actief document xuda_api_keys leidt, wordt geweigerd met 401 voordat er een tool is geregistreerd.

Sessies

Het transport is streambare HTTP: het eerste verzoek is een MCP-aanroep initialize, die een sessie opent en een header mcp-session-id teruggeeft. Elk volgend verzoek op die verbinding heeft dezelfde header en dezelfde referentie. Een sessie sluit na 10 minuten zonder verzoek. Een verzoek op een gesloten sessie antwoordt met 404, waarna een MCP-client zelf een nieuwe sessie start.

Wat een tool wordt

Tools worden aan het begin van de sessie geregistreerd op basis van de toegangsmodus die de sleutel al heeft:

  • Volledige toegang: elke methode in de catalogus die niet private is, wordt als tool geregistreerd, bepaald op het moment van verbinden, dus een methode die na het aanmaken van de sleutel is toegevoegd, is beschikbaar zonder iets aan de sleutel zelf te veranderen.
  • Aangepaste toegang: alleen de methoden op de toegestane lijst van de sleutel worden geregistreerd.

Een lopende sessie blijft meelopen met zijn sleutel: hij kijkt elke minuut naar de sleutel, en elke vijf minuten naar de modules en plugins erachter, en als de set tools is veranderd, stuurt hij notifications/tools/list_changed. Een client die luistert (Claude doet dat) leest de nieuwe lijst zonder opnieuw te verbinden, dus een methode die je op de sleutel toestaat, bereikt een agent die al verbonden is.

Elke tool houdt de vorm van de methode: de toolnaam is de methodenaam (get_account_projects, dbs_read, ...), de titel is de methodenaam in Title Case, de beschrijving is de eigen description van de methode, en het invoerschema wordt veld voor veld opgebouwd uit de fields van de methode: verplichte velden blijven verplicht, al het andere is optioneel. Een veld zonder herkend type wordt nog steeds een toegeeflijk toolargument in plaats van de hele sessie te breken, zodat één vreemd gespecificeerde methode de rest van de catalogus nooit meeneemt.

Sleutels van een Full Stack VPS hebben extra tools

Een sleutel die bij een Full Stack VPS hoort, toont ook de geïnstalleerde plugintools van die machine naast de ecosysteemmethoden hierboven, zodat een agent in één sessie zowel het platform als alles wat de ontwikkelaar op de machine heeft gebouwd kan bereiken. Zie Full Stack VPS.

Een tool aanroepen

Een agent roept een tool aan met dezelfde argumenten als de velden van de methode beschrijven. Xuda antwoordt door de methode intern aan te roepen, op dezelfde manier als /cpi/<method> dat zou doen, en geeft de envelop {code, data} van de methode als tekst terug aan de tool. Een mislukte aanroep keert op MCP-niveau nog gewoon terug: code -1 en hoger staat in het toolresultaat precies zoals bij een gewone REST-aanroep, zodat een agent het leest zoals je eigen foutafhandeling dat zou doen. Zie Fouten.

Een verzoek dat mislukt voordat een tool draait, een ontbrekende of geweigerde referentie (401), een gesloten sessie (404, code -32001) of een misvormd MCP-bericht, komt terug als een JSON-RPC-fout in plaats van een toolresultaat:

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

Volgende