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

The 50-digit clave numérica

build_clave assembles it from the parts you know:

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

... View full README on GitHub