Costa Rica Invoices (Hacienda comprobante electronico v4.4)

Official3 toolsLive

by junter1989k-ai · JavaScript

Costa Rica Hacienda v4.4: AI agents submit and query electronic invoices, stateless BYO.

Topics

ai-agentclaudecosta-ricahaciendainvoicemcpmcp-servervatwishpool

Captured live from the server via tools/list.

submit_invoice

Submit an ALREADY-SIGNED Costa Rica electronic invoice (comprobante electronico v4.4) to the Ministerio de Hacienda reception gateway — the /recepcion call. You build the v4.4 XML (FacturaElectronica / TiqueteElectronico / NotaCredito etc.), sign it with YOUR Hacienda certificate (llave criptografica), and pass { clave, fecha, emisor, receptor?, comprobante_xml(base64 signed XML) }. This server does NOT sign and does NOT hold your certificate — it exchanges your ATV API user/password for an OAuth token and forwards the bytes untouched. Hacienda accepts the document for ASYNCHRONOUS processing: a successful call returns HTTP 202 with ind_estado "recibido"/"procesando" — you then poll query_invoice to get the final ind_estado "aceptado" (accepted) or "rechazado" (rejected). Required credential headers (set once in your MCP client, per-request, never stored): x-hacienda-username (your ATV API user) + x-hacienda-password (its password) — exchanged for a short-lived OAuth token at the Hacienda IdP. Optional header x-hacienda-mode: stag (default, sandbox, no fiscal effect) | prod (production, real fiscal effect). Optional owner-policy headers x-agentpay-max-amount / x-agentpay-approval-above / x-agentpay-allowed-tools.

Parameters6

clave	string	required	The 50-digit clave numerica of the comprobante (same clave embedded in the signed XML). Use build_clave to assemble it if needed.
fecha	string	required	Emission timestamp in ISO 8601 with Costa Rica offset, e.g. 2026-07-10T09:30:00-06:00 (must match the FechaEmision in the signed XML).
emisor	object	required	The issuer identification { tipoIdentificacion, numeroIdentificacion }.
receptor	object	optional	The receiver identification { tipoIdentificacion, numeroIdentificacion }. Optional — omit for tiquete electronico / consumidor final.
comprobante_xml	string	required	The FULL signed v4.4 comprobante XML, base64-encoded. You sign it with your Hacienda certificate merchant-side; this server forwards the bytes untouched.
callback_url	string	optional	Optional URL Hacienda will POST the final estado to (async). Omit to poll with query_invoice instead.

Raw schema

{
  "type": "object",
  "properties": {
    "clave": {
      "type": "string",
      "description": "The 50-digit clave numerica of the comprobante (same clave embedded in the signed XML). Use build_clave to assemble it if needed."
    },
    "fecha": {
      "type": "string",
      "description": "Emission timestamp in ISO 8601 with Costa Rica offset, e.g. 2026-07-10T09:30:00-06:00 (must match the FechaEmision in the signed XML)."
    },
    "emisor": {
      "type": "object",
      "description": "The issuer identification { tipoIdentificacion, numeroIdentificacion }.",
      "properties": {
        "tipoIdentificacion": {
          "type": "string",
          "description": "Identification type: 01 = fisica (cedula fisica), 02 = juridica, 03 = DIMEX, 04 = NITE."
        },
        "numeroIdentificacion": {
          "type": "string",
          "description": "The identification number digits (cedula / DIMEX / NITE), no dashes."
        }
      },
      "required": [
        "tipoIdentificacion",
        "numeroIdentificacion"
      ]
    },
    "receptor": {
      "type": "object",
      "description": "The receiver identification { tipoIdentificacion, numeroIdentificacion }. Optional — omit for tiquete electronico / consumidor final.",
      "properties": {
        "tipoIdentificacion": {
          "type": "string",
          "description": "Identification type: 01 = fisica (cedula fisica), 02 = juridica, 03 = DIMEX, 04 = NITE."
        },
        "numeroIdentificacion": {
          "type": "string",
          "description": "The identification number digits (cedula / DIMEX / NITE), no dashes."
        }
      }
    },
    "comprobante_xml": {
      "type": "string",
      "description": "The FULL signed v4.4 comprobante XML, base64-encoded. You sign it with your Hacienda certificate merchant-side; this server forwards the bytes untouched."
    },
    "callback_url": {
      "type": "string",
      "description": "Optional URL Hacienda will POST the final estado to (async). Omit to poll with query_invoice instead."
    }
  },
  "required": [
    "clave",
    "fecha",
    "emisor",
    "comprobante_xml"
  ]
}

query_invoice

Query the processing status of a previously submitted Costa Rica comprobante by its 50-digit clave — the GET /recepcion/{clave} call. Returns ind_estado: "recibido" (queued) / "procesando" (in process) / "aceptado" (ACCEPTED — fiscally valid, hand respuesta_xml to the buyer) / "rechazado" (REJECTED — read respuesta_xml for the reason, fix and resubmit) / "error". respuesta_xml (base64) is the Hacienda "Mensaje Hacienda" response document. Poll this after submit_invoice until ind_estado is aceptado or rechazado. Required credential headers (set once in your MCP client, per-request, never stored): x-hacienda-username (your ATV API user) + x-hacienda-password (its password) — exchanged for a short-lived OAuth token at the Hacienda IdP. Optional header x-hacienda-mode: stag (default, sandbox, no fiscal effect) | prod (production, real fiscal effect). Optional owner-policy headers x-agentpay-max-amount / x-agentpay-approval-above / x-agentpay-allowed-tools.

Parameters1

clave

string

required

The 50-digit clave numerica returned/used when you submitted the comprobante.

Raw schema

{
  "type": "object",
  "properties": {
    "clave": {
      "type": "string",
      "description": "The 50-digit clave numerica returned/used when you submitted the comprobante."
    }
  },
  "required": [
    "clave"
  ]
}

build_clave

Assemble a Costa Rica 50-digit clave numerica from its parts — a PURE LOCAL helper (no network, no credentials, no fiscal effect). Structure: 506 + DD + MM + YY + cedula(12) + consecutivo(20) + situacion(1) + codigoSeguridad(8). Provide either the ready-made 20-digit consecutivo, or its parts (sucursal, terminal, tipoComprobante, numeroConsecutivo). tipoComprobante codes: 01=Factura, 02=Nota Debito, 03=Nota Credito, 04=Tiquete, 08=Factura de Compra, 09=Factura de Exportacion, 10=Recibo de Pago. situacion: 1=normal, 2=contingencia, 3=sin internet. Pass codigoSeguridad (8 digits) for a reproducible clave, or omit to auto-generate one. Returns the clave plus a labelled breakdown. Does NOT sign or submit.

Parameters12

fecha	string	optional	Emission date "YYYY-MM-DD" (e.g. 2026-07-10). Or pass day/month/year instead.
day	string	optional	Day DD (used only if fecha is omitted).
month	string	optional	Month MM (used only if fecha is omitted).
year	string	optional	Year — last two digits YY (used only if fecha is omitted).
cedula	string	required	Emisor numero de identificacion (up to 12 digits; left-padded to 12 in the clave).
consecutivo	string	optional	The full 20-digit consecutivo (sucursal 3 + terminal 5 + tipo 2 + secuencial 10). Provide this OR the four parts below.
sucursal	string	optional	Branch code (3 digits, casa matriz = 001). Used with terminal/tipoComprobante/numeroConsecutivo.
terminal	string	optional	Terminal / punto de venta (5 digits, e.g. 00001).
tipoComprobante	string	optional	Document type (2 digits): 01 FE, 02 ND, 03 NC, 04 TE, 08 FEC, 09 FEE, 10 REP.
numeroConsecutivo	string	optional	Sequential document number (up to 10 digits, left-padded).
situacion	string	optional	Comprobante situation: 1 normal (default), 2 contingencia, 3 sin internet.
codigoSeguridad	string	optional	Security code (8 digits). Omit to auto-generate; pass your own for a reproducible clave.

Raw schema

{
  "type": "object",
  "properties": {
    "fecha": {
      "type": "string",
      "description": "Emission date \"YYYY-MM-DD\" (e.g. 2026-07-10). Or pass day/month/year instead."
    },
    "day": {
      "type": "string",
      "description": "Day DD (used only if fecha is omitted)."
    },
    "month": {
      "type": "string",
      "description": "Month MM (used only if fecha is omitted)."
    },
    "year": {
      "type": "string",
      "description": "Year — last two digits YY (used only if fecha is omitted)."
    },
    "cedula": {
      "type": "string",
      "description": "Emisor numero de identificacion (up to 12 digits; left-padded to 12 in the clave)."
    },
    "consecutivo": {
      "type": "string",
      "description": "The full 20-digit consecutivo (sucursal 3 + terminal 5 + tipo 2 + secuencial 10). Provide this OR the four parts below."
    },
    "sucursal": {
      "type": "string",
      "description": "Branch code (3 digits, casa matriz = 001). Used with terminal/tipoComprobante/numeroConsecutivo."
    },
    "terminal": {
      "type": "string",
      "description": "Terminal / punto de venta (5 digits, e.g. 00001)."
    },
    "tipoComprobante": {
      "type": "string",
      "description": "Document type (2 digits): 01 FE, 02 ND, 03 NC, 04 TE, 08 FEC, 09 FEE, 10 REP."
    },
    "numeroConsecutivo": {
      "type": "string",
      "description": "Sequential document number (up to 10 digits, left-padded)."
    },
    "situacion": {
      "type": "string",
      "description": "Comprobante situation: 1 normal (default), 2 contingencia, 3 sin internet."
    },
    "codigoSeguridad": {
      "type": "string",
      "description": "Security code (8 digits). Omit to auto-generate; pass your own for a reproducible clave."
    }
  },
  "required": [
    "cedula"
  ]
}

README.md6 KBView on GitHub

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.

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.

Install

Tools (3)

submit_invoicequery_invoicebuild_clave

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://inv-cr.wishpool.app/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "costa-rica-invoice-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://inv-cr.wishpool.app/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.