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

{
  "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

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.

Sister servers

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

MIT licensed.