Pop MCP

pop-mcp

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.

npm: @getpopapi/pop-mcp · Remote: https://mcp.popapi.io/mcp

---

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):

curl -X POST https://mcp.popapi.io/mcp \

-H "Content-Type: application/json" \ -H "Authorization: Bearer your_license_key_here" \ -H "MCP-Protocol-Version: 2026-07-28" \ -H "Mcp-Method: server/discover" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "server/discover", "params": { "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientCapabilities": {} } } }'

List the available tools — every request is self-contained, so _meta (protocol version + client capabilities) travels on every call, not just the first one:

curl -X POST https://mcp.popapi.io/mcp \

-H "Content-Type: application/json" \ -H "Authorization: Bearer your_license_key_here" \ -H "MCP-Protocol-Version: 2026-07-28" \ -H "Mcp-Method: tools/list" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": { "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientCapabilities": {} } } }'

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 .

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
• 🇪🇺 Peppol — pan-European cross-border B2B invoicing (UBL 2.1)
• 📄 PDF invoices — branded, with email delivery
• ✅ Validation — fiscal codes, VAT numbers, document pre-submission checks
• 🗄️ Preservation — Italian legal archival (conservazione sostitutiva)

---

Tools Available (11 total)

Invoice Creation

Status & Retrieval

Validation & Advanced SdI

---

Prerequisites

• Node.js >= 20
• A POP license key
• For SdI/Peppol submission: active integration on your POP account (Basic/Growth plan)

---

Authentication

Get Your License Key

New to POP? Visit popapi.io to create your account and get your license key.

API-only users can activate their account and obtain a license_key with this flow:

1. Open https://popapi.io/otp-login/
2. Enter your email address
3. Receive a one-time password (OTP) by email and enter it
4. Complete the configuration wizard
5. Open https://popapi.io/ → Account > API
6. Copy the default generated license_key

Key Management

• Your account includes one default license_key, visible under Account > API
• You can generate additional keys linked to the same account from that same page
• Every license_key must be treated as a secret credential — do not commit it to source control

Recommended First Steps

1. Get your license_key
2. Test it with GET /account-profile
3. Send one document-generation request with a real payload
4. Add optional delivery integrations only after local generation works

---

Installation

From npm (recommended)

npm install -g @getpopapi/pop-mcp

From Source

git clone https://github.com/getpopapi/pop-mcp

cd pop-mcp npm install npm run build

---

Configuration

Set your POP license key as an environment variable:

export POP_API_KEY=your_license_key_here

Optional — use the staging environment:

export POP_ENVIRONMENT=staging

---

Claude Desktop Setup

Add to your claude_desktop_config.json:

If installed from npm:

{

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

If running from source:

{

"mcpServers": { "pop": { "command": "node", "args": ["/path/to/pop-mcp/dist/cli.js"], "env": { "POP_API_KEY": "your_license_key_here" } } } }

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

---

Tool Reference

The license_key is always injected automatically from POP_API_KEY — never pass it manually.

pop_create_sdi_invoice

Generate an Italian FatturaPA XML document. Optionally submit it to the SdI (Sistema di Interscambio).

MCP inputs:

Integration options for `integration.use`:

• "sdi-via-pop" or "sdi" — Submit via POP SdI
• "pop-to-webhook" — Deliver to a webhook (requires id)
• "fatture-in-cloud" — Deliver to Fatture in Cloud

API payload sent:

{

"license_key": "YOUR_LICENSE_KEY", "user_agent": "pop-mcp", "user_agent_version": "1.0.0", "data": { "...invoice fields..." }, "integration": { "use": "sdi-via-pop", "action": "create" } }

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:

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.

API payload sent:

{

"license_key": "YOUR_LICENSE_KEY", "user_agent": "pop-mcp", "user_agent_version": "1.0.0", "data": { "...invoice fields...", "nature": "VATEX-EU-IC", "delivery_data": { "country": "FR" } }, "integration": { "use": "peppol-via-pop", "action": "create" } }

---

pop_create_pdf_invoice

Generate a branded PDF invoice. Optionally email it to up to 3 recipients.

MCP inputs:

| send_email | boolean | — | Set true to email the PDF (requir