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
- 34 tool in quattro 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 Scrittura |
| 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 Codice |
| 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 Codice |
| Salari | Consultare l'elenco del personale e registrare posizioni salariali variabili (ore, indennità, bonus) sui conteggi aperti. | Lettura Codice |
Il meccanismo di conferma
Tutto ciò che è irreversibile avviene in due fasi: l'assistente prepara l'azione e ti mostra un riepilogo con un codice di conferma monouso. Solo quando indichi il codice l'azione viene eseguita – e ogni azione una sola volta. Vale sempre per: eliminazioni, creazione e invio di fatture, scritture, giustificativi, posizioni salariali, contatori di numerazione, dati aziendali e abbonamenti. Le preparazioni non confermate scadono da sole dopo 30 minuti.
Tool disponibili
KLARA MCP mette a disposizione 34 tool. Lettura consulta soltanto dati, Scrittura viene eseguita direttamente, Codice richiede la tua conferma con il codice monouso.
Contesto e dati di riferimento
| Tool | Funzione | Accesso |
|---|---|---|
klara_whoami | Azienda collegata, tipo di accesso e aree aperte dal tuo ruolo | Lettura |
klara_reference_data | Piano dei conti, cataloghi e casi IVA, tipi di registrazione, modelli, conti bancari, cambi, località, categorie e filtri articoli | 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 | Creare o modificare un cliente – inclusi IDI, numero IVA e registro di commercio | Scrittura Eliminare: codice |
klara_prepare_customer_contact | Creare o modificare un referente di un cliente | Scrittura Eliminare: codice |
klara_prepare_customer_address | Creare o modificare un indirizzo supplementare di un cliente | Scrittura Eliminare: codice |
klara_prepare_article | Creare o modificare un articolo – inclusi tipo, caso e codice IVA | Scrittura Eliminare: codice |
klara_prepare_articles_bulk | Creare più articoli in un'unica chiamata | Scrittura |
klara_prepare_article_catalog | Creare e modificare categorie e filtri articoli, assegnarli agli articoli | Scrittura Eliminare: codice |
klara_prepare_article_image | Aggiungere o sostituire un'immagine articolo (PNG/JPEG) | Scrittura Eliminare: codice |
Fatture e documenti d'ordine
| Tool | Funzione | Accesso |
|---|---|---|
klara_get_invoice | Una fattura con destinatario, posizioni e stato contabile | Lettura |
klara_recent_invoices | Registro delle fatture create tramite KLARA MCP (l'API KLARA non ha un elenco fatture) | Lettura |
klara_invoice_pdf | Recuperare la fattura in PDF ed estrarne il testo | Lettura |
klara_order_documents | Consultare i documenti d'ordine e la configurazione della numerazione | Lettura |
klara_prepare_invoice | Creare una fattura con destinatario e posizioni o modificare una bozza | Codice |
klara_prepare_send_invoice | Recapitare una fattura contabilizzata: Smart Delivery o canale fisso (e-mail, ePost, eBill, posta) | Codice |
klara_prepare_next_number | Estrarre il prossimo numero d'ordine o di documento (fa avanzare il contatore in modo irreversibile) | Codice |
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 | Codice |
klara_prepare_receipt_attachment | Allegare un giustificativo PDF a una scrittura esistente | Codice |
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_export | Generare il file d'interfaccia salari (contenuto solo su richiesta esplicita) | Lettura |
klara_prepare_salary_item | Registrare una posizione salariale variabile (ore, indennità, bonus) su un conteggio aperto | Codice |
Azienda e meccanismo di conferma
| Tool | Funzione | Accesso |
|---|---|---|
klara_prepare_profile | Modificare o creare i dati aziendali del proprio mandante | Codice |
klara_prepare_subscription | Creare un abbonamento KLARA (a pagamento, condizioni contrattuali proprie) | Codice |
klara_pending_actions | Mostrare le azioni preparate ma non ancora confermate | Lettura |
klara_confirm | Eseguire un'azione preparata con il codice di conferma | Codice |
klara_cancel_pending | Scartare 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. Numeri AVS, date di nascita e numeri del personale non lasciano mai il server. Negli elenchi gli indirizzi e-mail sono mascherati. I file di esportazione salari restituiscono di default solo formato e dimensione, non il contenuto.
- 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