Kaiross come server MCP: gli agenti in Claude, Cursor e altri client
Gli agenti pubblicati diventano strumenti MCP: da Claude, Cursor o un altro client puoi fare domande alla knowledge dell’azienda, con le stesse fonti e gli stessi permessi.
Ultimo aggiornamento:
1. Pubblica l’agente
Nella scheda Generale dell’agente attiva Agente pubblicato (accesso esterno) e premi Salva modifiche. Solo gli agenti pubblicati sono visibili dal server MCP, dall’API e dal widget; nell’app l’agente resta come prima. Il server MCP mostra, tra questi, solo gli agenti che chi ha creato la chiave può usare; senza agenti compare solo lo strumento kaiross_info.
2. Crea una chiave API
- Apri Impostazioni → Chiavi API e premi Crea chiave.
- Copia subito la chiave (inizia con
kai_): non sarà più visibile. Kaiross ne conserva solo l’impronta (hash). - Se la chiave finisce nel posto sbagliato, usa Rigenera o disattivala.
La chiave agisce a nome di chi l’ha creata: le risposte rispettano i suoi permessi sui documenti. Crea chiavi separate per persone e strumenti diversi.
3. Indirizzo e strumenti
Endpoint: https://app.kaiross.ch/api/mcp (Streamable HTTP, senza stato), con l’header Authorization: Bearer kai_…. Limiti per chiave: 120 richieste al minuto; le chiamate a ask_… e search_… contano anche nel limite di 30 al minuto della chat dell’API. Oltre il limite lo strumento risponde «Troppe richieste, riprova tra N s». Se la tua azienda usa un’installazione dedicata di Kaiross, sostituisci il dominio con il suo.
| Strumento | Parametri | Risultato |
|---|---|---|
ask_<agente> | question (obbligatorio, fino a 8000 caratteri), conversationId (per continuare una conversazione) | Risposta dell’agente con l’elenco delle fonti. |
search_<agente> | query (fino a 2000 caratteri), limit (1–20, predefinito 8) | Estratti dei documenti con titolo e pagina. |
Il nome deriva dal nome dell’agente, in minuscolo, senza accenti, con _ al posto di spazi e simboli (max 40 caratteri): «Assistente fiduciario» diventa ask_assistente_fiduciario. Due agenti con lo stesso nome ricevono _2, _3.
Claude Desktop
Claude Desktop avvia i server MCP locali dal file di configurazione. Per un server remoto con chiave si usa il pacchetto open source mcp-remote (serve Node.js sul computer).
- In Claude Desktop apri Settings → Developer → Edit Config.
- Aggiungi il blocco qui sotto a
claude_desktop_config.json, con la tua chiave al posto dikai_…. - Riavvia Claude Desktop: gli strumenti
ask_…esearch_…compaiono tra quelli disponibili.
{
"mcpServers": {
"kaiross": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://app.kaiross.ch/api/mcp",
"--header",
"Authorization:${KAIROSS_AUTH}"
],
"env": {
"KAIROSS_AUTH": "Bearer kai_…"
}
}
}
} Claude Code
claude mcp add --transport http kaiross https://app.kaiross.ch/api/mcp \
--header "Authorization: Bearer kai_…" Cursor
Aggiungi il server in ~/.cursor/mcp.json (per tutti i progetti) o in .cursor/mcp.json nella cartella del progetto:
{
"mcpServers": {
"kaiross": {
"url": "https://app.kaiross.ch/api/mcp",
"headers": {
"Authorization": "Bearer kai_…"
}
}
}
} Visual Studio Code
{
"servers": {
"kaiross": {
"type": "http",
"url": "https://app.kaiross.ch/api/mcp",
"headers": {
"Authorization": "Bearer kai_…"
}
}
}
} Altri client MCP
Molti client accettano il formato qui sotto (lo stesso di Copia configurazione nella pagina API e MCP dell’app).
{
"mcpServers": {
"kaiross": {
"type": "http",
"url": "https://app.kaiross.ch/api/mcp",
"headers": {
"Authorization": "Bearer kai_…"
}
}
}
} Il client deve poter inviare l’header Authorization. Alcuni assistenti web, come i connettori personalizzati di ChatGPT, prevedono l’accesso OAuth o nessuna autenticazione: in quel caso verifica nella loro documentazione se è possibile impostare un header, altrimenti usa un client desktop o l’API.