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

<!-- install-cta -->

Use it in 60 seconds

Paste this into your MCP client config (Claude Desktop, Cursor, Windsurf, or any MCP-capable agent):

{
  "mcpServers": {
    "paraguay-invoice": {
      "type": "http",
      "url": "https://inv-py.wishpool.app/mcp"
    }
  }
}

Nothing to install. Credentials, when you need them, travel as HTTP headers on each request and are never stored — see the threat model.

Or run it yourself

Would you rather not send production credentials to a server you do not control? Deploy this identical code to your own account and point your agent at your own URL:

git clone https://github.com/junter1989k-ai/paraguay-invoice-mcp && cd paraguay-invoice-mcp && npx vercel --prod

MIT-licensed. Self-hosting removes us from the picture entirely, at no cost and with no loss of function.

---

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.