¿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 11 herramientas listas para usar y las mismas garantías DIAN que la API REST de Alanube para Colombia.

¿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 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 · cliente 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 Alanube, 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, sin transformaciones.

Catálogo de herramientas

Once herramientas organizadas en tres capas. Para la mayoría de los casos basta con la capa operativa; 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.

Herramienta	Qué hace
`discover_co_endpoint`	Toma una descripción en lenguaje natural y devuelve la referencia exacta del endpoint
`explain_co_endpoint`	Detalle completo del endpoint: request, response y campos
`explain_co_field`	Explica un campo específico, incluso si está anidado; requiere `endpointRef` explícito
`generate_co_request_example`	Genera un payload de ejemplo listo para usar

📨 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.

Herramienta	Qué hace
`issue_co_invoice`	Emite una Factura Electrónica de Venta. En el caso típico devuelve `cufe`, `legalStatus` y `files` en la misma respuesta; si DIAN está intermitente devuelve un `trackingReference` para consultar después
`get_co_invoice_status`	Consulta el resultado final en DIAN para una factura que quedó en modo asíncrono
`issue_co_credit_note`	Emite una Nota Crédito Electrónica. Sigue el mismo patrón que la factura, pero devuelve `cude` en lugar de `cufe`
`get_co_credit_note_status`	Consulta el resultado final en DIAN para una nota crédito que quedó en modo asíncrono
`create_co_sandbox_company`	Crea una empresa emisora en el ambiente de pruebas

🛡️ Confiabilidad

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

Herramienta	Qué hace
`validate_co_payload`	Valida el payload contra el esquema antes de emitir
`diagnose_co_api_error`	Da las causas probables cuando una llamada falla o DIAN rechaza un documento

Cobertura de tipos de documento

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

Documento	Identificador único	Herramienta de emisión	Herramienta de status
Factura Electrónica de Venta	`cufe`	`issue_co_invoice`	`get_co_invoice_status`
Nota Crédito Electrónica	`cude`	`issue_co_credit_note`	`get_co_credit_note_status`

¿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/co",
      "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 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";

const result = await client.callTool({
  name: "issue_co_invoice",
  arguments: {
    payload: {
      numberingRange: { prefix: "SETP", resolutionNumber: "18760000001" },
      customer: {
        identification: { type: "13", number: "1234567890" },
        name: "Juan Pérez",
        legalOrganizationType: "person"
      },
      items: [{
        code: "CAM-001",
        description: "Camisa negra talla L",
        quantity: 1,
        price: 50000,
        taxes: [{ type: "01", rate: 19 }]
      }],
      paymentForm: { type: "1", method: "10" }
    }
  }
});

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. issue_co_invoice (o issue_co_credit_note) devuelve isFinal: true, legalStatus, cufe/cude 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 flow: "co.invoice" o "co.credit-note"). Tu aplicación debe consultar después get_co_invoice_status o get_co_credit_note_status para conocer el resultado legal.

Flujo 3 — Diagnosticar y reintentar

Cuando DIAN rechaza un documento, 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

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: cualquier emisión puede usar validate_co_payload para que el agente se detenga antes de enviar un documento inválido.
Archivos en la misma respuesta del caso típico: en la emisión síncrona, los files (xml, pdf), cufe/cude 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; nunca incluye archivos grandes en el contexto del agente.
Fidelidad con DIAN: los estados del ciclo de vida, governmentResponse y legalStatus llegan sin modificar.

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
Necesitas validar, emitir y diagnosticar desde una sola interfaz	Manejas tu propia máquina de estados

📘
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.

Estado y próximos pasos

✅ Disponible para COL V1: Factura Electrónica de Venta y Nota Crédito Electrónica
🚧 Próximamente: Nota Débito, mandatos electrónicos, descarga estandarizada de archivos firmados, flujos multi-empresa
🔜 Otros mercados: República Dominicana ya está disponible; Panamá y Perú están en preparación. Misma forma del MCP, catálogos específicos por país.

Empieza

🔑 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
💬 Soporte: [email protected]

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