Vai al contenuto
Kaiross

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

  1. Apri Impostazioni → Chiavi API e premi Crea chiave.
  2. Copia subito la chiave (inizia con kai_): non sarà più visibile. Kaiross ne conserva solo l’impronta (hash).
  3. 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.

StrumentoParametriRisultato
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).

  1. In Claude Desktop apri Settings → Developer → Edit Config.
  2. Aggiungi il blocco qui sotto a claude_desktop_config.json, con la tua chiave al posto di kai_….
  3. Riavvia Claude Desktop: gli strumenti ask_… e search_… compaiono tra quelli disponibili.
claude_desktop_config.json
{
  "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

Da terminale
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:

mcp.json
{
  "mcpServers": {
    "kaiross": {
      "url": "https://app.kaiross.ch/api/mcp",
      "headers": {
        "Authorization": "Bearer kai_…"
      }
    }
  }
}

Visual Studio Code

.vscode/mcp.json
{
  "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).

Configurazione generica
{
  "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.