Files
Khaemhat/docs/wiki/MCP.md
T
Alby96andClaude Opus 5.5 88de272b3e docs: avoid ambiguous Unicode and record Gitea planning in STATUS
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>
2026-11-10 22:44:14 +01:00

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:

  1. il modulo API attivo (Licenze-e-moduli);
  2. Khaemhat raggiungibile in HTTPS dal computer dove gira l'agente (indirizzo pubblico configurato e reverse proxy, vedi Installazione-Docker);
  3. un utente tecnico con i permessi da concedere all'agente e il flag Può usare le API (Utenti-e-permessi);
  4. una chiave API dedicata all'agente.

Creare la chiave per l'agente

  1. Apri Amministrazione → Chiavi API, MCP e webhook.
  2. Premi Nuova chiave, scegli l'utente tecnico e l'azienda, imposta una scadenza e, se possibile, gli IP consentiti.
  3. Lascia disattivati i tool di scrittura se l'agente deve solo consultare.
  4. Salva e copia subito la chiave (kh_…): non verrà più mostrata.
  5. Nel riquadro Configurazione client MCP (esempio) trovi il testo già pronto da copiare nel tuo client.

088 · Chiavi API, MCP e webhook 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