Servidor MCP

Además de la API REST, el servicio expone un servidor MCP (Model Context Protocol) por Streamable HTTP para que agentes y LLMs consulten los catálogos y validen o generen CFDI como herramientas. Usa la misma API key, los mismos scopes y los mismos permisos que la API REST, y expone también las herramientas de gestión para que una integración se configure por completo desde MCP.

POST /mcp Authorization: Bearer <token>

Configuración del cliente

Para clientes que solo soportan MCP por stdio (p. ej. Claude Desktop), usa mcp-remote como puente:

{
  "mcpServers": {
    "sat-catalogos": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<host>/mcp",
        "--header",
        "Authorization: Bearer <token>"
      ]
    }
  }
}

Los clientes con soporte nativo de Streamable HTTP apuntan directo a https://<host>/mcp con el encabezado Bearer.

Herramientas

Catálogos y versiones:

• listar_catalogos — catálogos disponibles y si admiten descarga completa.
• descargar_catalogo — descarga completa sin paginación de un catálogo cacheable.
• version_catalogos — versión instalada, versión disponible y si hay actualización (equivalente a GET /api/v1/version).

CFDI 4.0 (validación, generación y timbrado):

• validar_cfdi — valida el XML de un CFDI 4.0 con el mismo pipeline de /api/v1/cfdi/validar (guía de validación); con el flag opcional consultar_sat consulta además el estado del CFDI ante el SAT (llamada de red externa).
• consultar_estado_cfdi — consulta el estado de un CFDI timbrado ante el WS público del SAT (Vigente/Cancelado/No Encontrado, es_cancelable, estatus de cancelación), como el endpoint /api/v1/cfdi/consulta-estado; acepta el xml completo (extrae los datos) o los 4 datos del timbre (uuid, rfc_emisor, rfc_receptor, total).
• generar_cfdi_ingreso, generar_cfdi_egreso, generar_cfdi_traslado, generar_cfdi_pago — generan un CFDI 4.0 sellado del tipo correspondiente (I, E, T o REP con Pagos 2.0) con el CSD de la empresa del usuario, como los endpoints /api/v1/cfdi/generar/* (guía de generación); con el parámetro opcional timbrar: true lo devuelven además timbrado por el proveedor configurado (guía de timbrado).

Gestión de la integración (los mismos scopes, permisos y códigos de error que la API de gestión): permiten configurar una aplicación que solo habla MCP, sin tocar el panel.

• listar_empresas — emisores de la cuenta maestra del token (empresas:read).
• registrar_empresa — alta de un emisor con su CSD en base64 (cer_b64, key_b64, password, regimen_fiscal); el RFC es único dentro de la cuenta (empresas:write).
• actualizar_empresa — edita el régimen fiscal y/o la liga con el agente de timbrado (empresas:write).
• listar_aplicaciones — aplicaciones consumidoras de la cuenta (aplicaciones:read, administradores).
• crear_api_key — crea una key y devuelve el token una sola vez; con aplicacion_slug la crea para esa aplicación (apikeys:manage, sujeto a la regla de anti-escalada).

Y una herramienta de consulta paginada por cada catálogo del registry (los mismos filtros de /api/v1/catalogos/<nombre>/entradas):