¿Qué hace el MCP de infraestructura fiscal de Alanube?

Emite y rastrea facturas electrónicas de Costa Rica directamente desde cualquier agente de IA.

El MCP de Alanube expone el catálogo de facturación electrónica de Costa Rica como un servidor Model Context Protocol. Al conectarlo a Claude, Cursor, Continue o tu propio agente, tu aplicación puede crear su empresa emisora y emitir Facturas Electrónicas 4.4 desde lenguaje natural, con las mismas garantías de cumplimiento que ofrece la API REST.

📘
En resumen
Un solo endpoint con 6 herramientas listas para usar y las mismas garantías ante el Ministerio de Hacienda que v1.0-CRI. Disponible en el ambiente sandbox: los documentos que emitas no tienen validez fiscal.

¿Por qué MCP y por qué ahora?

REST funciona muy bien para backends. Pero cuando pones un modelo de lenguaje al frente de tu flujo de facturación —un copiloto, un bot que clasifica correos, un asistente de ERP— el modelo necesita un contrato que pueda interpretar: entradas tipadas, esquemas que se puedan descubrir y errores predecibles.

MCP es ese contrato: el protocolo abierto creado por Anthropic estandariza cómo los agentes descubren herramientas y las invocan, de modo que una vez tienes el endpoint configurado, Claude, Cursor o cualquier agente compatible lo entiende sin configuración extra — sin integraciones distintas por herramienta, sin manipular el prompt.

El MCP de Alanube envuelve v1.0-CRI y le agrega los controles que un agente autónomo realmente necesita: validación previa, un resultado que indica si el documento ya está resuelto y avisos claros cuando falta algo para emitir.

Arquitectura

flowchart LR
    A[Agente / IDE<br/>Claude · Cursor · agente propio] -->|MCP · JSON-RPC| B[Servidor MCP<br/>de Alanube]
    B -->|HTTPS| C[Alanube REST<br/>v1.0-CRI]
    C --> D[Hacienda]
    D -.-> C
    C -.-> B
    B -.-> A

El MCP no guarda estado y se autentica con tu mismo token de Alanube, por lo que los estados del ciclo de vida (REGISTERED, SENT, FINISHED, …) y los resultados legales (ACCEPTED, REJECTED, ERROR) llegan exactamente como los devuelve Hacienda. Cada respuesta suma además un resumen legible (resultSummary) y conserva la respuesta original de la API.

Catálogo de herramientas

Seis herramientas organizadas en dos capas.

📘
El detalle de cada herramienta viene en el propio MCP
Los parámetros, los campos obligatorios y la descripción completa de cada herramienta los entrega el servidor al conectarse (tools/list), y tu agente los lee de ahí. Para revisarlos por tu cuenta, usa MCP Inspector.

🧭 Descubrimiento y aprendizaje

Para agentes y personas que están explorando el catálogo antes de escribir código. Cubren toda la API de Costa Rica, incluidos los documentos que todavía no se emiten desde el MCP.

Herramienta	Qué hace
`discover_cr_endpoint`	Toma una descripción en lenguaje natural y devuelve la referencia exacta del endpoint
`explain_cr_endpoint`	Detalle completo del endpoint: request, response y campos
`explain_cr_field`	Explica un campo específico, incluso si está anidado; requiere `endpointRef` explícito

📨 Emisión y seguimiento

El corazón operativo: la emisión es asíncrona. La herramienta de emisión registra el documento y la de status te dice cuándo Hacienda ya resolvió.

Herramienta	Qué hace
`create_cr_sandbox_company`	Crea una empresa emisora en el ambiente de pruebas y te dice por separado si Hacienda aceptó el certificado y las credenciales ATV
`issue_cr_invoice`	Emite una Factura Electrónica 4.4. Devuelve un `trackingReference` con el id del documento y su clave numérica
`get_cr_invoice_status`	Consulta el resultado final en Hacienda usando el `trackingReference` y, si lo pides, devuelve las URLs de los archivos

Cobertura de tipos de documento

Documento	Identificador único	Herramienta de emisión	Herramienta de status
Factura Electrónica 4.4	clave numérica	`issue_cr_invoice`	`get_cr_invoice_status`

El tiquete electrónico, la factura de compra, la factura de exportación, las notas de crédito y débito, los recibos de pago y los mensajes de receptor se pueden explorar con discover_cr_endpoint y explain_cr_endpoint, pero todavía no tienen herramienta de emisión.

¿Cómo empezar?

1. Configura tu entorno

Necesitas tu token de sandbox, el mismo con el que llamas a la API sandbox de Costa Rica. El MCP lo recibe en el header Authorization: Bearer <token> y rechaza los tokens de producción. Si tu token de Alanube tiene acceso a varios países, te sirve para todos sus MCP.

🚧
No pegues el token en archivos versionados
Los ejemplos de abajo leen el token de una variable de entorno o lo piden al conectarse.

Registra el servidor según tu herramienta:

Claude Code (CLI): exporta el token y registra el servidor. Las comillas simples conservan la referencia ${ALANUBE_TOKEN} para que Claude Code la lea del entorno y el token no quede escrito en su configuración.

export ALANUBE_TOKEN="<TU_TOKEN_SANDBOX>"

claude mcp add-json --scope user alanube-cr \
  '{"type":"http","url":"https://sandbox-mcp.alanube.co/mcp/cr","headers":{"Authorization":"Bearer ${ALANUBE_TOKEN}"}}'

Para comprobar la conexión, usa claude mcp get alanube-cr o /mcp dentro de Claude Code.

Cursor: en ~/.cursor/mcp.json (global) o .cursor/mcp.json (por proyecto).

{
  "mcpServers": {
    "alanube-cr": {
      "url": "https://sandbox-mcp.alanube.co/mcp/cr",
      "headers": { "Authorization": "Bearer ${env:ALANUBE_TOKEN}" }
    }
  }
}

VS Code (GitHub Copilot): en .vscode/mcp.json. El bloque inputs hace que VS Code pida el token la primera vez y lo guarde de forma segura.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "alanube-token",
      "description": "Token sandbox de Alanube",
      "password": true
    }
  ],
  "servers": {
    "alanube-cr": {
      "type": "http",
      "url": "https://sandbox-mcp.alanube.co/mcp/cr",
      "headers": { "Authorization": "Bearer ${input:alanube-token}" }
    }
  }
}

Claude Desktop: su archivo de configuración (claude_desktop_config.json) solo arranca servidores locales, así que el servidor remoto se conecta a través de mcp-remote, que requiere Node.js.

{
  "mcpServers": {
    "alanube-cr": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://sandbox-mcp.alanube.co/mcp/cr",
        "--header", "Authorization:${ALANUBE_AUTH_HEADER}"
      ],
      "env": { "ALANUBE_AUTH_HEADER": "Bearer <TU_TOKEN_SANDBOX>" }
    }
  }
}

👍
Otras herramientas
Continue y cualquier herramienta compatible con MCP por HTTP (Streamable HTTP) usan la misma URL más el header de autenticación. Sigue la documentación de MCP de tu herramienta. El servidor no usa sesiones ni abre un stream SSE.

2. Crea tu empresa emisora

Pídele al agente que cree la empresa con create_cr_sandbox_company y revisa los dos estados que devuelve: certificateStatus (el certificado criptográfico) y credentialsStatus (las credenciales ATV). Costa Rica crea la empresa aunque rechace alguno de los dos, pero esa empresa no puede emitir hasta que lo corrijas.

3. Emite tu primer documento

Pídelo al agente en lenguaje natural:

Emite una Factura Electrónica por una consultoría de ₡100.000 + IVA 13%.

El agente arma el payload con ayuda de explain_cr_endpoint, llama a issue_cr_invoice, valida el payload, lo envía y devuelve:

{
  "ok": true,
  "accepted": true,
  "trackingReference": {
    "flow": "cr.invoice",
    "environment": "sandbox",
    "documentId": "...",
    "documentNumber": "50601..."
  }
}

Con ese trackingReference, el agente consulta el resultado con get_cr_invoice_status:

{
  "ok": true,
  "lifecycleState": "FINISHED",
  "isFinal": true,
  "legalStatus": "ACCEPTED",
  "documentKey": "50601...",
  "xml": "...",
  "xmlHacienda": "...",
  "pdf": "..."
}

Eso es todo: registrar, esperar la confirmación de Hacienda y dejar los archivos listos para descargar.

4. Ejemplo programático

Si prefieres código antes que chat, el MCP funciona contra el SDK estándar @modelcontextprotocol/sdk:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://sandbox-mcp.alanube.co/mcp/cr"),
  { requestInit: { headers: { Authorization: `Bearer ${process.env.ALANUBE_TOKEN}` } } }
);
const client = new Client({ name: "mi-aplicacion", version: "1.0.0" });
await client.connect(transport);

const issued = await client.callTool({
  name: "issue_cr_invoice",
  arguments: {
    payload: { /* Factura Electrónica 4.4 completa */ }
  }
});

const status = await client.callTool({
  name: "get_cr_invoice_status",
  arguments: {
    trackingReference: { /* el que devolvió issue_cr_invoice */ },
    documents: ["pdf", "xml"]
  }
});

Tres flujos que conviene conocer

Flujo 1 — Emisión asíncrona

issue_cr_invoice confirma que el documento quedó registrado y devuelve un trackingReference con la clave numérica, sin resultado legal: Hacienda todavía no se pronunció. El resultado se consulta con get_cr_invoice_status.

Flujo 2 — Saber cuándo el documento está resuelto

get_cr_invoice_status devuelve isFinal: true cuando el ciclo de vida termina:

FINISHED: el documento completó su ciclo y su legalStatus queda en ACCEPTED, REJECTED o ERROR.
FAILED: la firma se rechazó porque el certificado de la empresa está vencido o revocado.

Mientras legalStatus sea RECEIVED o IN_PROCESS, el documento sigue en curso. Un documento ACCEPTED cuyo ciclo de vida todavía no terminó tampoco es final: Hacienda ya lo aceptó, pero falta el paso de notificación. Ningún estado final cambia en una consulta posterior.

Flujo 3 — Pedir los archivos

La consulta de estado no trae URLs de archivos salvo que las pidas con documents (pdf, xml, xmlHacienda). El PDF solo existe cuando Hacienda ya aceptó el documento; si todavía no, la respuesta te lo avisa en warnings.

Garantías que te damos

Solo sandbox: las herramientas que crean empresas o emiten documentos operan únicamente contra el ambiente de pruebas.
Catálogo controlado: solo se permiten operaciones que ya están en v1.0-CRI. No hay forma de llamar accidentalmente a endpoints no compatibles.
Validación previa con esquema: toda emisión valida el payload antes de enviarlo y se detiene si encuentra errores.
Errores completos: cuando la API rechaza una llamada, recibes el código HTTP, el mensaje de la API y el cuerpo completo del error, con los códigos de cada problema.
Higiene de respuestas: el MCP devuelve URLs y metadatos estructurados; nunca incluye el contenido de los archivos en el contexto del agente.
Fidelidad con Hacienda: los estados del ciclo de vida, governmentResponse y legalStatus llegan sin modificar.
Texto de terceros identificado: los mensajes de Hacienda y de la API llegan marcados como datos externos y sin caracteres de control, para que el agente no los confunda con instrucciones.
Límites por llamada: hasta 256 KB por payload, 32 niveles de anidamiento y 10.000 nodos.

Cuándo usar el MCP y cuándo la API REST

Usa el MCP cuando…	Usa la API REST cuando…
Estás construyendo un copiloto, un agente o una interfaz de chat con LLM	Ya tienes un proceso de backend funcionando y no necesitas que un agente razone por ti
Quieres descubrir el esquema y usar herramientas que se explican solas	Estás optimizando para máximo rendimiento
Tu herramienta ya es compatible con MCP (Claude, Cursor, Continue, …)	Integras desde un lenguaje que aún no tiene SDK de MCP
Estás probando o preparando tu integración en sandbox	Necesitas un tipo de documento que el MCP todavía no emite, o vas a emitir en producción

📘
Ambos caminos llegan al mismo lugar
El MCP y la API REST producen los mismos resultados frente a Hacienda. Elegir uno no te impide usar el otro en paralelo.

Empieza

📖 Referencia REST: developer.alanube.co/v1.0-CRI
🔑 Token de sandbox: solicítalo desde el dashboard de tu cuenta de Alanube.
🛠️ Endpoint MCP: https://sandbox-mcp.alanube.co/mcp/cr
🌎 MCP en otros países: República Dominicana, Colombia y Panamá
💬 Soporte: [email protected]

Lanza copilotos de facturación en una tarde. Del cumplimiento nos encargamos nosotros.