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.
| 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
node test/e2e.js
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.