Vai al contenuto
Verificata

MCP

La stessa chiave API, esposta a un agente AI come uno strumento tipizzato per ogni metodo consentito.

Xuda esegue un server Model Context Protocol su /mcp, accanto a /cpi. Collega a esso un agente compatibile con MCP, accedendo o con una chiave API, e ogni metodo che quella chiave può chiamare compare come strumento tipizzato, senza bisogno di scrivere un'integrazione separata per gli agenti AI.

Collegarsi

Ci sono due modi per entrare, e entrambi finiscono nello stesso punto: i diritti di una chiave API.

Accedere (connettori Claude e altri client OAuth)

Aggiungi https://xuda.ai/mcp come connettore personalizzato in Claude (Impostazioni, Connettori, Aggiungi connettore personalizzato), lascia vuoti l'ID client e il segreto OAuth e premi Collega. Claude apre Xuda: accedi se non l'hai già fatto e una finestra nella dashboard chiede con quale delle tue chiavi API agisce la connessione; scegline una e premi Collega. Claude sul web, Desktop, mobile e Cowork condividono quella connessione, e qualsiasi altro account Claude la aggiunge allo stesso modo. La scheda Sviluppatori, MCP della dashboard mostra l'indirizzo da incollare, questi passaggi e tutto ciò che segue.

Claude Code accede allo stesso modo quando aggiungi il server senza un header, poi esegui /mcp e scegli Authenticate:

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

La connessione non ha mai diritti propri. Ogni chiamata di strumento viene eseguita come la chiave che hai scelto, quindi la modalità di accesso della chiave, la sua lista consentita e la sua revoca valgono anche per la connessione: revoca la chiave in Sviluppatori, Chiavi API e la connessione si interrompe, e al successivo accesso ti verrà chiesta un'altra chiave. La pagina elenca solo le tue chiavi attive; se non ne hai, creane prima una.

Per gli sviluppatori di client, il server segue la specifica di autorizzazione MCP:

Una chiamata a /mcp senza un token utilizzabile risponde con 401 e WWW-Authenticate: Bearer resource_metadata="...", ed è così che un client trova il resto. I token di accesso durano un'ora; i token di aggiornamento durano 90 giorni e vengono sostituiti a ogni utilizzo. Un URI di reindirizzamento loopback (http://localhost o http://127.0.0.1) corrisponde su qualsiasi porta.

Una chiave API in un header

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

La chiave va in un header Authorization: Bearer, la stessa chiave che useresti come api_key su /cpi. Non esiste una credenziale MCP separata. Una richiesta senza header Authorization, o con una chiave che non corrisponde a un documento xuda_api_keys attivo, viene rifiutata con 401 prima che venga registrato qualsiasi strumento.

Sessioni

Il trasporto è HTTP in streaming: la prima richiesta è una chiamata MCP initialize, che apre una sessione e restituisce un header mcp-session-id; ogni richiesta successiva su quella connessione porta lo stesso header e la stessa credenziale. Una sessione si chiude dopo 10 minuti senza richieste. Una richiesta su una sessione chiusa risponde 404, e un client MCP avvia allora una nuova sessione da solo.

Cosa diventa uno strumento

Gli strumenti vengono registrati all'inizio della sessione in base alla stessa modalità di accesso che la chiave ha già:

  • Accesso completo: ogni metodo del catalogo che non è private viene registrato come strumento, risolto al momento della connessione, quindi un metodo aggiunto dopo la creazione della chiave è disponibile senza alcuna modifica alla chiave stessa.
  • Accesso personalizzato: vengono registrati solo i metodi della lista consentita della chiave.

Una sessione in corso resta al passo con la sua chiave: controlla la chiave ogni minuto e i moduli e i plugin che la sostengono ogni cinque, e quando l'insieme degli strumenti è cambiato invia notifications/tools/list_changed. Un client in ascolto (Claude lo fa) legge il nuovo elenco senza riconnettersi, così un metodo che consenti sulla chiave raggiunge un agente già connesso.

Ogni strumento mantiene la forma del metodo: il nome dello strumento è il nome del metodo (get_account_projects, dbs_read, ...), il suo titolo è il nome del metodo in Title Case, la sua descrizione è la description del metodo stesso e il suo schema di input è costruito campo per campo dai fields del metodo: i campi obbligatori restano obbligatori, tutto il resto è facoltativo. Un campo senza un tipo riconosciuto diventa comunque un argomento permissivo dello strumento invece di rompere l'intera sessione, così un metodo specificato in modo strano non trascina mai giù il resto del catalogo.

Le chiavi VPS full stack portano strumenti aggiuntivi

Una chiave limitata a un VPS full stack espone anche gli strumenti dei plugin installati su quella macchina, accanto ai metodi dell'ecosistema qui sopra, così un agente può raggiungere sia la piattaforma sia ciò che lo sviluppatore ha creato sulla macchina in un'unica sessione. Vedi VPS full stack.

Chiamare uno strumento

Un agente chiama uno strumento con gli stessi argomenti descritti dai campi del metodo. Xuda risponde chiamando internamente il metodo, nello stesso modo di /cpi/<method>, e restituisce allo strumento il formato {code, data} del metodo come testo. Una chiamata fallita restituisce comunque normalmente al livello MCP: il codice -1 e superiori compare nel risultato dello strumento esattamente come con una normale chiamata REST, quindi un agente lo legge come lo leggerebbe la tua gestione degli errori. Vedi Errori.

Una richiesta che fallisce prima che venga eseguito qualsiasi strumento, una credenziale mancante o rifiutata (401), una sessione chiusa (404, codice -32001), un messaggio MCP malformato, torna come errore JSON-RPC invece che come risultato di uno strumento:

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

Passi successivi