# Costa Rica Invoice MCP

> A remote MCP server that lets any AI agent submit and query Costa Rica electronic invoices (comprobante electrónico / factura electrónica v4.4) through the Ministerio de Hacienda national gateway. It wraps the submission call only: XAdES signing and the Hacienda certificate stay merchant-side. Stateless, bring-your-own ATV API user, never stores anything.

- MCP endpoint (Streamable HTTP): https://inv-cr.wishpool.app/mcp
- Credentials headers: x-hacienda-username (your ATV API user, registered in ATV "Registro de Usuarios API") + x-hacienda-password (its password). Exchanged for a short-lived OAuth token via Keycloak password grant at the Hacienda IdP. Your certificate and private key never leave your side.
- Mode header: x-hacienda-mode: prod submits to production (realm rut, real fiscal effect); stag (default) = recepcion-sandbox (realm rut-stag, no fiscal effect).
- Design: this server ONLY forwards the Hacienda /recepcion submission call. You build + XAdES-sign the comprobante electrónico v4.4 XML with your Hacienda certificate, compute the 50-digit clave numérica, and pass { clave, fecha, emisor{tipoIdentificacion,numeroIdentificacion}, receptor?, comprobante_xml(base64 signed XML) }. We never sign and never store credentials.
- Asynchronous: Hacienda accepts the comprobante for processing (HTTP 202, ind_estado recibido), then you poll query_invoice until ind_estado is aceptado (fiscally valid) or rechazado (rejected — read respuesta_xml, fix, resubmit).
- Endpoints wrapped: idp.comprobanteselectronicos.go.cr/auth/realms/{rut-stag|rut}/protocol/openid-connect/token (OAuth), api.comprobanteselectronicos.go.cr/{recepcion-sandbox|recepcion}/v1/recepcion (POST submit + GET /{clave} query).

## Tools

- submit_invoice: Submit an already-signed comprobante electrónico v4.4 to Hacienda /recepcion — { clave, fecha, emisor, receptor?, comprobante_xml(base64 signed XML) } in, HTTP 202 with ind_estado recibido/procesando out (asynchronous). Signing stays merchant-side.
- query_invoice: Poll GET /recepcion/{clave} — returns ind_estado aceptado / rechazado / procesando / recibido / error plus respuesta_xml (the Mensaje Hacienda, base64).
- build_clave: PURE LOCAL helper (no network, no credentials) — assemble the 50-digit clave numérica: 506 + DD + MM + YY + cédula(12) + consecutivo(20: sucursal 3 + terminal 5 + tipo 2 + secuencial 10) + situación(1) + códigoSeguridad(8). tipoComprobante: 01 Factura, 02 Nota Débito, 03 Nota Crédito, 04 Tiquete, 08 Factura de Compra, 09 Factura de Exportación, 10 Recibo de Pago.
- Owner policy guardrails: x-agentpay-max-amount (hard cap on grand total in CRC colones, read from TotalComprobante incl. IVA 13% when present), x-agentpay-approval-above (returns an unsubmitted draft for human review), x-agentpay-allowed-tools (tool allow-list) — set by the human owner in the MCP client config; the agent cannot relax them.

## Safety

Stateless translation layer that forwards the Hacienda /recepcion submission call only. XAdES signing and the Hacienda certificate stay merchant-side; the ATV API user and password travel per-request in headers and are never stored. This server never stores credentials, invoices, or customer data. Privacy policy: https://inv-cr.wishpool.app/privacy

## Sister servers

Invoices: Saudi ZATCA https://inv-sa.wishpool.app/mcp, Mexico CFDI 4.0 https://inv-mx.wishpool.app/mcp, Poland KSeF https://inv-pl.wishpool.app/mcp, Chile DTE https://inv-cl.wishpool.app/mcp, Brazil NF-e https://inv-br.wishpool.app/mcp, Peru CPE https://inv-pe.wishpool.app/mcp, India GST e-invoicing https://inv-in.wishpool.app/mcp. Same stateless BYO pattern, local payments in 81 countries — full list: https://mcp.wishpool.app/llms.txt (Taiwan e-invoice 電子發票 lives in https://mcp.wishpool.app/mcp).