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:
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
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 è
privateviene 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.
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: