Paraguay Invoice MCP 🇵🇾 — How can my AI agent issue a SIFEN e-Kuatia factura electrónica?

Remote MCP server that lets any AI agent issue and query Paraguay electronic invoices (factura electrónica / Documento Electrónico for SIFEN — the DNIT e-Kuatia system) through FacturaSend. FacturaSend generates, digitally signs and transmits the DE to SIFEN from the merchant's own account; this server is a stateless forwarder that also does the local IVA math. Bring-your-own credentials, never stores anything.

Live endpoint: https://inv-py.wishpool.app/mcp · Registry: app.wishpool/paraguay-invoice-mcp

Honest scope — what this server does and does NOT do

This wraps the FacturaSend API calls and does the IVA math. Signing and SIFEN transmission stay in your FacturaSend account.

- ✅ It does: validate and assemble the Documento Electrónico (DE) from your buyer + line items, compute the Paraguay IVA (10% / 5% / exempt, guaraní integers, tax-inclusive), forward POST /{tenant}/lote/create to FacturaSend, and translate the response (cdc, estado); look a DE up by cdc or internal id; and consult the live SIFEN estado via POST /{tenant}/de/estado.
- ❌ It does NOT: hold your digital certificate, apply the signature, or transmit to SIFEN itself. FacturaSend does all of that inside your own FacturaSend account, where your certificate and SIFEN enrolment live. This server never signs and stores nothing.

This deliberate split keeps the security-critical material (certificate, SIFEN enrolment) entirely on the FacturaSend side — a compromise of this stateless forwarder cannot forge or alter your invoices.

Quick start

{
  "mcpServers": {
    "paraguay-invoice": {
      "type": "http",
      "url": "https://inv-py.wishpool.app/mcp",
      "headers": {
        "x-facturasend-tenant": "your-facturasend-tenant-id",
        "x-facturasend-key": "your-facturasend-api-key"
      }
    }
  }
}

Self-register free at facturasend.com.py — you can integrate before you have SIFEN production enrolment or a certificate. Required headers: x-facturasend-tenant (travels in the URL path) + x-facturasend-key (sent as Authorization: Bearer api_key_...). Optional: the owner-policy headers below.

Free test environments

You do not need SIFEN production access to start:

1. draft=true on create_invoice builds the DE offline — FacturaSend does not transmit it to SIFEN (no fiscal effect). Great for wiring up the payload.
2. A FacturaSend account connected to the DNIT test environment transmits to the real SIFEN test gateway for end-to-end validation without production fiscal effect.

Whether a call is test or production is decided by your FacturaSend account / timbrado, not by this server.

Tools

| Tool | What it does |
|---|---|
| create_invoice | Issue a Paraguay DE (factura electrónica) via POST /{tenant}/lote/create with a single document. In: establecimiento, punto, numero, cliente{contribuyente,ruc?,razonSocial,tipoOperacion?,documentoTipo?,documentoNumero?,email?}, items[{descripcion,cantidad,precioUnitario,iva?,codigo?,unidadMedida?}], optional moneda (default PYG), tipoTransaccion (default 1), draft. Out: cdc (44 digits), numero, estado, respuesta_codigo/mensaje, totals. |
| query_invoice | Look up a DE by cdc OR id (pass exactly one) — GET /{tenant}/de/cdc/{cdc} or /de/id/{id}. Out: id, cdc, fecha, situacion, lote_id, lote_estado, info_codigo/descripcion. |
| get_document_status | Consult the live SIFEN estado of a cdc — POST /{tenant}/de/estado. Out: estado (Aprobado / Aprobado con observación / Rechazado), situacion, fecha, respuesta_codigo, respuesta_mensaje. |

Money & IVA (the load-bearing math)

Guaraníes (PYG) have no decimals — pass integer, tax-inclusive unit prices. IVA rate per line is 10 (standard), 5 (reduced) or 0 (exempt). Because prices include IVA, the IVA portion is liquidated as:

- 10%: iva = round(price 10 / 110)
- 5%: iva = round(price 5 / 105)
- 0%: exempt (ivaTipo 3, no IVA)

The server sets ivaTipo/ivaBase/iva per line and totals gravada10, gravada5, iva10, iva5, exenta and the grand total. Covered by test/tax.test.js (10% / 5% / mixed / rounding).

Owner policy guardrails ride optional headers (x-agentpay-max-amount, x-agentpay-approval-above, x-agentpay-allowed-tools) — set by the human owner in client config; the agent cannot relax them. Cap scope: the amount gate reads the invoice grand total (guaraníes, PYG) computed locally from the line items.

SIFEN e-Kuatia mandate

Paraguay's SIFEN (Sistema Integrado de Facturación Electrónica Nacional), branded e-Kuatia, is administered by the DNIT (formerly SET). Since 2022 the DNIT has incorporated taxpayers into electronic invoicing in successive obligatory groups (grupos), progressively covering all businesses — issuing the Documento Electrónico instead of paper/pre-printed invoices is increasingly mandatory. Check your assigned group and start date on the DNIT / e-Kuatia portal; FacturaSend lets you integrate and test ahead of your mandatory date.

Endpoints wrapped

Base https://api.facturasend.com.py, auth Authorization: Bearer api_key_<key>, tenant id in the path:

| Tool | Call |
|---|---|
| create_invoice | POST /{tenant}/lote/create (JSON array with one DE; ?draft=true = offline) |
| query_invoice | GET /{tenant}/de/cdc/{cdc} or GET /{tenant}/de/id/{id} |
| get_document_status | POST /{tenant}/de/estado body { cdcList: [{ cdc }] } |

FacturaSend responses are passed through: { success:false, error } (e.g. API Key inválida) surfaces as FacturaSend API error: ….

Develop

node test/tax.test.js   # IVA math unit tests (10% / 5% / mixed / rounding)
node test/serve.js      # local server on :3262
node test/e2e.js        # protocol + validation + policy asserts + LIVE fake-key probes against FacturaSend

The e2e suite makes real calls to api.facturasend.com.py: a fake tenant + fake API key runs the full create_invoice / query_invoice / get_document_status path and surfaces FacturaSend's native {"success":false,"error":"… Auth: API Key inválida"} (HTTP 400) — the deepest live verification possible without a real onboarded FacturaSend account (we never sign, so we cannot mint a valid document).

Safety

Pure stateless translation layer. Digital signing and SIFEN transmission happen inside the merchant's own FacturaSend account; the tenant id and API key travel per-request in headers, nothing is stored. Privacy policy.

Sister servers

Invoices: Mexico CFDI inv-mx · Brazil NF-e inv-br · Chile DTE inv-cl · Peru CPE inv-pe · Argentina AFIP inv-ar · Costa Rica Hacienda inv-cr · Ecuador SRI inv-ec · Saudi ZATCA inv-sa · India GST inv-in · Poland KSeF inv-pl · Local payments in 81 countries, one family: mcp.wishpool.app · Taiwan e-invoice 電子發票 included.

MIT licensed.