Usare POP da un assistente AI senza installazione (MCP remoto)

Integrazionimcp-ai2026-07-24

Obiettivo

Collegare un assistente AI (Claude, o qualunque client che parla MCP) al server MCP remoto ufficiale di POP (https://mcp.popapi.io/mcp), senza installare Node.js né configurare nulla in locale — a differenza della versione locale, qui basta un URL.

Prerequisiti

Una license_key POP valida (vedi get-your-license-key) — oppure, se non hai ancora un account, puoi crearne uno conversando con l’assistente stesso: vedi onboard-via-ai-assistant.
Un client che supporta MCP via HTTP: Claude (connector remoto), OpenAI Responses API, n8n, MCP Inspector, o un’integrazione custom.

Come funziona

Endpoint: https://mcp.popapi.io/mcp — trasporto Streamable HTTP.
Il server è stateless e multi-tenant: non c’è una license_key configurata lato server come nella versione locale. Ogni singola richiesta deve portare la tua chiave come header:
```
Authorization: Bearer la_tua_license_key
```
Se l’header manca o è malformato, la richiesta fallisce con 401 (unauthorized_user) prima di chiamare l’API POP. Se invece la chiave è presente ma non valida, la richiesta arriva a POP e restituisce l’errore che POP stesso genera (es. unauthorized_user, insufficient_level).

Collegare Claude

Aggiungi un nuovo connector remoto puntato a https://mcp.popapi.io/mcp, con header Authorization: Bearer la_tua_license_key — la procedura esatta dipende dalla versione di Claude che usi (desktop o web): cerca “connector” o “MCP remoto” nelle impostazioni.

Provare con MCP Inspector

npx @modelcontextprotocol/inspector

Configuralo per puntare a https://mcp.popapi.io/mcp, con lo stesso header Authorization: Bearer.

Provare con curl

curl -X POST https://mcp.popapi.io/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer la_tua_license_key" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Strumenti disponibili (16)

Gli stessi 11 strumenti della versione locale (creazione/invio SdI, PEPPOL, KSeF, ZUGFeRD, PDF, sincronizzazione Zoho, stato, verifica, conservazione), più 5 strumenti di onboarding (pop_onboarding_request_otp, pop_onboarding_verify_otp, pop_onboarding_get_status, pop_onboarding_get_account_setup, pop_onboarding_save_account_setup) che non richiedono l’header Bearer: usano un proprio onboarding_token temporaneo, pensato apposta per creare un account da zero. Vedi onboard-via-ai-assistant per il flusso completo.

Da sapere

Il server gira come funzione serverless: è stateless, ogni richiesta è indipendente — non aspettarti che ricordi conversazioni precedenti al di fuori di quello che il client MCP stesso gestisce.
https://mcp.popapi.io/health è un endpoint di stato pensato per il monitoraggio, non per l’uso conversazionale.

Errori comuni

401 unauthorized_user immediato — header Authorization assente o non nel formato Bearer <chiave>: il server lo rifiuta prima ancora di contattare POP.
Chiave presente ma richiesta rifiutata da POP — la chiave è formalmente valida ma POP la rifiuta (piano insufficiente, integrazione non attiva): l’errore restituito è quello di POP, non del server MCP.
Il client non trova il tool giusto — verifica di aver connesso il client all’URL /mcp (non alla home page https://mcp.popapi.io/, che è solo la landing page informativa).

Configurazione correlata

Per l’installazione locale (stdio, via npm) vedi mcp. Per il contratto dati completo delle fatture, vedi api/overview, api/sdi, api/peppol, api/ksef, api/zugferd, api/pdf e api/zoho.