Cómo conectar un agente de IA a la DIAN con MCP: guía de configuración

Integrar un agente de inteligencia artificial con la DIAN no es un problema de código: es un problema de protocolo. La firma XAdES-BES, la construcción del XML UBL 2.1, la gestión del CUFE y el manejo de estados de validación son capas que históricamente han requerido semanas de integración antes de emitir la primera factura de prueba.

El Model Context Protocol cambia esa ecuación. Esta guía explica cómo funciona la arquitectura MCP aplicada a la DIAN, qué necesita el desarrollador antes de conectar y cómo configurar cualquier cliente compatible —Claude Desktop, Cursor, VS Code, Windsurf o Zed— para invocar herramientas fiscales colombianas desde un agente de IA.

MCP como capa de acceso a la infraestructura fiscal de la DIAN

El Model Context Protocol es un estándar abierto publicado por Anthropic en noviembre de 2024 que define cómo los agentes de IA descubren herramientas externas y las invocan mediante JSON-RPC. A diferencia de una API REST —diseñada para código determinista que construye payloads manualmente— un servidor MCP expone herramientas con nombre, descripción y esquema tipado que el agente puede descubrir y usar en tiempo de ejecución.

Aplicado a la DIAN, esto significa que el desarrollador no necesita implementar la capa de firma digital, el parsing del XML UBL 2.1 ni el ciclo de vida del documento. El servidor MCP encapsula esas operaciones como herramientas que el agente puede llamar directamente. La arquitectura completa tiene cuatro componentes:

Agente / IDE → Servidor MCP (JSON-RPC) → API Fiscal Colombia → DIAN

El servidor es stateless. Los resultados —CUFE, XML firmado, estado de validación— llegan al agente exactamente como los devuelve la DIAN, sin transformaciones intermedias. La autenticación usa un token Bearer emitido por el proveedor del servidor MCP.

Qué debe resolver el servidor MCP por el desarrollador

Un servidor MCP de infraestructura fiscal colombiana expone al menos cuatro categorías de herramientas: emisión de facturas electrónicas (con firma XAdES-BES y transmisión al hub DIAN), emisión de notas crédito, diagnóstico de errores de rechazo (traduciendo códigos técnicos a causas legibles) y validación de NITs contra el RUT de la DIAN.

Para Colombia, el único servidor MCP de infraestructura fiscal disponible públicamente a la fecha es el publicado por Alanube, proveedor de facturación electrónica con cobertura DIAN, CUFE y RADIAN. El servidor expone cuatro herramientas principales. Para el detalle de cada una, ver Las 4 herramientas del MCP de Colombia.

Prerrequisitos antes de conectar

Independientemente del IDE que se use, conectar un cliente MCP a un servidor fiscal colombiano requiere tres elementos:

API key del servidor MCP. El endpoint no es público — requiere autenticación. El proveedor del servidor emite el token al registrar la cuenta. En entorno Sandbox se pueden usar credenciales de prueba.

Cliente MCP instalado y compatible. Los clientes que implementan el protocolo MCP incluyen Claude Desktop (versión ≥ 0.9), Cursor, VS Code con extensión MCP, Windsurf y Zed. También es posible conectarse programáticamente usando el SDK oficial @modelcontextprotocol/sdk en TypeScript o Python.

NIT del emisor registrado en la DIAN con certificado digital vigente. En Sandbox se usan los NITs de prueba que provee el servidor, no es necesario un certificado real.

Configuración en Claude Desktop

La configuración se realiza editando el archivo claude_desktop_config.json ubicado en ~/.config/claude/ (Linux/Mac) o %APPDATA%\Claude\ (Windows). Agregar el servidor bajo la clave mcpServers:

{
  "mcpServers": {
    "fiscal-colombia": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sse"],
      "env": {
        "MCP_SERVER_URL": "https://[endpoint-del-servidor]/mcp/co",
        "MCP_API_KEY": "TU_API_KEY"
      }
    }
  }
}

Reemplazar [endpoint-del-servidor] con la URL que provee el proveedor del servidor MCP. Reiniciar Claude Desktop después de guardar. Para verificar que las herramientas están disponibles, escribir en el chat: ¿Qué herramientas tienes disponibles? — el agente listará las herramientas fiscales cargadas desde el servidor.

Configuración en Cursor y VS Code (guía detallada aquí)

En Cursor, la configuración MCP se gestiona desde Settings → MCP Servers → Add Server. Ingresar la URL del endpoint y el API key. El proceso toma menos de dos minutos.

En VS Code, instalar la extensión oficial MCP Client y agregar el servidor en .vscode/mcp.json dentro del workspace:

{
  "servers": {
    "fiscal-colombia": {
      "type": "sse",
      "url": "https://[endpoint-del-servidor]/mcp/co",
      "headers": {
        "Authorization": "Bearer TU_API_KEY"
      }
    }
  }
}

Primera prueba: verificar conectividad con validate_co_nit

La prueba más directa para confirmar que el servidor responde es consultar un NIT. Esta operación no requiere datos de factura — solo verifica que el NIT esté activo en el RUT de la DIAN y devuelve razón social, régimen tributario y estado. Si el servidor responde con los datos del contribuyente, la conexión está funcionando. Ejemplo de prompt en Claude Desktop:

Valida el NIT 900123456-7 y dime si está habilitado como emisor electrónico en la DIAN.

Si el servidor retorna un error de autenticación (401), revisar el API key en la configuración. Si retorna un timeout o un error de conexión, verificar que la URL del endpoint no tenga trailing slash ni parámetros adicionales.

Errores frecuentes al conectar y cómo resolverlos

El error más común es un 401 Unauthorized, que indica que el API key está incorrecto o que la variable de entorno no se cargó correctamente. Verificar que el archivo de configuración no tenga espacios extra alrededor del valor del token.

Si el cliente MCP no detecta las herramientas después de reiniciar, verificar que el servidor esté activo con una llamada directa al endpoint desde curl o HTTPie: un servidor SSE activo responde con Content-Type: text/event-stream.

Si las herramientas aparecen pero las llamadas devuelven errores DIAN, el problema está generalmente en los datos del emisor (NIT no habilitado, certificado vencido) o en el entorno (intentar emitir en producción con credenciales de sandbox).

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

Preguntas frecuentes

¿Cuál es la diferencia entre MCP y una integración REST directa contra la DIAN?

Con una integración REST directa, el desarrollador construye el XML UBL 2.1, implementa la firma XAdES-BES, gestiona el CUFE y maneja los estados de validación de forma manual. Con MCP, esas operaciones están encapsuladas en herramientas que el agente invoca describiendo la factura en lenguaje natural o pasando un JSON de negocio. La complejidad técnica fiscal es responsabilidad del servidor, no del código del integrante.

¿Cómo puedo usar un servidor MCP en producción sin un IDE?

El protocolo MCP es agnóstico del cliente. El SDK oficial @modelcontextprotocol/sdk en TypeScript o Python permite integrar un cliente MCP en cualquier aplicación backend. El servidor responde exactamente igual independientemente del cliente — IDE o código propio.

¿Qué diferencia hay entre un servidor MCP fiscal y un wrapper REST?

Un wrapper REST expone la API del proveedor con una capa HTTP adicional pero mantiene la misma interfaz estructurada. Un servidor MCP expone herramientas con descripción semántica que un LLM puede descubrir y usar sin instrucciones adicionales en el código — el agente entiende qué hace cada herramienta y cuándo usarla. Es la diferencia entre una librería y un colaborador con conocimiento del dominio.

¿Es posible conectar múltiples NITs emisores con un solo servidor MCP?

Sí. El servidor acepta el NIT emisor como parámetro en cada llamada. No es necesario reconectar ni cambiar la configuración del cliente para alternar entre emisores. Cada llamada puede especificar un emisor distinto dentro de los autorizados por el API key.