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

```json
{
  "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](https://mcp.wishpool.app/trust).

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

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/junter1989k-ai/paraguay-invoice-mcp)

```bash
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

```json
{
  "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](https://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

```bash
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](https://inv-py.wishpool.app/privacy).

## Sister servers

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

MIT licensed.