MCP (Model Context Protocol) server for POP — enabling LLMs to generate, submit, and manage Italian e-invoices (FatturaPA/SdI), Peppol, KSeF, ZUGFeRD/Factur-X, and PDF invoices directly from AI assistants.
Italian e-invoicing (FatturaPA/SdI), Peppol, KSeF, ZUGFeRD, and PDF invoice generation via POP
2026-11-10
ดาว
—
เครื่องมือ
—
อัปไทม์
—
Remote MCP (HTTP) — fastest way to get started
Don't want to install anything? pop-mcp runs as a hosted, multi-tenant MCP server at:
https://mcp.popapi.io/mcp
Head to popapi.io to grab a license key, then point any MCP-speaking client at
that URL with your key as a Bearer token. No local install, no POP_API_KEY env var, no build step
— this is the recommended way to try pop-mcp for most people. Use the local stdio setup below only
if you specifically need a Claude Desktop config running a process on your own machine.
How it works
This endpoint speaks MCP 2026-07-28, which is fully stateless: there is no initialize
handshake and no session to open or track. Every request is self-contained — it names its own
protocol version and capabilities — and the server answers it independently. Because of that,
this is a multi-tenant endpoint: it never reads a fixed POP_API_KEY from its own environment.
Every request must carry your own POP license key as a Bearer token:
Authorization: Bearer <your_license_key>
A missing or malformed Authorization header returns a 401 with error_code: "unauthorized_user"
before any POP API call is made. An invalid-but-well-formed key is passed straight through to POP's
API and surfaces whatever error POP returns (unauthorized_user, insufficient_level, etc.) — the
server does not re-validate keys itself.
Any modern MCP HTTP client can connect: Claude (remote connector), the OpenAI Responses API, n8n,
MCP Inspector, or a custom integration — not
just Claude Desktop. All invoice, status, advanced, and onboarding tools are available; onboarding
tools use their own onboarding_token per call and don't require the Bearer key.
Example with curl
Discover the server's supported protocol versions and capabilities (optional — clients can also
just call tools/list or tools/call directly and handle a version-negotiation error inline):
List the available tools — every request is self-contained, so _meta (protocol version + client
capabilities) travels on every call, not just the first one:
The tool catalog is identical for every license key, so tools/list and server/discover
responses carry a one-hour public cache hint (ttlMs: 3600000, cacheScope: "public") — clients and
gateways may cache them across tenants.
MCP-Protocol-Version and Mcp-Method are required on every request (per SEP-2243), and must
match the body's _meta.protocolVersion and method exactly, or the server rejects the request
with a 400 and JSON-RPC error -32020 (HeaderMismatch). tools/call requests additionally
require an Mcp-Name header matching params.name.
Example with MCP Inspector
npx @modelcontextprotocol/inspector
Configure it to connect to https://mcp.popapi.io/mcp with header
Authorization: Bearer <your_license_key>.
This endpoint runs as a Vercel serverless function (api/mcp.ts → src/mcpHandler.ts). To run it
locally: npx vercel dev (requires vercel link to the project first).
What is POP?
POP is a cloud service for electronic invoice generation and delivery, supporting:
🇮🇹 Italian e-invoicing (FatturaPA/SdI) — compliant with D.Lgs. 127/2015
integration is omitted when submit_to_sdi is false and no override is provided (XML-only generation).
pop_create_peppol_invoice
Generate a Peppol UBL 2.1 document. Optionally submit it to the Peppol network.
MCP inputs:
Parameter
Type
Required
Description
data
object
✅
Full invoice data. customer_type must be "company" or "freelance"
submit_to_peppol
boolean
—
Set true to submit to the Peppol network. Requires Basic+ plan. Default: false
integration
object
—
Override integration config
environment
string
—
Target environment
Integration options for integration.use:
"peppol-via-pop" or "peppol" — Submit via POP Peppol
"pop-to-webhook" — Deliver to a webhook (requires id)
VAT exemption rules specific to Peppol:
data.nature is the VAT exemption code (a VATEX code such as VATEX-EU-G, VATEX-EU-IC, VATEX-EU-AE or VATEX-EU-O; these are examples, not a complete list). It stays a free string: the POP API verifies it and answers with a plain-language error.
The exemption code comes from the user. The model never chooses, infers (countries, vies, VAT rate) or changes it, and asks when it is missing. An API error is shown to the user and the call is not retried with another code.
The API requires data.delivery_data.country (ISO 3166-1 alpha-2, country only, never the address) when the code is VATEX-EU-IC. delivery_data.date (YYYY-MM-DD) is optional and defaults to the document date. A credit note carries the same delivery_data as the invoice it reverses.
Poland only — transfer_lender.personal_data.tax_id_vat.country_id must be "PL" with a 10-digit NIP as id_code
customer_type must be "company" or "freelance" (no private individuals)
nature is always required at the top level for KSeF (unlike SdI/Peppol, where it's only required at 0% VAT) — reuses the same SdI nature codes (N1, N2.1, N2.2, N3.1, N3.2, N4, ...) to derive KSeF's internal fiscal variant
transmitter_data is not used (SdI-only concept)
payment_data.payment_details only accepts MP01, MP02/MP03, MP05, MP08 — other payment method codes are rejected at generation time
Base XML generation is available on any plan; provider submission via integration.use: "ksef" requires a Basic+ plan and the supplier already enrolled as a KSeF legal entity in the POP dashboard
Validation checks performed: XML schema conformance · fiscal code format · VAT number validity · required field presence · amount consistency
Requires: Basic+ plan with active SdI integration and registered business.
pop_preserve_document
Archive an SdI document in certified long-term digital storage (conservazione sostitutiva). Italian law requires invoices to be preserved for 10 years.
Important: Only call this tool when pop_get_invoice_status returns status RC (Ricevuta di Consegna) or MC (Mancata Consegna). Do not call for statuses NS, EC, SE, or DT.
Requires: Basic+ plan with active SdI integration.
Usage Examples
Generate a Simple Italian Invoice (XML Only)
Ask your AI assistant:
"Create a FatturaPA invoice for 1000€ + 22% VAT to Rossi SRL (VAT IT12345678901, Milan). My company is Bianchi SRL (VAT IT98765432109, Rome), using payment method bank transfer to IBAN IT60X0542811101000000123456."
Submit Invoice to SdI
"Create and submit to SdI an invoice #45 for consulting services, 500€ + 22% VAT to customer Mario Rossi (fiscal code RSSMRA80A01H501U) in Rome."
Check Invoice Status After Submission
"What's the status of SdI invoice with UUID abc123-def456-...?"
Generate PDF with Email Delivery
"Create a PDF invoice for order #123 and email it to [email protected]."
Verify SdI Document Before Sending
"Verify SdI document with UUID abc123-... for compliance before submission."
Plan Requirements
Feature
Free
Basic/Growth
Pro
XML generation (local)
✅
✅
✅
PDF generation
✅
✅
✅
SdI submission
❌
✅
✅
Peppol submission
❌
✅
✅
PDF email delivery
❌
✅
✅
SdI document verification
❌
✅
✅
Document preservation
❌
✅
✅
Testing
MCP Inspector (Interactive)
npm run inspector
# or
npx @modelcontextprotocol/inspector dist/cli.js