Panoramica
KLARA MCP è un server basato sul protocollo aperto Model Context Protocol (MCP), gestito da ePost Service SA. Collega gli assistenti IA compatibili MCP – per esempio Claude o ChatGPT – al tuo mandante KLARA. L'assistente può così cercare e gestire clienti e articoli, creare fatture con posizioni e destinatario, registrare scritture con giustificativi e inserire posizioni salariali variabili sui conteggi salario aperti.
- Indirizzo del server:
https://mcp.klara.ch/mcp - Trasporto: Streamable HTTP · Accesso: OAuth 2.0 con chiave API KLARA personale
- 64 tool in sette aree, vedi Tool disponibili
Collegare
Passo 1 per tutti i client: creare una chiave API in KLARA. In KLARA, sotto Utenti, crea una nuova chiave API. Assegnale solo i ruoli di cui hai davvero bisogno – KLARA MCP raggiunge esattamente ciò che il ruolo della chiave apre. L'accesso funziona esclusivamente con una chiave API; la tua password KLARA va inserita solo su KLARA, mai altrove.
Collegare con Claude
- In Claude, sotto Impostazioni → Connettori, scegli Aggiungi connettore personalizzato e inserisci
https://mcp.klara.ch/mcp– oppure seleziona la voce KLARA nella directory dei connettori. - Claude apre la pagina di accesso di KLARA MCP: incolla la chiave API e collegati.
Collegare con ChatGPT
- Apri chatgpt.com/plugins e fai clic sul più «Nuovo plugin». Inserisci l'indirizzo
https://mcp.klara.ch/mcp. - Al primo collegamento si apre la pagina di accesso di KLARA MCP: incolla la chiave API e collegati.
Inizia con il prompt «KLARA whoami» – l'assistente ti mostra con quale azienda sei collegato e quali aree apre il tuo ruolo.
Esempi
Ecco come appaiono richieste tipiche al tuo assistente IA (tutti i dati sono inventati):
Funzionalità
| Area | Cosa può fare l'assistente | Accesso |
|---|---|---|
| Clienti & articoli | Cercare, creare e modificare: clienti con indirizzi, referenti, IDI e numero IVA; articoli con prezzi, IVA e immagini; categorie e filtri. | Lettura Approvazione |
| Fatture & ordini | Creare fatture con posizioni e destinatario e recuperarle in PDF; invio per e-mail, ePost, eBill o posta; consultare i documenti d'ordine. | Lettura Approvazione |
| Contabilità | Registrare scritture manuali con giustificativi, consultare piano dei conti e cataloghi IVA, leggere le posizioni aperte della riconciliazione bancaria e i rendiconti IVA. | Lettura Approvazione |
| Salari | Consultare l'elenco del personale e registrare posizioni salariali variabili (ore, indennità, bonus) sui conteggi aperti. | Lettura Approvazione |
Il meccanismo di conferma
Tutto ciò che è irreversibile avviene in due fasi: l'assistente prepara l'azione e ti mostra un riepilogo e un link alla pagina di approvazione di KLARA MCP. Lì approvi l'azione tu stesso, con il codice della tua app di autenticazione o con una passkey (Touch ID, Face ID, Windows Hello). L'assistente non riceve in nessun momento un codice o un segreto; esegue solo ciò che hai approvato, nemmeno su istruzione contenuta in un documento. L'approvazione vale per questa singola azione e viene registrata sul server. Sulla pagina di approvazione puoi anche annullare l'azione. Al primo collegamento configuri una volta l'app di autenticazione (codice QR); vale per la tua chiave API, anche se in seguito colleghi KLARA a un altro servizio di IA. Altro browser o altro dispositivo: inserisci lì una volta la tua chiave API. Ogni azione viene eseguita una sola volta. Vale per ogni accesso in scrittura: dati di base (clienti, referenti, indirizzi, articoli, categorie, immagini) così come eliminazioni, creazione e invio di fatture, scritture, giustificativi, posizioni salariali e contatori di numerazione. Le preparazioni non confermate scadono da sole dopo 30 minuti.
Tool disponibili
KLARA MCP mette a disposizione 64 tool – ogni operazione è un tool a sé. Lettura consulta soltanto dati, Approvazione prepara l'azione e richiede la tua approvazione nel browser (codice di autenticazione o passkey), Scrittura agisce solo su preparazioni (scartare).
Contesto
| Tool | Funzione | Accesso |
|---|---|---|
klara_whoami | Azienda collegata, tipo di accesso e aree aperte dal tuo ruolo | Lettura |
Dati di riferimento
| Tool | Funzione | Accesso |
|---|---|---|
klara_accounts | Piano dei conti – completo o un conto per numero | Lettura |
klara_account_picker | Selezione dei conti per le righe di registrazione, inclusi i valori links | Lettura |
klara_booking_types | Tipi di registrazione | Lettura |
klara_business_case_templates | Modelli di casi aziendali – catalogo, selezione dell'azienda o singolo | Lettura |
klara_business_case | Un singolo caso aziendale per id | Lettura |
klara_business_case_from_template | Leggere il caso aziendale derivato da un modello (modello di registrazione pronto, sola lettura) | Lettura |
klara_accounting_config | Impostazioni contabili dell'azienda | Lettura |
klara_financial_years | Esercizi contabili dell'azienda | Lettura |
klara_vat_master | Catalogo IVA – elenco, solo quelli in vigore o singolo | Lettura |
klara_vat_types | Tipi IVA – elenco o singolo | Lettura |
klara_vat_cases | Casi IVA (ad es. TAXABLE_SUPPLY) – elenco o singolo | Lettura |
klara_vat_profile | Profilo IVA dell'azienda (modalità di rendiconto, aliquota saldo) | Lettura |
klara_vat_suggestions | Suggerimenti IVA di KLARA | Lettura |
klara_company_vats | Aliquote IVA registrate nell'azienda | Lettura |
klara_vat_included_setting | Se i prezzi sono gestiti IVA inclusa o esclusa | Lettura |
klara_bank_accounts | Conti bancari dell'azienda | Lettura |
klara_exchange_rate | Tasso di cambio di una valuta in CHF | Lettura |
klara_article_categories | Categorie articoli – elenco o singola | Lettura |
klara_article_filters | Filtri articoli – elenco o singolo | Lettura |
klara_city | Una località nell'elenco delle località di KLARA | Lettura |
Clienti e articoli
| Tool | Funzione | Accesso |
|---|---|---|
klara_search_customers | Cercare clienti per nome, e-mail, telefono o numero cliente | Lettura |
klara_get_customer | Un cliente in dettaglio, su richiesta con referenti e indirizzi supplementari | Lettura |
klara_search_articles | Articoli tramite ricerca full-text o elenco per tipo di prodotto | Lettura |
klara_article_details | Un articolo con varianti, componenti del set e immagine | Lettura |
klara_lookup_articles | Articoli per numero di articolo o come elenco di varianti risolto | Lettura |
klara_prepare_customer_create | Creare un cliente – inclusi IDI, numero IVA e registro di commercio | Approvazione |
klara_prepare_customer_update | Modificare un cliente – il server legge l'esistente e sostituisce solo i campi indicati | Approvazione |
klara_prepare_customer_delete | Eliminare un cliente (definitivo) | Approvazione |
klara_prepare_contact_create | Creare un referente di un cliente | Approvazione |
klara_prepare_contact_update | Modificare un referente | Approvazione |
klara_prepare_contact_delete | Eliminare un referente (definitivo) | Approvazione |
klara_prepare_address_create | Creare un indirizzo supplementare di un cliente | Approvazione |
klara_prepare_address_update | Modificare un indirizzo supplementare | Approvazione |
klara_prepare_address_delete | Eliminare un indirizzo supplementare (definitivo) | Approvazione |
klara_prepare_article_create | Creare un articolo – inclusi tipo, caso e codice IVA | Approvazione |
klara_prepare_article_update | Modificare un articolo – il server riprende i campi obbligatori dall'esistente | Approvazione |
klara_prepare_article_delete | Eliminare un articolo (definitivo) | Approvazione |
klara_prepare_articles_bulk | Creare più articoli in un'unica chiamata | Approvazione |
klara_prepare_catalog_create | Creare una categoria o un filtro articoli | Approvazione |
klara_prepare_catalog_update | Modificare una categoria o un filtro articoli | Approvazione |
klara_prepare_catalog_delete | Eliminare una categoria o un filtro articoli (definitivo) | Approvazione |
klara_prepare_catalog_assign | Assegnare una categoria o un filtro a un elenco di articoli | Approvazione |
klara_prepare_article_image_upload | Aggiungere o sostituire un'immagine articolo (PNG/JPEG) | Approvazione |
klara_prepare_article_image_delete | Eliminare un'immagine articolo (definitivo) | Approvazione |
Fatture e documenti d'ordine
| Tool | Funzione | Accesso |
|---|---|---|
klara_get_invoice | Una fattura con destinatario, posizioni e stato contabile | Lettura |
klara_list_invoices | Cercare e sfogliare le fatture: testo libero, filtri per stato e stato di pagamento | Lettura |
klara_invoice_pdf | Recuperare la fattura in PDF ed estrarne il testo | Lettura |
klara_order_documents | Consultare i documenti d'ordine di un numero d'ordine | Lettura |
klara_order_numbering | Leggere la configurazione della numerazione (automatica o manuale) | Lettura |
klara_prepare_invoice | Creare una fattura con destinatario e posizioni o modificare una bozza | Approvazione |
klara_prepare_send_invoice | Recapitare una fattura contabilizzata: Smart Delivery o canale fisso (e-mail, ePost, eBill, posta) | Approvazione |
klara_prepare_next_number | Estrarre il prossimo numero d'ordine o di documento (fa avanzare il contatore in modo irreversibile) | Approvazione |
Contabilità
| Tool | Funzione | Accesso |
|---|---|---|
klara_bank_open_positions | Posizioni aperte della riconciliazione bancaria | Lettura |
klara_vat_report | Leggere il rendiconto IVA di un periodo (senza ricalcolo) | Lettura |
klara_prepare_booking | Registrare una scrittura manuale, su richiesta con giustificativo PDF; dare/avere verificato in anticipo | Approvazione |
klara_prepare_receipt_attachment | Allegare un giustificativo PDF a una scrittura esistente | Approvazione |
Salari
| Tool | Funzione | Accesso |
|---|---|---|
klara_search_employees | Elenco del personale con ricerca, filtri e ordinamento | Lettura |
klara_addable_salary_items | Quali tipi di salario sono ammessi sul conteggio salario aperto di una persona | Lettura |
klara_payroll_file_check | Verificare il file d'interfaccia salari – solo formato e dimensione, mai il contenuto | Lettura |
klara_prepare_salary_item | Registrare una posizione salariale variabile (ore, indennità, bonus) su un conteggio aperto | Approvazione |
Meccanismo di approvazione
| Tool | Funzione | Accesso |
|---|---|---|
klara_pending_actions | Mostrare le azioni preparate ma non ancora confermate | Lettura |
klara_confirm | Eseguire un'azione che hai approvato sulla pagina di approvazione | Approvazione |
klara_cancel_pending | Scartare definitivamente un'azione preparata | Scrittura |
Sicurezza & dati
- Accesso via OAuth 2.0, esclusivamente con chiave API. L'assistente IA non riceve mai la tua chiave API KLARA – resta cifrata sul server KLARA MCP (gestito da ePost Service SA, ospitato a Francoforte) e serve solo per le chiamate a KLARA. Volutamente non esiste un accesso con nome utente e password KLARA: la tua password va inserita solo sulla pagina di accesso di KLARA.
- Il tuo ruolo determina l'accesso. KLARA MCP raggiunge esattamente le aree che il ruolo della tua chiave API apre in KLARA – non di più.
- Minimizzazione dei dati. Numero AVS, data di nascita, numero del personale, numero di figli e pagamento in contanti vengono rimossi da ogni risposta e non raggiungono mai l'assistente IA. I file di esportazione salari restituiscono esclusivamente formato e dimensione, il loro contenuto non viene mai trasmesso tramite il connettore. Negli elenchi gli indirizzi e-mail sono mascherati. Tutto il resto che consulti arriva all'assistente in chiaro: nomi e tipi di salario dei tuoi collaboratori, dati dei clienti, posizioni di fattura, testi dei giustificativi.
- Cosa vede l'assistente IA. I risultati dei tool – per esempio i clienti trovati o il riepilogo di una fattura – confluiscono nella tua conversazione e vengono trattati dal fornitore (per es. Anthropic o OpenAI) come gli altri contenuti della chat.
- Servizio aggiuntivo facoltativo. Il connettore IA non fa parte del normale uso di KLARA – lo attivi consapevolmente e decidi tu con quale servizio IA collegare KLARA. Il fornitore scelto tratta i contenuti consultati secondo le proprie condizioni, eventualmente fuori dalla Svizzera. La pagina di accesso lo segnala al momento del collegamento.
- Termini di cancellazione. I link di accesso e i codici monouso vengono cancellati alla scadenza. I contenuti dei giustificativi delle azioni preparate vengono eliminati subito dopo esecuzione, annullamento o scadenza, i loro riepiloghi dopo 30 giorni. Le connessioni inutilizzate per 180 giorni vengono cancellate insieme alla chiave API cifrata; il registro delle fatture dopo un anno.
- Protezione dei dati. I dettagli sul trattamento dei dati presso KLARA li trovi nella dichiarazione sulla protezione dei dati.
- Terminare l'accesso. Elimina la chiave API in KLARA sotto Utenti – l'accesso termina subito e completamente. In più puoi rimuovere il connettore nel tuo assistente IA.
Risoluzione dei problemi
«Accesso negato» o manca un'area
Al ruolo della tua chiave API manca l'autorizzazione, oppure alla tua azienda l'abbonamento KLARA corrispondente – senza abbonamento una funzione resta chiusa anche per gli amministratori. Chiedi all'assistente «KLARA whoami»: la risposta mostra quali aree sono aperte. Per più accesso, crea in KLARA sotto Utenti una chiave con il ruolo adatto e ricollegati.
Una località viene rifiutata alla creazione
KLARA verifica le località nel proprio registro e ne conosce alcune solo con la sigla del cantone – per esempio «Studen BE» invece di «Studen». Adatta la grafia e riprova; il messaggio d'errore lo segnala.
La creazione della fattura richiede un numero di documento
La tua azienda numera le fatture manualmente. KLARA MCP non estrae allora volutamente alcun numero dal contatore – indica all'assistente il prossimo numero della tua serie, verrà usato come numero di documento. Con la numerazione automatica avviene da sé.
Nessun PDF della fattura alla contabilizzazione
È il comportamento dell'API KLARA: a differenza dell'interfaccia, non genera alcun documento alla contabilizzazione. Chiedi poi all'assistente di creare il PDF – su richiesta lo allega alla scrittura.
Le nuove funzioni non compaiono
Gli assistenti IA memorizzano l'elenco dei tool di un server al collegamento. Dopo un aggiornamento di KLARA MCP scollegati una volta e ricollegati.
La prima risposta tarda
Dopo una pausa prolungata il server si riavvia (avvio a freddo). La prima richiesta può quindi durare alcuni secondi, poi tutto è veloce.
«Questa azione non è più valida»
Le azioni preparate scadono dopo 30 minuti senza conferma – per sicurezza. Chiedi semplicemente all'assistente di preparare di nuovo l'azione.
Errore del server con id incidente durante contabilizzazione, PDF o invio
Errori noti dell'interfaccia KLARA (stato: agosto 2026, segnalati a KLARA): la contabilizzazione delle fatture, la generazione del PDF e l'invio possono fallire tramite l'interfaccia con un errore del server, mentre la stessa azione funziona nell'interfaccia KLARA. Esegui l'azione in KLARA; l'id incidente del messaggio aiuta il supporto.
Supporto
Domande, problemi o segnalazioni di sicurezza su KLARA MCP: support@klara.ch
Utile per una risposta rapida: il messaggio d'errore del tuo assistente IA – in caso di errori KLARA contiene un id dell'incidente che rende il caso univoco. Non inviare mai chiavi API o password.
Di più su KLARA: klara.ch · Per sviluppatrici e sviluppatori: developer.klara.ch