Salta ai contenuti
Nuntius

Guide

La mia IA e il mio backend, che parlano con i miei dati

Visualizza come Markdown

Se sei arrivato qui probabilmente hai già visto il server MCP e la referenza API separatamente. Sono due facce della stessa superficie /public/v1 — questa pagina è il ponte che le collega, per il caso reale «voglio il mio assistente IA (Claude, Cursor) che parla con i miei dati di Nuntius, E anche il mio backend che chiama direttamente l’API pubblica».

Perché sono la stessa cosa internamente

Sezione intitolata “Perché sono la stessa cosa internamente”

Il server MCP non ha logica propria: i suoi tool sono generati leggendo la stessa definizione OpenAPI che documenta questa referenza REST, e ogni chiamata di un tool inoltra la tua stessa chiave API a /public/v1, così com’è. Tutto il controllo reale — permessi, piano, limiti, isolamento per account — lo applica l’API, mai l’adattatore MCP. Per questo: una sola chiave, un solo insieme di scope, due modi di usarli.

Il ponte in 3 passi

Sezione intitolata “Il ponte in 3 passi”
  1. Crea una chiave API con gli scope che servono a entrambi gli usi. Vedi Chiavi API — viene mostrata per intero una sola volta, conservala. Se il tuo assistente IA deve solo leggere i lead e il tuo backend deve anche creare ticket, assegna alla chiave entrambi gli scope: tenant:leads.read e tenant:tickets.manage, per esempio — la stessa chiave serve entrambi gli usi contemporaneamente.
  2. Collega il tuo assistente IA tramite MCP con quella chiave — Claude Desktop, Claude Code o Cursor parlano Streamable HTTP su https://mcp.nuntius.chat/mcp con l’header X-Api-Key. Vedi Collega il tuo assistente. Da qui, il tuo assistente può leggere e (con la tua conferma, vedi La conferma nelle scritture) scrivere nel tuo account durante la conversazione.
  3. Collega il tuo backend direttamente all’API pubblica, con la stessa chiave, nell’header X-API-Key di ogni richiesta HTTP — senza MCP in mezzo, per il codice che gira senza supervisione umana turno per turno. Vedi i 5 casi d’uso con esempi di codice.

Quando usare ciascun percorso

Sezione intitolata “Quando usare ciascun percorso”
PercorsoA cosa serveConferma
MCP (https://mcp.nuntius.chat/mcp)Il tuo assistente conversazionale (Claude, Cursor) esplora e agisce sul tuo account dentro una sessione con una persona presente.Ogni scrittura richiede confirm: true — pensato perché la persona veda il riepilogo dell’azione prima di approvarla.
API pubblica (https://api.nuntius.chat/public/v1)Il tuo backend, uno script programmato, o un’integrazione con un altro sistema (CRM, helpdesk, Zapier…) che gira senza supervisione turno per turno.Nessun passaggio di conferma intermedio — il tuo codice decide ed esegue direttamente.

Un esempio reale che usa entrambi insieme: il tuo assistente Claude Code, collegato tramite MCP, consulta e qualifica i lead mentre ci parli; il tuo stesso backend, con la stessa chiave ma tramite l’API diretta, sincronizza quegli stessi lead verso il tuo CRM ogni ora senza che nessuno lo guardi — vedi Sincronizzare i lead verso il tuo CRM.

Vedi anche

Sezione intitolata “Vedi anche”