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

Emite y consulta facturas electrónicas de Panamá directamente desde cualquier agente de IA.

El MCP de Alanube expone el catálogo de facturación electrónica de Panamá como un servidor Model Context Protocol. Al conectarlo a Claude, Cursor, Continue o tu propio agente, tu aplicación puede crear su empresa emisora y su punto de facturación, y emitir facturas electrónicas desde lenguaje natural, con las mismas garantías de cumplimiento que ofrece la API REST.

📘

En resumen

Un solo endpoint con 7 herramientas listas para usar y las mismas garantías DGI que v1.0-PAN. 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 v1.0-PAN y le agrega los controles que un agente autónomo realmente necesita: validación previa, las reglas del punto de facturación que el esquema no expresa y un resultado que indica si el documento ya tiene validez legal.

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/>v1.0-PAN · PAC]
    C -.->|sincronización| D[DGI]
    C -.-> B
    B -.-> A

En Panamá, Alanube es un PAC (Proveedor de Autorización Calificado) dentro del modelo de autorización descentralizado de la DGI: autoriza el documento en el momento de la emisión y después lo sincroniza con la DGI.

El MCP no guarda estado y se autentica con tu mismo token de Alanube, por lo que los estados y las respuestas del PAC y de la DGI llegan exactamente como los devuelve la API. Cada respuesta suma además un resumen legible (resultSummary) y conserva la respuesta original de la API.

Catálogo de herramientas

Siete herramientas organizadas en dos capas.

📘

El detalle de cada herramienta viene en el propio MCP

Los parámetros, los campos obligatorios, las reglas de validación 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. Cubren toda la API de Panamá, incluidos los documentos que todavía no se emiten desde el MCP.

📨 Emisión y seguimiento

El corazón operativo: cuando el PAC autoriza la factura, el documento ya tiene validez legal en la misma respuesta. La herramienta de status sirve para ver la revisión posterior de la DGI y pedir los archivos firmados.

Cobertura de tipos de documento

Las notas de crédito y débito y los eventos se pueden explorar con discover_pa_endpoint y explain_pa_endpoint, pero todavía no tienen herramienta de emisión. La anulación fiscal de documentos no está disponible desde el MCP.

¿Cómo empezar?

1. Configura tu entorno

Necesitas tu token de sandbox, el mismo con el que llamas a la API sandbox de Panamá. El MCP lo recibe en el header Authorization: Bearer <token> y rechaza los tokens de producción. Si tu token de Alanube tiene acceso a varios países, te sirve para todos sus MCP.

🚧

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

export ALANUBE_TOKEN="<TU_TOKEN_SANDBOX>"

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

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

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

{
  "mcpServers": {
    "alanube-pa": {
      "url": "https://sandbox-mcp.alanube.co/mcp/pa",
      "headers": { "Authorization": "Bearer ${env:ALANUBE_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-token",
      "description": "Token sandbox de Alanube",
      "password": true
    }
  ],
  "servers": {
    "alanube-pa": {
      "type": "http",
      "url": "https://sandbox-mcp.alanube.co/mcp/pa",
      "headers": { "Authorization": "Bearer ${input:alanube-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-pa": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://sandbox-mcp.alanube.co/mcp/pa",
        "--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. Prepara tu empresa y tu punto de facturación

La empresa: create_pa_sandbox_company crea la empresa y dispara su afiliación ante la DGI, que arranca en REQUESTED. La empresa puede emitir recién cuando la afiliación llega a SUBSCRIBED y tiene un código de seguridad de la DGI; la herramienta te informa ambos datos. Si el certificado no pasa la validación, la empresa no se crea. El nombre que envías se reemplaza por el del registro de la DGI para ese RUC.

El punto de facturación: todo documento se emite desde un punto de facturación, y una empresa sin ninguno recibe AP1008 Office not found. create_pa_sandbox_office revisa, antes de enviarlas, reglas que el esquema no expresa:

Si tu usuario no tiene una empresa principal sino solo empresas asociadas, indica idCompany al emitir. El MCP lo conserva en el trackingReference para que la consulta de estado use la misma empresa.

3. Emite tu primer documento

Pídelo al agente en lenguaje natural:

Emite una factura electrónica por un servicio de consultoría de B/.100,00 + ITBMS 7%.

El agente arma el payload con ayuda de explain_pa_endpoint, llama a issue_pa_invoice, valida el payload, lo envía y devuelve:

{
  "ok": true,
  "cufe": "FE01...",
  "pacResponse": [{ "code": "0260", "message": "Autorizado el uso de la FE" }],
  "isFinal": true,
  "legalStatus": "PAC_AUTHORIZED",
  "trackingReference": {
    "flow": "pa.invoice",
    "environment": "sandbox",
    "documentId": "...",
    "documentNumber": "FE01..."
  }
}

Eso es todo: emitir y tener el documento autorizado en la misma respuesta.

4. 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/pa"),
  { requestInit: { headers: { Authorization: `Bearer ${process.env.ALANUBE_TOKEN}` } } }
);
const client = new Client({ name: "mi-aplicacion", version: "1.0.0" });
await client.connect(transport);

const issued = await client.callTool({
  name: "issue_pa_invoice",
  arguments: {
    payload: { /* factura electrónica completa */ }
  }
});

const status = await client.callTool({
  name: "get_pa_invoice_status",
  arguments: {
    trackingReference: { /* el que devolvió issue_pa_invoice */ },
    documents: "pdf-xml"
  }
});

Tres flujos que conviene conocer

Flujo 1 — La autorización del PAC ya es definitiva

Cuando el PAC autoriza la factura, issue_pa_invoice devuelve legalStatus: "PAC_AUTHORIZED" e isFinal: true. El documento ya tiene validez legal: no necesitas esperar a la DGI.

Flujo 2 — Revisión posterior de la DGI

Después, Alanube sincroniza el documento con la DGI, que lo vuelve a revisar. Ese resultado (DGI_AUTHORIZED o DGI_REJECTED) se consulta con get_pa_invoice_status, que muestra la vista de la DGI en dgi. Los archivos firmados solo vienen si los pides con documents (xml, pdf, xml-pdf, pdf-xml, container o container-pdf).

Flujo 3 — El rechazo del PAC llega como error

Alanube no guarda un documento que no autorizó. Por eso un rechazo del PAC no llega como una respuesta exitosa con estado rechazado, sino como un error (ok: false) con el código HTTP, el mensaje de la API y el cuerpo completo del error, donde están los códigos de cada problema. Con eso, el agente puede corregir su propio payload y volver a intentar.

Garantías que te damos

• Solo sandbox: las herramientas que crean empresas, puntos de facturación o documentos operan únicamente contra el ambiente de pruebas.
• Catálogo controlado: solo se permiten operaciones que ya están en v1.0-PAN. 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.
• Higiene de respuestas: el MCP devuelve URLs y metadatos estructurados; nunca incluye el contenido de los archivos en el contexto del agente.
• Fidelidad con la DGI: los estados legales y las respuestas del PAC y de la DGI llegan sin modificar.
• Texto de terceros identificado: los mensajes del PAC, de la DGI 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 la DGI. Elegir uno no te impide usar el otro en paralelo.

Empieza

• 📖 Referencia REST: developer.alanube.co/v1.0-PAN
• 🔑 Token de sandbox: solicítalo desde el dashboard de tu cuenta de Alanube.
• 🛠️ Endpoint MCP: https://sandbox-mcp.alanube.co/mcp/pa
• 🌎 MCP en otros países: República Dominicana, Colombia y Costa Rica
• 💬 Soporte: [email protected]

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