Costa Rica Invoices (Hacienda comprobante electronico v4.4)
Server Details
Costa Rica Hacienda v4.4: AI agents submit and query electronic invoices, stateless BYO.
- Status
- Unhealthy
- Last Tested
- Transport
- Streamable HTTP
- URL
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.7/5 across 3 of 3 tools scored.
Each tool has a distinct role: build_clave constructs a clave locally, submit_invoice sends an already-signed XML to Hacienda, and query_invoice polls its processing status. There is no overlap in purpose.
All tool names follow a consistent verb_noun snake_case pattern (build_clave, query_invoice, submit_invoice), making it predictable for an agent.
Three tools is minimal but covers the core workflow of building a clave, submitting an invoice, and querying status. The scope is narrow, and each tool earns its place.
For the server's purpose (submitting comprobantes to Hacienda and checking acceptance), the tool surface is complete. Missing cancel or other operations, but those are outside the stated scope.
Available Tools
3 toolsbuild_claveARead-onlyInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| day | No | Day DD (used only if fecha is omitted). | |
| year | No | Year — last two digits YY (used only if fecha is omitted). | |
| fecha | No | Emission date "YYYY-MM-DD" (e.g. 2026-07-10). Or pass day/month/year instead. | |
| month | No | Month MM (used only if fecha is omitted). | |
| cedula | Yes | Emisor numero de identificacion (up to 12 digits; left-padded to 12 in the clave). | |
| sucursal | No | Branch code (3 digits, casa matriz = 001). Used with terminal/tipoComprobante/numeroConsecutivo. | |
| terminal | No | Terminal / punto de venta (5 digits, e.g. 00001). | |
| situacion | No | Comprobante situation: 1 normal (default), 2 contingencia, 3 sin internet. | |
| consecutivo | No | The full 20-digit consecutivo (sucursal 3 + terminal 5 + tipo 2 + secuencial 10). Provide this OR the four parts below. | |
| codigoSeguridad | No | Security code (8 digits). Omit to auto-generate; pass your own for a reproducible clave. | |
| tipoComprobante | No | Document type (2 digits): 01 FE, 02 ND, 03 NC, 04 TE, 08 FEC, 09 FEE, 10 REP. | |
| numeroConsecutivo | No | Sequential document number (up to 10 digits, left-padded). |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true and destructiveHint=false; the description adds valuable context: no network calls, no credentials needed, no fiscal effect. It also discloses the behavior for codigoSeguridad (mandatory vs optional, auto-generation) and confirms the return format (clave plus breakdown). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose and then provides necessary detail. It is slightly long but every sentence earns its place. Minor redundancy (e.g., listing tipoComprobante codes twice: in text and in param description) but overall well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a local helper with no output schema, the description covers all necessary aspects: what inputs are needed, how they combine, optional vs required fields, and what is returned ('Returns the clave plus a labelled breakdown'). No gaps remain given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% but the description adds substantial meaning: it explains the overall structure (506 + DD + ...), provides code mappings for tipoComprobante and situacion, and clarifies the relationship between fecha and individual day/month/year fields. This goes far beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb ('Assemble') and specific resource ('Costa Rica 50-digit clave numerica'), immediately distinguishing it from siblings (query_invoice, submit_invoice) by declaring it a 'PURE LOCAL helper (no network, no credentials, no fiscal effect)'. This sets a precise scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to provide the full consecutivo versus its parts, and specifies that the tool does not sign or submit, implying it should be used before those operations. However, it lacks an explicit 'when not to use' statement or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
query_invoiceARead-onlyIdempotentInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| clave | Yes | The 50-digit clave numerica returned/used when you submitted the comprobante. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond annotations (readOnlyHint, idempotentHint, destructiveHint) by detailing the GET call mechanism, possible status values with meanings, polling necessity, credential headers, and mode options. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that packs essential information efficiently. Every sentence adds value, though it could be more structured (e.g., bullet points for statuses). Front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 1 required parameter and no output schema, the description fully explains return values (ind_estado with meanings, respuesta_xml), polling guidance, and all relevant headers. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a brief description of 'clave'. The description adds value by specifying it's a '50-digit clave numerica returned/used when you submitted the comprobante', clarifying its origin beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Query', the resource 'processing status of a previously submitted Costa Rica comprobante', and the required input '50-digit clave'. It distinguishes from siblings submit_invoice and build_clave by focusing on status checking after submission.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Poll this after submit_invoice until ind_estado is aceptado or rechazado', providing clear when-to-use context. It does not explicitly mention when not to use, but the polling context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
submit_invoiceAInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| clave | Yes | The 50-digit clave numerica of the comprobante (same clave embedded in the signed XML). Use build_clave to assemble it if needed. | |
| fecha | Yes | 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 | Yes | The issuer identification { tipoIdentificacion, numeroIdentificacion }. | |
| receptor | No | The receiver identification { tipoIdentificacion, numeroIdentificacion }. Optional — omit for tiquete electronico / consumidor final. | |
| callback_url | No | Optional URL Hacienda will POST the final estado to (async). Omit to poll with query_invoice instead. | |
| comprobante_xml | Yes | The FULL signed v4.4 comprobante XML, base64-encoded. You sign it with your Hacienda certificate merchant-side; this server forwards the bytes untouched. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the asynchronous nature (HTTP 202, ind_estado 'recibido'/'procesando'), the OAuth token exchange, and side effects (async processing with eventual acceptance/rejection). Annotations already indicate readOnlyHint=false, and the description adds rich behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with purpose, but it is somewhat long. However, every sentence adds necessary detail, and the length is justified by the complexity. Minor improvement could be trimming redundant phrases.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 params, 4 required, nested objects, async processing, no output schema), the description covers preconditions, workflow, response handling, headers, and error polling. It is complete and self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds significant meaning to each parameter, such as requiring clave to match embedded value, fecha to match FechaEmision, and explaining comprobante_xml is base64 signed XML. It also clarifies emisor and receptor objects and optional callback_url.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool submits an already-signed Costa Rica electronic invoice to the Hacienda gateway, specifying the version (v4.4) and endpoint (/recepcion). It distinguishes from siblings by mentioning polling query_invoice for status, and build_clave for clave generation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use (after building and signing XML) and conditions (must have certificate, credential headers). It specifies what the server does not do (does not sign, does not hold certificate) and provides alternatives (poll query_invoice).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!