Conectar MCP de facturación electrónica en Claude Desktop — República Dominicana
Conectar MCP de facturación electrónica en Claude Desktop toma menos de 10 minutos si se sabe exactamente qué editar. El archivo de configuración de Claude Desktop tiene una sola entrada que separa a un developer de poder emitir comprobantes fiscales electrónicos ante la DGII en lenguaje natural, usando el MCP de infraestructura fiscal de Alanube. El problema no es técnico: es que la mayoría de las guías de MCP explican el protocolo en abstracto y no muestran el JSON exacto que hay que escribir, ni qué token usar, ni por qué el servidor no aparece después de reiniciar. Esta guía cubre cómo conectar el MCP de facturación electrónica de Alanube en Claude Desktop paso a paso, con el archivo de configuración completo, los errores más frecuentes y cómo extender la misma configuración a Cursor, VS Code y Zed.
Tiempo estimado al primer e-CF emitido desde el chat: menos de 10 minutos si ya se tiene el token Sandbox activo.
Índice de contenidos
- Por qué Claude Desktop es el punto de entrada más rápido al MCP de Alanube
- Prerrequisitos antes de editar el archivo de configuración
- Cómo localizar y editar
claude_desktop_config.jsonsegún el sistema operativo - Cómo verificar que el servidor MCP quedó activo
- Emitir el primer e-CF en lenguaje natural: ejemplo con Factura de Consumo
- Qué pasa con los tipos asíncronos: polling y trackingReference
- Extender la configuración a Cursor, VS Code y Zed
- Errores comunes al conectar el MCP y cómo resolverlos
Por qué Claude Desktop es el punto de entrada más rápido al MCP de Alanube
El MCP (Model Context Protocol) de infraestructura fiscal de Alanube expone la API de facturación electrónica de República Dominicana como herramientas que cualquier agente de IA puede invocar directamente. Claude Desktop es el cliente de referencia porque la configuración se reduce a un archivo JSON, no requiere código, y el catálogo de las 30 herramientas queda disponible en el momento en que el servidor responde.
La alternativa es integrar el mismo MCP vía SDK desde código, lo que tiene sentido para producción pero agrega fricción en la fase de exploración. Para un developer que quiere entender qué hace cada herramienta, qué respuesta devuelve la DGII y cómo se comporta el flujo asíncrono, Claude Desktop permite iterar en segundos sin escribir ni un import.
💡 Con Alanube: el MCP de infraestructura fiscal de Alanube es el primer servidor MCP conectado a la DGII de República Dominicana. Accede a la misma API REST v1.0-DOM certificada — no agrega una capa nueva, expone la misma infraestructura como herramientas invocables desde el IDE.
Prerrequisitos antes de editar el archivo de configuración
- Token Sandbox activo de la API de Alanube. Se solicita al equipo de Alanube — la documentación del MCP de Alanube incluye el proceso completo. No requiere contrato previo. Es el mismo token que usa la API REST; no hay credenciales separadas para el MCP.
- Claude Desktop instalado en la versión más reciente. Disponible en claude.ai/download para macOS, Windows y Linux.
- Editor de texto para modificar el archivo JSON de configuración. Cualquier editor sirve — VS Code, Sublime, nano, Notepad.
- Conocer el tipo de e-CF principal que la integración necesita emitir, para anticipar si el flujo será síncrono o asíncrono desde el primer test.
⚠️ Nota normativa: el Sandbox del MCP de Alanube opera contra el Ambiente Piloto de la DGII. Los documentos emitidos no tienen validez fiscal real — son exclusivamente para desarrollo y prueba bajo la Ley núm. 32-23 de Facturación Electrónica (2023).
Cómo localizar y editar claude_desktop_config.json según el sistema operativo
Claude Desktop gestiona todos los servidores MCP desde un archivo JSON central. La ruta varía por sistema operativo:
| Sistema operativo | Ruta del archivo |
|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
| Linux | ~/.config/Claude/claude_desktop_config.json |
Si el archivo no existe, se crea manualmente en esa ruta. Si ya tiene otros servidores configurados, se edita el archivo existente agregando la entrada de Alanube sin tocar las demás.
El bloque que hay que agregar dentro de mcpServers:
{
"mcpServers": {
"alanube": {
"url": "https://sandbox-mcp.alanube.co/mcp/rd",
"headers": {
"Authorization": "Bearer TU_TOKEN_SANDBOX"
}
}
}
}Si ya hay otros servidores en el archivo, agregar alanube como una entrada más dentro del mismo objeto mcpServers:
{
"mcpServers": {
"otro-servidor-existente": {
"url": "https://...",
"headers": {}
},
"alanube": {
"url": "https://sandbox-mcp.alanube.co/mcp/rd",
"headers": {
"Authorization": "Bearer TU_TOKEN_SANDBOX"
}
}
}
}Reemplazar TU_TOKEN_SANDBOX con el token recibido. No agregar espacios antes ni después del token.
Antes de guardar: validar el JSON en jsonlint.com. Un error de sintaxis impide que Claude Desktop cargue el servidor sin mostrar un mensaje claro.
Cómo verificar que el servidor MCP quedó activo
Los cambios en claude_desktop_config.json no se cargan en caliente: se requiere reinicio completo. No basta cerrar la ventana — el proceso debe terminar completamente.
En macOS: Cmd + Q o clic derecho en el Dock → Salir.
En Windows: clic derecho en la bandeja del sistema → Salir.
En Linux: pkill claude o desde el administrador de tareas.
Al volver a abrir y crear una conversación nueva, hacer clic en el ícono de herramientas o conectores. Si el servidor alanube aparece con herramientas como issue_and_track_rd_document o discover_rd_endpoint, la conexión fue exitosa.
💡 Con Alanube: no se necesita configuración adicional por herramienta. Las 30 herramientas del catálogo quedan disponibles automáticamente en cuanto el cliente detecta el servidor.
Emitir el primer e-CF en lenguaje natural: ejemplo con Factura de Consumo
Con el servidor activo, el developer describe la operación al agente sin construir el payload manualmente. Claude identifica la herramienta adecuada, construye el JSON con los campos correctos, lo valida y devuelve el resultado de la DGII.
Emite una Factura de Consumo (32) por una camisa negra
talla L a DOP$1.000 + ITBIS 18%El agente invoca issue_and_track_rd_document con documentTypeCode: "32" y devuelve:
{
"ok": true,
"documentTypeCode": "32",
"flowMode": "sync",
"legalStatus": "ACCEPTED",
"documentNumber": "E320000000005",
"assetUrls": {
"xml": "https://...",
"pdf": "https://...",
"resumeXml": "https://..."
}
}El campo legalStatus: "ACCEPTED" confirma que la DGII aceptó el documento. El resultado fue síncrono porque el monto es menor a DOP$250.000 — la única excepción síncrona de los 10 tipos de e-CF activos en República Dominicana.
Qué pasa con los tipos asíncronos: polling y trackingReference
Para cualquier tipo distinto al 32 por debajo de DOP$250.000, la DGII no devuelve el resultado final de inmediato. La primera respuesta contiene el estado interno y una referencia de seguimiento:
{
"ok": true,
"documentTypeCode": "31",
"flowMode": "async",
"finalLegalOutcomeReached": false,
"trackingReference": {
"flow": "rd.fiscal-credit-invoice-31",
"documentId": "doc_abc123"
}
}Desde Claude Desktop, el agente consulta el estado con ese trackingReference cuando se le pide, o hace el polling automático si se activa esa opción en issue_and_track_rd_document.
| Tipo de e-CF | Flujo | Condición |
|---|---|---|
| 32 — Factura de Consumo | Síncrono | Solo si monto < DOP$250.000 |
| 32 — Factura de Consumo | Asíncrono | Monto ≥ DOP$250.000 o timeout DGII |
| 31, 33, 34, 41, 43, 44, 45, 46, 47 | Asíncrono | Siempre, sin excepción por monto |
Extender la configuración a Cursor, VS Code y Zed
El bloque de configuración del MCP de Alanube es idéntico en todos los clientes MCP. Solo cambia la ruta del archivo:
| Cliente MCP | Archivo de configuración |
|---|---|
| Claude Desktop | claude_desktop_config.json |
| Cursor | .cursor/mcp.json |
| VS Code | .vscode/mcp.json |
| Zed | ~/.config/zed/settings.json bajo context_servers |
| Windsurf | ~/.codeium/windsurf/mcp_config.json |
| Claude Code (CLI) | Comando claude mcp add o ~/.claude.json |
Errores comunes al conectar MCP de facturación electrónica con Claude Desktop
Error: el servidor alanube no aparece en la lista de herramientas después de reiniciar.
Causa: error de sintaxis en el JSON — coma faltante, corchete sin cerrar, o comillas simples.
Solución: pegar el contenido en jsonlint.com, corregir el error y reiniciar Claude Desktop completamente.
Error: el servidor aparece pero las herramientas no se cargan o aparecen en gris.
Causa: el token Sandbox es inválido, expiró, o fue copiado con espacios adicionales.
Solución: verificar que el header sea exactamente Bearer [token] sin caracteres extra. Solicitar token nuevo al equipo de Alanube si expiró.
Error: el servidor se conecta pero las llamadas devuelven 401 Unauthorized.
Causa: el token corresponde a producción en lugar de Sandbox, o fue revocado.
Solución: confirmar con Alanube que el token es específico del ambiente sandbox-mcp.alanube.co/mcp/rd.
Error: flowMode: "async" en una Factura de Consumo cuando se esperaba respuesta inmediata.
Causa: el monto superó DOP$250.000 o la DGII no respondió en tiempo.
Solución: no es un error de integración. El mismo trackingReference sirve para consultar el estado final sin lógica adicional.
Preguntas frecuentes para conectar MCP de facturación electrónica en Claude Desktop
¿Cuál es la diferencia entre conectar el MCP vía Claude Desktop y hacerlo por código?
Claude Desktop permite invocar las herramientas del MCP de infraestructura fiscal de Alanube en lenguaje natural, sin código de integración. La conexión vía SDK desde código ofrece más control para producción pero agrega fricción en la fase de exploración. Ambas rutas acceden al mismo servidor MCP y producen los mismos resultados ante la DGII.
¿Cómo puedo verificar que el servidor MCP de Alanube está activo en Claude Desktop?
Al abrir una conversación nueva tras reiniciar, hacer clic en el ícono de herramientas. Si el servidor alanube aparece con herramientas como issue_and_track_rd_document o discover_rd_endpoint, la conexión fue exitosa. Si no aparece, revisar la sintaxis del JSON y que el proceso se cerró completamente antes de reiniciar.
¿Qué pasa si Claude Desktop no reconoce el servidor MCP después de reiniciar?
Las causas más comunes son error de sintaxis JSON o token inválido. Validar el JSON en jsonlint.com, confirmar que el token no tiene espacios extra, y asegurarse de que el proceso de Claude Desktop se cerró completamente — no solo la ventana — antes de reiniciar.
¿La API de Alanube permite conectar el mismo servidor MCP en Cursor y VS Code además de Claude Desktop?
Sí. El MCP de infraestructura fiscal de Alanube es compatible con cualquier cliente que soporte el protocolo MCP: Cursor, VS Code, Zed, Windsurf, Continue y Claude Code. El bloque de configuración es idéntico en todos; solo cambia la ruta del archivo donde se declara.
Conecta el MCP de facturación electrónica de Alanube hoy
Solicita acceso al Sandbox del MCP de infraestructura fiscal de Alanube para República Dominicana y emite tu primer e-CF ante la DGII desde Claude Desktop en menos de 10 minutos.
Solicita acceso al Sandbox del MCP de Alanube →
Fuentes
Anthropic. (2026). Introducción a los servidores MCP locales en Claude Desktop. https://support.claude.com/es/articles/10949351
Alanube. (2026). Documentación oficial del MCP de Alanube para República Dominicana. https://developer.alanube.co/docs/alanube-mcp
Congreso Nacional de la República Dominicana. (2023). Ley núm. 32-23 de Facturación Electrónica. Gaceta Oficial.
DGII. (2023). Facturación Electrónica. https://dgii.gov.do
