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

Emite, rastrea y diagnostica documentos electrónicos de Colombia directamente desde cualquier agente de IA.

El MCP de Alanube expone el catálogo de facturación electrónica de Colombia como un servidor Model Context Protocol. Al conectarlo a Claude, Cursor, Continue o tu propio agente, tu aplicación puede emitir Facturas Electrónicas de Venta, Notas Crédito y el resto del catálogo disponible desde lenguaje natural, con las mismas garantías de cumplimiento que ofrece la API REST.

📘

En resumen

Un solo endpoint con 25 herramientas listas para usar y las mismas garantías DIAN que la API REST de Alanube para Colombia. 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 la API de Colombia y le agrega los controles que un agente autónomo realmente necesita: ejemplos listos, validación previa, consulta de estado para el caso asíncrono y diagnóstico de errores.

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/>Colombia]
    C --> D[DIAN]
    D -.-> C
    C -.-> B
    B -.-> A

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

Catálogo de herramientas

Veinticinco herramientas organizadas en cuatro capas. Para la mayoría de los casos basta con la capa operativa; el resto está disponible cuando necesitas control fino.

📘

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.

📨 Emisión y seguimiento

El corazón operativo: la emisión es síncrona por defecto, la DIAN responde con el resultado legal en la misma llamada, así que en el caso típico no necesitas un orquestador ni hacer polling. La herramienta de status solo entra en juego cuando hay caída al modo asíncrono.

📬 Eventos RADIAN

Para registrar lo que pasa con una factura después de emitida: acuse de recibo, recibo del bien o servicio, aceptación o reclamo.

🛡️ Confiabilidad

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

Cobertura de tipos de documento

Cada tipo de documento tiene su propio par de herramientas de emisión y consulta de estado:

Antes de emitir cada tipo de documento

• Documento Soporte y su nota de ajuste: la empresa debe estar habilitada para factura electrónica y tener a Alanube como proveedor de documento soporte en el portal de habilitación de la DIAN.
• Documento Equivalente POS y su nota de ajuste: la empresa debe estar habilitada para POS, con su set de pruebas aprobado y una resolución de numeración POS asociada.
• Eventos RADIAN: solo aplican a facturas a crédito. Si vas a emitir una factura para probar eventos, emítela con forma de pago a crédito.

¿Cómo empezar?

1. Configura tu entorno

Necesitas tu token de sandbox, el mismo con el que llamas a la API sandbox de Colombia. El MCP lo recibe en el header Authorization: Bearer <token>. Ten en cuenta que es un token distinto del que usan República Dominicana, Costa Rica y Panamá.

🚧

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_CO_TOKEN} para que Claude Code la lea del entorno y el token no quede escrito en su configuración.

export ALANUBE_CO_TOKEN="<TU_TOKEN_SANDBOX>"

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

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

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

{
  "mcpServers": {
    "alanube-co": {
      "url": "https://sandbox-mcp.alanube.co/mcp/co",
      "headers": { "Authorization": "Bearer ${env:ALANUBE_CO_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-co-token",
      "description": "Token sandbox de la API de Colombia",
      "password": true
    }
  ],
  "servers": {
    "alanube-co": {
      "type": "http",
      "url": "https://sandbox-mcp.alanube.co/mcp/co",
      "headers": { "Authorization": "Bearer ${input:alanube-co-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-co": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://sandbox-mcp.alanube.co/mcp/co",
        "--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. Emite tu primer documento

Pídelo al agente en lenguaje natural:

Emite una Factura Electrónica de Venta por una camisa negra talla L a COP$50.000 + IVA 19%.

El agente llama a issue_co_invoice, valida el payload, lo envía y devuelve:

{
  "ok": true,
  "isFinal": true,
  "legalStatus": "ACCEPTED",
  "cufe": "a1b2c3d4e5f6…",
  "fullNumber": "SETP990000001",
  "governmentResponse": { "code": "00", "message": "OK" },
  "files": { "xml": "…", "pdf": "…" },
  "qrCodeContent": "…"
}

Eso es todo: validar, emitir, esperar la confirmación de DIAN y dejar los archivos disponibles en la misma respuesta.

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/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

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

const result = await client.callTool({
  name: "issue_co_invoice",
  arguments: {
    payload: {
      /* factura completa; generate_co_request_example te da una de partida */
    }
  }
});

Tres flujos que conviene conocer

Flujo 1 — Emisión síncrona (caso típico)

DIAN responde con el resultado legal final en la misma llamada y la API te lo entrega sin necesidad de hacer polling. Las herramientas de emisión devuelven isFinal: true, legalStatus, el identificador del documento (cufe, cude o cuds) y files directamente en la primera respuesta. No necesitas un orquestador ni una herramienta de status para el caso típico.

Flujo 2 — Caída a asíncrono (intermitencia de DIAN)

Cuando DIAN está intermitente al momento del POST, Alanube encola el documento para reintento. La respuesta sigue siendo 2xx, pero legalStatus no viene y status queda en REGISTERED o WAITING_RESPONSE. La herramienta devuelve isFinal: false, pendingLegalStatus: true y un trackingReference (con el flow del tipo de documento, por ejemplo "co.invoice"). Tu aplicación debe consultar después la herramienta de status de ese tipo de documento, por ejemplo get_co_invoice_status, para conocer el resultado legal.

Flujo 3 — Diagnosticar y reintentar

Cuando DIAN rechaza un documento o lo acepta con observaciones, la respuesta de la emisión ya trae en governmentDiagnosis la explicación de cada regla que reportó la DIAN. Para analizar un error en cualquier otro momento, pásale el governmentResponse a diagnose_co_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

• 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 la cobertura COL. 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. Con validate_co_payload puedes revisar un borrador sin emitirlo.
• Archivos en la misma respuesta del caso típico: en la emisión síncrona, los files (xml, pdf), el identificador del documento y qrCodeContent vienen directamente en la respuesta. No hace falta una segunda llamada para obtenerlos.
• Higiene de respuestas: el MCP devuelve URLs y metadatos estructurados. La única excepción es list_co_invoice_events con xmlBase64: true, que devuelve el documento de respuesta de la DIAN codificado en base64.
• Fidelidad con DIAN: los estados del ciclo de vida, governmentResponse y legalStatus llegan sin modificar.
• Texto de terceros identificado: los mensajes de la DIAN 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

📘

Ambos caminos llegan al mismo lugar

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

Empieza

• 📖 Referencia REST: developer.alanube.co/v1.0-COL
• 🔑 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/co
• 🌎 MCP en otros países: República Dominicana, Costa Rica y Panamá
• 💬 Soporte: [email protected]

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