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

Emite, rastrea y diagnostica comprobantes fiscales electrónicos de República Dominicana (e-CF) directamente desde cualquier agente de IA.

El MCP de Alanube expone el catálogo completo de e-CF de República Dominicana como un servidor Model Context Protocol. Al conectarlo a Claude, Cursor, Continue o tu propio agente, tu aplicación puede emitir Facturas de Consumo, Crédito Fiscal, Notas de Crédito y Débito, y el resto del catálogo de la DGII desde lenguaje natural, con las mismas garantías de cumplimiento que ofrece la API REST.

📘

En resumen

Un solo endpoint con 30 herramientas listas para usar y las mismas garantías DGII que v1.0-DOM.

¿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 de 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-DOM y le agrega los controles que un agente autónomo realmente necesita: ejemplos listos, validación previa, consulta de estado acotada y diagnóstico de errores.

Arquitectura

flowchart LR
    A[Agente / IDE<br/>Claude · Cursor · cliente propio] -->|MCP · JSON-RPC| B[Servidor MCP<br/>de Alanube]
    B -->|HTTPS| C[Alanube REST<br/>v1.0-DOM]
    C --> D[DGII]
    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, TO_SEND, WAITING_RESPONSE, TO_NOTIFY, FINISHED) y los resultados legales (ACCEPTED, ACCEPTED_WITH_OBSERVATIONS, REJECTED) llegan exactamente como los devuelve la DGII, sin transformaciones.

Catálogo de herramientas

Treinta herramientas organizadas en tres capas. Para la mayoría de los casos basta con conocer la capa de orquestación; el resto está disponible cuando necesitas control fino.

🧭 Descubrimiento y aprendizaje

Para agentes y personas que están explorando el catálogo antes de escribir código.

📨 Emisión, seguimiento y archivos

El corazón operativo: un orquestador y diez pares de tools, uno por cada tipo de documento.

🛡️ Confiabilidad

Para agentes que necesitan fallar de forma controlada y poder explicar el porqué.

Cobertura de tipos de documento

Cada tipo de e-CF tiene su propio par de herramientas de emisión y consulta de estado:

¿Cómo empezar?

1. Configura tu entorno

Edita el archivo de configuración MCP según tu herramienta y sistema operativo. La ubicación cambia según la herramienta y el sistema operativo:

• Claude Desktop
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
• Claude Code (CLI): ~/.config/claude/mcp.json (Linux/macOS) o %APPDATA%\claude\mcp.json (Windows)

Contenido:

{
  "mcpServers": {
    "alanube": {
      "url": "https://sandbox-mcp.alanube.co/mcp/rd",
      "headers": {
        "Authorization": "Bearer <TU_TOKEN_SANDBOX>"
      }
    }
  }
}

👍

Otras herramientas

Cursor, Continue y cualquier herramienta compatible con MCP usan la misma URL más el header de autenticación. Sigue la documentación de MCP de tu herramienta.

2. Emite tu primer documento

Pídelo al agente en lenguaje natural:

Emite una Factura de Consumo (32) por una camisa negra talla L a DOP$1.000 + ITBIS 18%.

El agente llama a issue_and_track_rd_document con documentTypeCode: "32", valida el payload, lo envía y devuelve:

{
  "ok": true,
  "documentTypeCode": "32",
  "flowMode": "sync",
  "finalLegalOutcomeReached": true,
  "legalStatus": "ACCEPTED",
  "documentNumber": "E320000000005",
  "trackingReference": { "flow": "rd.consumer-invoice-32", "documentId": "..." },
  "assetUrls": { "xml": "...", "pdf": "...", "resumeXml": "..." }
}

Eso es todo: validar, emitir, esperar la confirmación de DGII y dejar los archivos listos para descargar.

3. 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";

const result = await client.callTool({
  name: "issue_and_track_rd_document",
  arguments: {
    documentTypeCode: "32",
    validateFirst: true,
    waitForFinalStatus: true,
    downloadAssets: true,
    assetTypes: ["xml", "pdf"],
    payload: {
      idDoc: { encf: "E320000000005", paymentType: 1 },
      sender: { rnc: "133109124", companyName: "Mi compañía" /* ... */ },
      totals: { totalTaxedAmount: 1000, itbis1Total: 180, totalAmount: 1180 },
      itemDetails: [{
        lineNumber: 1, itemName: "Camisa negra talla L",
        billingIndicator: 1, quantityItem: 1,
        unitPriceItem: 1000, itemAmount: 1000
      }]
    }
  }
});

Tres flujos que conviene conocer

Flujo 1 — Emisión síncrona (E32 por debajo de DOP$250.000)

Cuando emites una Factura de Consumo Electrónica (32) por un total menor a DOP$250.000, DGII responde con el resultado legal final en la misma llamada y la API te lo entrega sin necesidad de hacer polling. issue_and_track_rd_document devuelve flowMode: "sync" y finalLegalOutcomeReached: true en la primera respuesta.

Flujo 2 — Emisión asíncrona (E32 desde DOP$250.000, otros documentos, o caída a asíncrono por intermitencia de DGII)

Si la E32 tiene un total igual o mayor a DOP$250.000, o si emites cualquier otro tipo de documento (31, 33, 34, 41, 43, 44, 45, 46, 47), DGII procesa la emisión de forma asíncrona. La primera respuesta trae un estado interno del ciclo de vida (REGISTERED, WAITING_RESPONSE, …) y un trackingReference. Si activas waitForFinalStatus: true, el orquestador consulta el estado de forma periódica (con límites configurables vía maxStatusChecks y statusCheckIntervalMs) hasta que DGII confirma o se agota el presupuesto, lo que ocurra primero. El estado siempre se devuelve, así que tu aplicación puede retomar el seguimiento después.

Una E32 por debajo del umbral también puede caer al flujo asíncrono cuando DGII no responde a tiempo: la API encola el documento y la respuesta pasa automáticamente al formato del flujo asíncrono. No necesitas lógica adicional del lado del integrador, el mismo trackingReference sirve.

Flujo 3 — Diagnosticar y reintentar

Cuando DGII rechaza un documento, pásale el governmentResponse a diagnose_rd_api_error. Recibes una explicación estructurada de la causa probable y la acción correctiva. Es la herramienta ideal para un agente que necesita corregir su propio payload y volver a intentar.

Garantías que te damos

• Catálogo controlado: solo se permiten operaciones que ya están en v1.0-DOM. No hay forma de llamar accidentalmente a endpoints no compatibles.
• Validación previa con esquema: cualquier emisión puede activar validateFirst: true para que el agente se detenga antes de enviar un documento inválido.
• Consulta de estado con límites: el polling tiene topes estrictos (por defecto: 12 consultas cada 2 segundos) para evitar ciclos sin control.
• Higiene de archivos: los archivos se entregan por URL firmada; el MCP nunca incluye archivos grandes en el contexto del agente.
• Fidelidad con DGII: los estados del ciclo de vida, governmentResponseCode y legalStatus llegan sin modificar.

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

📘

Ambos caminos llegan al mismo lugar

El MCP y la API REST producen los mismos resultados frente a DGII. Elegir uno no te impide usar el otro en paralelo.

Estado y próximos pasos

• ✅ Disponible para RD v1.0-DOM: los 10 tipos de e-CF
• 🚧 Próximamente: flujos multi-empresa, integración por webhook para cargas pesadas en producción, más formatos de archivos descargables
• 🔜 Otros mercados: Colombia, Panamá, Perú; misma forma del MCP, catálogos específicos por país

Empieza

• 📖 Referencia REST: developer.alanube.co/v1.0-DOM
• 🔑 Token de sandbox: solicítalo desde el dashboard de tu cuenta de Alanube o desde la landing del MCP de Alanube .
• 🛠️ Endpoint MCP: https://sandbox-mcp.alanube.co/mcp/rd
• 💬 Soporte: [email protected]

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