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 <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
• 🇪🇺 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: