Gitea flags en dash, multiplication sign, minus sign and single angle quotes as confusable characters, which put a warning on most pages; use plain equivalents (docs/SPEC.md stays untouched). STATUS.md now lists the issue numbers per milestone, the items waiting for the owner and the open specification questions tracked by issue #114. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
5.8 KiB
Collegare un agente AI (MCP)
Stato: bozza · Ultima revisione: 2026-11-10 · Versione software: non ancora rilasciata (milestone M12) Modulo di licenza: API · Permessi principali: permessi della chiave; tool di scrittura abilitati per chiave · Specifica: SPEC §15
Khaemhat include un server MCP (Model Context Protocol): un assistente AI compatibile può consultare i dati del gestionale (clienti, giacenze, documenti, scadenze, bilancio, pipeline CRM) e, solo se lo consenti, creare ordini in bozza, anagrafiche e attività CRM. Il dettaglio tecnico è in docs/MCP.md.
Prima di iniziare
Attenzione ai dati. Quello che l'agente legge da Khaemhat viene passato al modello linguistico che usi (in cloud o locale). Collega solo agenti e servizi di cui ti fidi e dai alla chiave solo i permessi che servono.
Serve:
- il modulo API attivo (Licenze-e-moduli);
- Khaemhat raggiungibile in HTTPS dal computer dove gira l'agente (indirizzo pubblico configurato e reverse proxy, vedi Installazione-Docker);
- un utente tecnico con i permessi da concedere all'agente e il flag Può usare le API (Utenti-e-permessi);
- una chiave API dedicata all'agente.
Creare la chiave per l'agente
- Apri Amministrazione → Chiavi API, MCP e webhook.
- Premi Nuova chiave, scegli l'utente tecnico e l'azienda, imposta una scadenza e, se possibile, gli IP consentiti.
- Lascia disattivati i tool di scrittura se l'agente deve solo consultare.
- Salva e copia subito la chiave (
kh_…): non verrà più mostrata. - Nel riquadro Configurazione client MCP (esempio) trovi il testo già pronto da copiare nel tuo client.
Mockup 088 — chiavi con prefisso, permessi e scadenza; elenco dei tool MCP esposti dalla chiave selezionata e configurazione di esempio per il client (anteprima ridotta).
Configurare il client
La maggior parte dei client MCP che supportano server remoti accetta una configurazione come questa (sostituisci indirizzo e chiave):
{
"mcpServers": {
"khaemhat": {
"type": "http",
"url": "https://gestionale.example.com/mcp",
"headers": { "Authorization": "Bearer kh_…" }
}
}
}
Con Claude Code, da riga di comando:
claude mcp add --transport http khaemhat https://gestionale.example.com/mcp \
--header "Authorization: Bearer kh_…"
Se la chiave è di istanza (creata per più aziende) aggiungi anche l'intestazione X-Company con il codice
dell'azienda, ad esempio DEMO. Per verificare il collegamento chiedi all'assistente di elencare gli strumenti
disponibili: deve comparire l'elenco dei tool di Khaemhat.
Cosa può fare l'agente
Consultare (sola lettura)
| Strumento | A cosa serve | Esempio di domanda |
|---|---|---|
search_parties |
cercare clienti, fornitori, prospect | "Trova i clienti di Alba" |
get_party |
scheda di un cliente o fornitore | "Che condizioni di pagamento ha C000042?" |
search_items |
cercare articoli | "Articoli della categoria viteria" |
get_item_stock |
giacenze e disponibilità per deposito | "Quanti ART-0001 ho disponibili?" |
get_document |
dettaglio di un documento | "Mostrami la fattura FT/2026/000412" |
list_documents |
elenco documenti con filtri | "Ordini aperti di questo mese" |
get_open_items |
partite aperte e scadute (Scadenzario) | "Chi mi deve pagare da più di 60 giorni?" |
sales_summary |
fatturato per cliente, agente, categoria, mese | "Fatturato per agente nel 2026" |
get_account_balance |
saldo di un conto (Contabilità) | "Saldo della banca al 31 ottobre" |
trial_balance |
bilancio di verifica (Contabilità) | "Bilancio di verifica a settembre" |
vat_settlement_preview |
anteprima della liquidazione IVA | "Quanta IVA verso per ottobre?" |
crm_pipeline_summary |
riepilogo della pipeline CRM | "Valore delle opportunità per fase" |
get_log_errors |
errori recenti del log (solo amministratori) | "Ci sono errori SDI oggi?" |
Gli strumenti compaiono solo se il modulo corrispondente è attivo e la chiave ha il permesso necessario: per
esempio senza modulo Contabilità l'agente non vede trial_balance. I margini compaiono solo se l'utente tecnico
vede costi e margini.
Creare (solo se abilitato sulla chiave)
| Strumento | Cosa crea |
|---|---|
create_sale_order |
un ordine cliente in bozza, da controllare e confermare in Khaemhat |
create_party |
un nuovo cliente o prospect, con codice automatico e controlli su partita IVA e codice fiscale |
create_crm_activity |
un'attività CRM (chiamata, riunione, promemoria…) |
Nessuno strumento emette fatture, registra in contabilità o invia allo SDI: le operazioni con effetti fiscali restano nelle mani di una persona. Ogni creazione è registrata nello Storico del record con l'utente tecnico della chiave.
Domande frequenti
L'agente dice che lo strumento non esiste. Il modulo non è attivo o la chiave non ha il permesso: controlla la chiave in Amministrazione → Chiavi API, MCP e webhook.
Errore 401. Chiave sbagliata, scaduta o IP non consentito.
L'agente risponde con un errore e un codice. Comunica il codice all'amministratore: lo ritrova in Amministrazione → Log, sezione API/MCP (vedi Log).
Posso togliere l'accesso all'agente? Sì, revoca la chiave: l'effetto è immediato.
Pagine correlate
API-e-MCP · API · Utenti-e-permessi · Licenze-e-moduli · Log