🇨🇷 Costa Rica Invoice MCP live

AI agents can now submit a Costa Rica factura electrónica (comprobante electrónico v4.4) to the Ministerio de Hacienda. This remote MCP server forwards your already-signed v4.4 XML to the government Hacienda gateway — submit_invoice for the /recepcion call, query_invoice to poll the estado by clave, and build_clave to assemble the 50-digit clave numérica locally. It only wraps the submission call: XAdES signing and the Hacienda certificate stay merchant-side.

Connect

{
  "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"). Omit x-hacienda-mode to stay in the stag sandbox (realm rut-stag, no fiscal effect); prod = production. Your Hacienda certificate and private key never leave your side — this server never sees them.

How it works

• You sign, we forward: you build + XAdES-sign the v4.4 comprobante XML and compute its 50-digit clave; you pass { clave, fecha, emisor, receptor?, comprobante_xml(base64) }. This server exchanges your ATV API user/password for an OAuth token and relays it to Hacienda /recepcion — it never signs and never stores anything.
• Asynchronous: Hacienda returns HTTP 202 (recibido) and processes the comprobante; query_invoice polls /recepcion/{clave} until ind_estado is aceptado (fiscally valid) or rechazado.
• The clave numérica: 506 + DD + MM + YY + cédula(12) + consecutivo(20) + situación(1) + códigoSeguridad(8) = 50 digits. build_clave assembles it from those parts.
• Status enums: results carry ind_estado (recibido / procesando / aceptado / rechazado / error), respuesta_xml, and numbered next_steps.

Why it is safe

• Stateless: no database — your ATV API user and password travel per-request in headers and are never stored.
• Signing stays with you: the XAdES signature and the Hacienda certificate are applied and kept merchant-side; a compromise here cannot forge or alter your comprobantes.
• Owner policy guardrails: 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. The cap applies to the grand total (TotalComprobante, incl. IVA 13%, in colones CRC) when it can be read from the signed XML.

Weak-model friendly

Credentials taken from headers (never in the body); status enums spelled out in every tool description; Hacienda HTTP responses (202 recibido, 200 estado, 400/401/404 errors) passed through with numbered next_steps; every error teaches the fix (both credential headers, 50-digit clave, base64 not raw XML, mode). build_clave is a pure local helper with no fiscal effect.

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, same stateless pattern: mcp.wishpool.app (Taiwan e-invoice 電子發票 included).