Documentazione del server MCP
Validare, creare, convertire ed estrarre fatture elettroniche da Claude, ChatGPT e altri client MCP
Il server MCP remoto collega un assistente AI alla Electronic Invoice API. Effettui l'accesso una sola volta con la Sua chiave API; successivamente l'assistente può validare fatture XRechnung e ZUGFeRD, crearle a partire dai Suoi dati, convertirle ed esportarle. Questa pagina illustra la configurazione, gli strumenti, i formati supportati e la risoluzione dei problemi.
Server
| URL | https://mcp.electronic-invoice.app/mcp (Streamable HTTP) |
|---|---|
| MCP Registry | Elencato nel MCP Registry ufficiale come app.electronic-invoice/mcp |
| Accesso | OAuth 2.1, oppure Authorization: Bearer con la Sua chiave API per i client diretti |
| Senza accesso | Strumenti per lo stato del servizio e i limiti |
| Destinatari | Solo aziende (B2B) |
Accesso e chiave API
Il server MCP non dispone di account propri. Crei una chiave API nella console. Quando l'assistente utilizza per la prima volta uno strumento protetto, apre una pagina di accesso su mcp.electronic-invoice.app, dove Lei inserisce la chiave. Per la durata della connessione la chiave viene memorizzata esclusivamente in forma crittografata con AES-GCM. Viene eliminata quando Lei revoca la connessione o alla scadenza.
I client che non supportano OAuth possono inviare la chiave direttamente come Authorization: Bearer eia_live_.... Gli strumenti per lo stato del servizio e i limiti funzionano senza alcun accesso.
Configurazione
I nomi dei menu cambiano tra le versioni; se un'etichetta è diversa, cerchi la voce equivalente.
Claude
- Apra Impostazioni o Personalizza, quindi Connettori.
- Scelga Aggiungi connettore personalizzato e inserisca
https://mcp.electronic-invoice.app/mcp. - In una chat, chieda qualcosa che richieda uno strumento per le fatture. Al primo utilizzo di uno strumento protetto, Claude Le chiede di effettuare la connessione; acceda con la Sua chiave API.
ChatGPT
Al momento questa funzione è disponibile tramite la modalità sviluppatore: in Impostazioni, App, crei un'app con l'URL del server e scelga OAuth come autenticazione. I passaggi esatti dipendono dal Suo piano e dalle impostazioni dell'area di lavoro.
Altri client
Qualsiasi client che supporti server MCP remoti tramite Streamable HTTP può utilizzare l'URL. Scelga OAuth, se disponibile, oppure imposti l'intestazione bearer con la Sua chiave API.
Strumenti
| Strumento | Cosa fa |
|---|---|
validate_invoice | Verifica una fattura elettronica (XML o PDF) e restituisce l'esito e i rilievi con l'ID della regola |
generate_invoice | Crea una fattura XRechnung (UBL o CII) o un PDF ZUGFeRD/Factur-X a partire dai dati della fattura in JSON |
convert_invoice | Converte UBL in CII, CII in UBL oppure XML in PDF |
extract_invoice | Legge i dati della fattura come JSON, CSV o esportazione DATEV |
open_invoice_check | Apre un campo di caricamento nella chat, per i client che non possono trasmettere file allo strumento (ad esempio Claude) |
get_service_status | Stato del servizio e versioni del set di regole, senza necessità di accesso |
get_usage_limits | Limiti tecnici (frequenza, dimensione, codici di stato fatturabili), senza necessità di accesso |
Formati supportati per la validazione
Il server MCP verifica gli stessi formati dell'API: XRechnung, EN 16931, Peppol BIS, NLCIUS, CIUS-RO, regole CIUS francesi, ZUGFeRD/Factur-X e, per l'Italia e la Polonia, solo rispetto allo schema. La tabella con l'ambito della verifica per formato si trova nella pagina dell'API. La creazione di fatture è limitata a XRechnung e ZUGFeRD/Factur-X. Il server non invia fatture e non dispone di accesso a Peppol.
Esempi di prompt
- "Questa fattura elettronica è valida?" con un file PDF o XML allegato. In Claude l'assistente apre il campo di caricamento.
- "Crei una fattura XRechnung (CII) per Muster GmbH, 3 ore di consulenza a EUR 120, IVA al 19%, riferimento dell'acquirente 04011000-12345-34." Quindi verifichi i dati che l'assistente elenca prima di utilizzare il file.
- "Converta questa fattura UBL in CII."
- "Esporti questa fattura come batch di registrazioni contabili DATEV."
- "Quale regola viene violata qui e cosa deve modificare nell'XML?"
- "Il servizio di fatturazione è attivo e quali sono i limiti di frequenza e dimensione?"
Quota e costi
Ogni chiamata fatturabile incide sulla quota del Suo piano, esattamente come una chiamata API diretta. I piani e i limiti sono elencati nella pagina dell'API. L'apertura del campo di caricamento è gratuita; una verifica viene conteggiata nel momento in cui viene avviata.
Risoluzione dei problemi
- Accesso in loop: la chiave è stata rifiutata o è stata revocata. Crei una nuova chiave nella console, rimuova il connettore nel client e lo aggiunga di nuovo. Inserisca la chiave solo nella pagina di accesso, non nelle impostazioni del connettore.
- Errore 401: la chiave è assente, errata o revocata. Si riconnetta con una chiave attiva; in caso di intestazione bearer, verifichi il valore dell'intestazione.
- Errore 429 (quota superata): la quota mensile del Suo piano è esaurita. Attenda il periodo successivo o cambi piano. In caso di 429 con un tempo di attesa (limite di frequenza), riprovi dopo i secondi indicati.
- File non trasmesso: il client non può consegnare il file allo strumento. Chieda all'assistente di aprire la verifica della fattura; viene mostrato un campo di caricamento nella chat.
- Il risultato sembra errato: chieda i rilievi con gli ID delle regole e li confronti con la fattura. I rilievi sono il risultato delle regole ufficiali, non un'affermazione sul Suo contratto o sulla Sua posizione fiscale.
Ha ancora problemi? Ci scriva tramite la pagina dei contatti.
Privacy e condizioni
Quali dati vengono trattati, dove e per quanto tempo è indicato nell'informativa sulla privacy, sezione sul server MCP. Si applicano le condizioni dell'API. Se inserisce una fattura in una chat, anche il fornitore dell'assistente la vede; per questo si applicano le condizioni del fornitore.
Nota: le verifiche e i risultati sono ausili tecnici, non consulenza legale o fiscale.
I testi legali sono disponibili in tedesco e inglese: informativa sulla privacy, termini API e note legali. Solo la versione tedesca è giuridicamente vincolante.