Usare POP da un assistente AI (MCP)

Integrazionimcp-ai2026-09-01

Obiettivo

Generare, inviare e verificare fatture SdI, PEPPOL, KSeF, ZUGFeRD e PDF, oltre a sincronizzare documenti verso Zoho, direttamente da un assistente AI (es. Claude Desktop) tramite il server MCP ufficiale (@getpopapi/pop-mcp), senza chiamare manualmente l’API REST.

Questa guida copre l’installazione locale (Node.js, stdio). Se vuoi collegare il tuo assistente senza installare nulla, esiste anche un server MCP remoto già online — vedi mcp-remote.

Prerequisiti

Node.js >= 18.
Una license_key POP valida (vedi get-your-license-key) — se non hai ancora un account, puoi ottenerla anche via flusso headless (vedi api/onboarding), senza passare dal login via browser.
Per l’invio SdI/PEPPOL: integrazione attiva sull’account POP. Nessun piano minimo: l’invio è disponibile su ogni piano, incluso Free, a consumo di crediti.

Installazione

npm install -g @getpopapi/pop-mcp

In alternativa, da sorgente: clona il repository, npm install, npm run build, poi punta il client al file dist/cli.js generato.

Configurazione

La license_key va passata come variabile d’ambiente, mai come parametro nelle chiamate:

export POP_API_KEY=la_tua_license_key

Opzionale, per usare l’ambiente sandbox: export POP_ENVIRONMENT=staging.

Collegare Claude Desktop

Aggiungi al file di configurazione (~/Library/Application Support/Claude/claude_desktop_config.json su macOS, equivalenti su Windows/Linux):

{
  "mcpServers": {
    "pop": {
      "command": "pop-mcp",
      "env": { "POP_API_KEY": "la_tua_license_key" }
    }
  }
}

Strumenti disponibili (11)

Creazione — pop_create_sdi_invoice (XML FatturaPA, invio opzionale via SdI), pop_create_peppol_invoice (UBL 2.1, invio opzionale via PEPPOL), pop_create_ksef_invoice (FA(3) XML polacco, invio opzionale via KSeF), pop_create_zugferd_invoice (bundle PDF/XML/PDF ibrido), pop_create_pdf_invoice (PDF con invio email opzionale, fino a 3 destinatari).
Sincronizzazione Zoho — pop_sync_zoho_document: sincronizza fattura o nota di credito verso Zoho Books/Invoice tramite il connector nativo dell’account; per default verifica prima che il connector Zoho sia attivo e connesso (GET /integration/zoho/status), fallendo con un errore chiaro se non lo è, invece di lasciar fallire la sincronizzazione lato Zoho.
Stato e recupero — pop_get_invoice_status (notifiche SdI), pop_get_peppol_document, pop_get_sdi_document.
Validazione e conservazione — pop_verify_sdi_document, pop_preserve_document (conservazione sostitutiva). Nessuno di questi richiede più un piano minimo.

Ogni strumento richiama le stesse route REST già documentate in api/sdi, api/peppol, api/ksef, api/zugferd, api/pdf e api/zoho — il server MCP non introduce un contratto API diverso, traduce solo le richieste dell’assistente in chiamate HTTP verso POP.

Verifica

Chiedi all’assistente qualcosa come “Crea una fattura FatturaPA da 1000€ + IVA 22% per Rossi SRL (P.IVA IT12345678901)”: se la configurazione è corretta, il tool restituisce l’XML generato (o un errore leggibile, con causa e campo coinvolto).

Errori comuni

unauthorized_user — POP_API_KEY mancante o non valida: verificala da Account > API su popapi.io.
integration_inactive — SdI o PEPPOL non è attivo sull’account: completa l’attivazione prima di usare submit_to_sdi/submit_to_peppol.
pop_api_email_limit — più di 3 destinatari email su pop_create_pdf_invoice: riduci a un massimo di 3.
pop_preserve_document chiamato nel momento sbagliato — va usato solo dopo che pop_get_invoice_status restituisce stato RC (Ricevuta di Consegna) o MC (Mancata Consegna), non per gli altri stati.
“Zoho integration is not active for this account” — restituito da pop_sync_zoho_document prima ancora di chiamare Zoho, se il connector nativo non risulta attivo/connesso: completa l’attivazione dal pannello account POP (vedi guides/integrations/zoho).

Configurazione correlata

Per il contratto dati completo (struttura data, campi obbligatori per tipo documento), vedi api/overview e le pagine specifiche per canale (api/sdi, api/peppol, api/ksef, api/zugferd, api/pdf, api/zoho).