Las 4 herramientas del servidor MCP de Colombia: referencia técnica

El servidor MCP de infraestructura fiscal para Colombia, operado por Alanube, expone cuatro herramientas que cubren el ciclo completo de la facturación electrónica ante la DIAN: emisión de facturas, emisión de notas crédito, diagnóstico de rechazos y validación de NITs. Este artículo es la referencia técnica de cada una — parámetros, respuesta y cuándo usarla.

Para instrucciones de conexión del servidor, ver Cómo conectar un agente de IA a la DIAN con MCP.

El servidor MCP de Colombia y sus cuatro herramientas

Un servidor MCP expone herramientas con nombre, descripción y esquema tipado que el agente descubre automáticamente al conectarse. El servidor de Colombia organiza sus cuatro herramientas en dos capas: operaciones de emisión (issue_co_invoice, issue_co_credit_note) y operaciones de soporte (diagnose_co_api_error, validate_co_nit). Las cuatro son independientes entre sí pero se encadenan naturalmente en el flujo de facturación.

issue_co_invoice — emitir una factura electrónica ante la DIAN

Es la herramienta principal del servidor. Toma los datos del negocio en formato JSON, construye el XML UBL 2.1, aplica la firma XAdES-BES, transmite al hub de la DIAN y retorna el comprobante con el CUFE. El desarrollador no gestiona ninguna de esas capas directamente.

Parámetros principales

{
  "issuerNit": "900123456",        // NIT del emisor (sin dígito de verificación)
  "receiverNit": "800987654",       // NIT del receptor
  "receiverName": "Cliente S.A.S.",
  "invoiceDate": "2025-08-01",      // Formato YYYY-MM-DD
  "currency": "COP",
  "items": [
    {
      "description": "Servicio de desarrollo",
      "quantity": 1,
      "unitPrice": 5000000,
      "taxRate": 19           // IVA en porcentaje
    }
  ]
}

Respuesta exitosa

{
  "ok": true,
  "cufe": "abc123...def456",        // Código Único de Factura Electrónica
  "invoiceNumber": "FE-0000123",
  "status": "ACCEPTED",             // ACCEPTED | ACCEPTED_WITH_OBSERVATIONS
  "xmlUrl": "https://...",          // XML firmado
  "pdfUrl": "https://..."           // Representación gráfica
}

Cuándo usarla

Cualquier flujo que genere una nueva obligación fiscal: venta de producto, prestación de servicio, exportación. No usar para revertir o corregir documentos previos — para eso existe issue_co_credit_note. Si la DIAN rechaza el documento, la respuesta incluye el código de error; pasarlo a diagnose_co_api_error para obtener la causa y la corrección.

issue_co_credit_note — emitir una nota crédito electrónica

Emite una nota crédito vinculada a una factura previa. Sigue el mismo flujo que issue_co_invoice — firma XAdES-BES, transmisión DIAN, CUFE — pero requiere el CUFE de la factura original como referencia. La DIAN valida que la factura referenciada exista y que el monto de la nota crédito no supere el saldo pendiente.

Parámetros principales

{
  "issuerNit": "900123456",
  "originalInvoiceCufe": "abc123...def456",  // CUFE de la factura a corregir
  "correctionCode": "1",             // 1 = descuento, 2 = anulación, 3 = corrección
  "correctionReason": "Precio incorrecto en la factura original",
  "items": [
    {
      "description": "Ajuste por diferencia de precio",
      "quantity": 1,
      "unitPrice": 500000,
      "taxRate": 19
    }
  ]
}

Relación con la factura original

El CUFE de la factura original es obligatorio y debe corresponder a un documento en estado ACCEPTED en la DIAN. Si la factura original fue emitida en Sandbox, la nota crédito también debe emitirse en Sandbox — los entornos no se cruzan. El correctionCode define el tipo de ajuste y afecta cómo la DIAN contabiliza el documento en el sistema del emisor.

diagnose_co_api_error — diagnosticar un rechazo DIAN (ver guía completa: Cómo diagnosticar rechazos de la DIAN con un agente de IA)

Toma el código de error o el mensaje de rechazo devuelto por la DIAN y retorna la causa probable en lenguaje natural, el campo responsable del error y la acción correctiva recomendada. Está diseñada para llamarse automáticamente cuando issue_co_invoice o issue_co_credit_note retornan ok: false.

Parámetros y respuesta

// Llamada
{
  "errorCode": "FAD23",
  "errorMessage": "El NIT del receptor no está registrado en el RUT",
  "documentType": "invoice"
}

// Respuesta
{
  "category": "datos_receptor",
  "likelyCause": "El NIT 800987654 no existe en el RUT o está inactivo.",
  "affectedField": "receiverNit",
  "suggestedAction": "Validar el NIT con validate_co_nit antes de emitir.",
  "dianReference": "Anexo Técnico §4.2.1"
}

Cuándo llamarla automáticamente

El patrón recomendado es encadenarla en el mismo flujo: si issue_co_invoice retorna ok: false, el agente llama diagnose_co_api_error con el código de error y presenta la causa y la corrección al usuario sin requerir intervención del desarrollador. Esto elimina el ciclo manual de buscar el código en el Anexo Técnico de la DIAN.

validate_co_nit — validar un NIT en el RUT de la DIAN

Consulta el Registro Único Tributario de la DIAN y retorna el estado del NIT: si está activo, la razón social registrada, el régimen tributario y si está habilitado como emisor de factura electrónica. No requiere datos de factura — es una consulta puntual.

Parámetros y respuesta

// Llamada
{ "nit": "800987654" }

// Respuesta
{
  "valid": true,
  "legalName": "Empresa Receptora S.A.S.",
  "taxRegime": "RESPONSABLE_IVA",
  "electronicInvoicingEnabled": true,
  "status": "ACTIVE"
}

Cuándo usarla en el flujo de facturación

Usarla antes de issue_co_invoice cuando el receptor es nuevo o cuando el NIT viene de una fuente externa (formulario de cliente, importación de CRM). Un NIT inválido o inactivo es una de las causas más frecuentes de rechazo DIAN — validarlo antes de emitir evita el ciclo de corrección. También es la primera acción recomendada cuando diagnose_co_api_error reporta un error en datos_receptor.

Cómo encadenan las cuatro herramientas en un flujo completo

En un flujo de facturación bien diseñado, las cuatro herramientas se llaman en secuencia según el estado del proceso, no de forma aislada:

1. validate_co_nit(receiverNit)
      → Si valid: false → mostrar error al usuario, no continuar
      → Si valid: true → continuar

2. issue_co_invoice(datos_factura)
      → Si ok: true → almacenar CUFE, entregar comprobante
      → Si ok: false → continuar a paso 3

3. diagnose_co_api_error(errorCode, errorMessage)
      → Presentar causa y corrección al usuario
      → Si affectedField == "receiverNit" → volver a paso 1
      → Si corrección implica datos de factura → corregir y volver a paso 2

4. issue_co_credit_note(originalCufe, ...)
      → Solo si hay que corregir una factura ya aceptada

Este patrón permite que el agente maneje el ciclo completo de forma autónoma: valida, emite, diagnostica y corrige sin requerir intervención del desarrollador en cada paso.

Para los escenarios de prueba recomendados de este flujo en Sandbox, ver MCP DIAN en Sandbox: qué probar antes de producción.

Preguntas frecuentes

¿Cuál es la diferencia entre issue_co_invoice e issue_co_credit_note?

issue_co_invoice crea un nuevo documento fiscal independiente. issue_co_credit_note crea un documento que referencia y modifica uno existente — requiere el CUFE de la factura original y no puede superar su valor. Ambas herramientas siguen el mismo flujo de firma y transmisión DIAN, pero generan tipos de documento distintos en el sistema fiscal.

¿Cómo sé qué herramientas están disponibles en mi cliente MCP?

Cualquier cliente MCP puede consultar las herramientas disponibles en el servidor enviando una solicitud tools/list. En Claude Desktop o Cursor se puede preguntar directamente: '¿Qué herramientas tienes disponibles?' — el agente lista todas las herramientas cargadas desde el servidor con su descripción.

¿Qué diferencia hay entre validate_co_nit y consultar directamente el RUT de la DIAN?

La consulta directa al RUT de la DIAN devuelve HTML que requiere parsing manual. validate_co_nit retorna un JSON estructurado con los campos que el flujo de facturación necesita — estado, régimen, habilitación electrónica — sin ningún procesamiento adicional. También normaliza el NIT antes de consultar, eliminando errores por formato incorrecto.

¿Es posible invocar las cuatro herramientas en una sola conversación con el agente?

Sí. El agente puede encadenar múltiples llamadas a herramientas dentro de la misma conversación. Un prompt del tipo 'Valida el NIT 800987654 y si está activo emite una factura por servicio de consultoría por 2.000.000 COP' dispara validate_co_nit y, si el resultado es válido, issue_co_invoice en la misma sesión, sin pasos intermedios.