Server MCP per assistenti IA

IllusionDB è anche un server MCP (Model Context Protocol): il tuo assistente IA – Claude Code, Claude Desktop o un altro client MCP – interroga da solo i dati, li analizza e gestisce i record. Tipico: «Quali progetti sono in ritardo?», «Somma delle ore per cliente a ottobre» oppure «Imposta tutte le attività del progetto X su completate».

L’endpoint è POST /mcp della tua istanza (fuori da /api/v1, Streamable HTTP). In Impostazioni → Il mio account la scheda Server MCP mostra l’indirizzo con comandi pronti; subito dopo aver creato un token, è già inserito.

Configurazione

Claude Code (una volta, nella cartella del progetto; con --scope user in tutti i progetti):

claude mcp add --transport http illusiondb https://db.example.com/mcp --header "Authorization: Bearer <TOKEN>"

Claude Desktop (Impostazioni → Sviluppatore → Modifica configurazione; serve Node.js), poi riavvia:

{
  "mcpServers": {
    "illusiondb": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://db.example.com/mcp", "--header", "Authorization: Bearer <TOKEN>"]
    }
  }
}

Strumenti

• Lettura (qualsiasi token): list_datasources, list_tables, get_table, query_records, get_record, list_views, distinct_values. query_records comprende gli stessi filtri, ordinamenti, raggruppamenti e riepiloghi di GET /tables/{id}/records, ad es. l’albero di filtri {"and":[{"col":"status","op":"eq","val":"open"}]}. Le tabelle si possono indicare per ID o per nome (tasks, main.tasks, Demo/tasks).
• Modifica (token senza Sola lettura): create_record, update_record, add_link, remove_link.

Permessi

• Il token agisce con i diritti del suo account: ruolo e permessi sulle tabelle valgono per ogni strumento – le tabelle senza permesso di lettura non compaiono, scrivere richiede il permesso di scrittura. Meglio creare per l’assistente un account dedicato con esattamente i permessi necessari.
• Un token di Sola lettura riceve solo gli strumenti di lettura.
• Volutamente non via MCP: eliminare record, modificare colonne, tabelle o viste, SQL, importazioni, fonti dati, script, webhook, utenti, gruppi, token e impostazioni.
• Solo token API; i cookie di sessione, ?token= e il MASTER_TOKEN qui non valgono. Le richieste da altre pagine del browser (Origin) vengono rifiutate, al massimo 600 chiamate per token in 10 minuti. Il server MCP funziona anche senza interfaccia di amministrazione.

Protezione dei dati

Ciò che l’assistente interroga arriva al suo fornitore IA. I record possono provenire da utenti o sistemi esterni – il server indica all’assistente di trattarli come dati, non come istruzioni.