# Costa Rica Invoice MCP 🇨🇷 — How can my AI agent submit a Hacienda factura electrónica (comprobante electrónico v4.4)?

Remote MCP server that lets any AI agent submit **Costa Rica electronic invoices** (**comprobante electrónico v4.4**) to the **Ministerio de Hacienda** national e-invoicing gateway. It forwards an **already-signed** v4.4 XML to the reception (`/recepcion`) endpoint and returns Hacienda's response. Stateless, bring-your-own credentials, never stores anything.

**Live endpoint:** `https://inv-cr.wishpool.app/mcp` · Registry: `app.wishpool/costa-rica-invoice-mcp`

## Honest scope — what this server does and does NOT do

**This wraps the submission calls only. Signing stays merchant-side.**

- ✅ **It does:** exchange your ATV API user/password for a short-lived OAuth token (Keycloak password grant), forward `{ clave, fecha, emisor, receptor?, comprobante_xml(base64) }` to the Hacienda `/recepcion` endpoint, and translate the response (HTTP 202 → `ind_estado`); poll status via `/recepcion/{clave}`. It also offers a pure-local `build_clave` helper to assemble the 50-digit clave numérica.
- ❌ **It does NOT:** build your XML, apply your **XAdES signature**, or hold your **Hacienda certificate / llave criptográfica**. The v4.4 XML is signed with your certificate in your own system, next to your private key. You sign each comprobante and pass the signed bytes here.

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

## Quick start

```json
{
  "mcpServers": {
    "costa-rica-invoice": {
      "type": "http",
      "url": "https://inv-cr.wishpool.app/mcp",
      "headers": {
        "x-hacienda-username": "your-atv-api-user",
        "x-hacienda-password": "your-atv-api-password",
        "x-hacienda-mode": "prod"
      }
    }
  }
}
```

Register your **API user** in ATV ("Registro de Usuarios API") to get the username/password. Omit `x-hacienda-mode` to stay in the **`stag` sandbox** (realm `rut-stag`, `recepcion-sandbox`, no fiscal effect); `prod` = production (realm `rut`, real fiscal effect). **Required** headers: `x-hacienda-username` + `x-hacienda-password`. **Optional:** `x-hacienda-mode` (default `stag`) and the owner-policy headers below.

## Tools

| Tool | What it does |
|---|---|
| `submit_invoice` | Forward an **already-signed** v4.4 comprobante to Hacienda `/recepcion`. In: `clave`, `fecha`, `emisor{tipoIdentificacion,numeroIdentificacion}`, `receptor?`, `comprobante_xml` (base64 signed XML). Out: HTTP **202** with `ind_estado` `recibido`/`procesando` (Hacienda processes asynchronously). |
| `query_invoice` | Poll `/recepcion/{clave}`. Out: `ind_estado` **aceptado** (fiscally valid — hand `respuesta_xml` to the buyer), **rechazado** (rejected — read `respuesta_xml`, fix, resubmit), `procesando`/`recibido`, or `error`. |
| `build_clave` | **Pure local helper (no network, no credentials):** assemble the 50-digit **clave numérica** from `506` + DD + MM + YY + cédula(12) + consecutivo(20) + situación(1) + códigoSeguridad(8). |

## The 50-digit clave numérica

`build_clave` assembles it from the parts you know:

| Segment | Length | Notes |
|---|---|---|
| País | 3 | `506` |
| Día / Mes / Año | 2 / 2 / 2 | from `fecha` (YYYY-MM-DD) |
| Cédula del emisor | 12 | left-padded |
| Consecutivo | 20 | sucursal(3) + terminal(5) + tipo(2) + secuencial(10) |
| Situación | 1 | 1 normal · 2 contingencia · 3 sin internet |
| Código de seguridad | 8 | your system generates it |

`tipoComprobante` codes: `01` Factura · `02` Nota de Débito · `03` Nota de Crédito · `04` Tiquete · `08` Factura de Compra · `09` Factura de Exportación · `10` Recibo de Pago.

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 grand total (incl. IVA 13%) from `<TotalComprobante>` inside `<ResumenFactura>` of the signed XML (colones, CRC). If that element cannot be parsed from the base64 payload, the **amount** gate is skipped for that call (the tool allow-list still applies unconditionally); this is by design because the invoice is opaque signed XML we do not parse in full.

## Endpoints wrapped (per env)

Auth (Keycloak OAuth2 password grant, per request):
`https://idp.comprobanteselectronicos.go.cr/auth/realms/{rut-stag | rut}/protocol/openid-connect/token` (client_id `api-stag` / `api-prod`).

Reception API:

| `x-hacienda-mode` | Realm / client | Reception base | Submit | Query |
|---|---|---|---|---|
| `stag` (default) | `rut-stag` / `api-stag` | `…/recepcion-sandbox/v1` | `POST /recepcion` | `GET /recepcion/{clave}` |
| `prod` | `rut` / `api-prod` | `…/recepcion/v1` | same | same |

Hacienda HTTP responses are passed through: **202** received-for-processing · **200** status · **400** invalid · **401** bad/expired token · **403** forbidden · **404** clave not found · **429/5xx** transient (resend).

## Develop

```bash
node test/serve.js   # local server on :3245
node test/e2e.js     # protocol + build_clave + validation + policy asserts + LIVE probes against Hacienda
```

The e2e suite makes **real** calls to the Hacienda IdP (`idp.comprobanteselectronicos.go.cr`, realm `rut-stag`): a fake API user runs the full OAuth2 password grant and surfaces Hacienda's native **`{"error":"invalid_grant"}` 401** — the deepest live verification possible without a real onboarded ATV API user (we never sign, so we cannot mint a valid document). A fake Bearer against `recepcion-sandbox` surfaces the native gateway rejection (401/403).

## Safety

Pure stateless translation layer straight to the government Hacienda gateway. XAdES signing and the certificate stay merchant-side; the ATV API user/password travel per-request in headers, nothing is stored. [Privacy policy](https://inv-cr.wishpool.app/privacy).

## Sister servers

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

MIT licensed.