Conecta tu agente (MCP)

uuid.mx tiene un servidor MCP para que Claude Code, Cursor o cualquier agente compatible con MCP timbre en sandbox, lea lo que se envió y lo que respondió el SAT en cada petición, corrija y reintente, sin que tengas que abrir el portal.

URL: https://api.uuid.mx/mcp (Streamable HTTP, stateless)
Autenticación: tu API key en Authorization: Bearer …. Se crea en portal.uuid.mx/api-keys.

Conectar

No pegues tu key directo en un mcp.json dentro del proyecto: ese archivo suele terminar en el repo con el siguiente commit. Guárdala en una variable de entorno (UUID_API_KEY) y deja que tu agente la lea, como en los ejemplos.

# Se guarda en tu usuario (~/.claude.json), no en el repo
claude mcp add --transport http uuidmx https://api.uuid.mx/mcp \
  --header "Authorization: Bearer uuid_sandbox_…"

Cada agente expande variables con su propia sintaxis: Claude Code usa ${UUID_API_KEY} y Cursor ${env:UUID_API_KEY}. Con otro agente, revisa su documentación antes de copiar el ejemplo. El .mcp.json de Claude Code sí se puede subir al repo, porque ya no lleva la key: así todo el equipo comparte la conexión y cada quien pone la suya.

Para revisar producción sin perder sandbox, registra dos conexiones: uuidmx con la key de sandbox y uuidmx-prod con la de producción, cada una con su propia variable.

Qué puede hacer el agente

La API key decide el ambiente:

Tool	Sandbox (`uuid_sandbox_…`)	Producción (`uuid_live_…`)
`buscar_eventos`, `ver_evento`	✅	✅
`listar_facturas`, `ver_factura`, `descargar_xml`	✅	✅
`consultar_estatus_sat`, `consultar_cancelacion`	✅	✅
`listar_emisores`, `ver_emisor`, `consultar_saldo`	✅	✅
`obtener_plantilla`	✅	✅
`timbrar`, `cancelar`, `crear_prefactura`	✅	—

Con una key de producción las tools de acción no existen: el agente puede revisar qué pasó, pero no puede timbrar, cancelar ni prefacturar.

Con una key de producción el agente ve los datos de tus receptores (RFC, nombre, domicilio y el XML), igual que los vería tu código con esa misma key. Tenlo en cuenta al elegir qué key le das.

Prompts de ejemplo

Integrar

Integra el timbrado CFDI 4.0 de uuid.mx en este proyecto. Parte de la plantilla de factura global, timbra una de prueba en sandbox y, si falla, revisa el evento de esa petición hasta que salga.

Depurar

Revisa el request 65983fe2-0585-4af4-a6dd-980e2ba82f92 de uuid.mx. Dime por qué falló y qué campo del CFDI tengo que corregir.

Seguir una factura

¿Qué pasó con la factura eb726f5f-6ab7-4da0-8168-ee5816b98e74? Dame su historia en uuid.mx y confirma si sigue vigente en el SAT.

Plantillas

obtener_plantilla regresa un CFDI 4.0 que ya timbró en sandbox con el emisor de pruebas EKU9003173C9, con la Fecha actual puesta: factura_global (Público en General, con InformacionGlobal) o ingreso (a una persona moral). Es el punto de partida recomendado: se ajustan conceptos y montos, no la forma.

Fecha va en hora de la Ciudad de México, sin zona (2026-09-28T12:41:47), y dentro de las últimas 72 horas. Si mandas la hora de un servidor en UTC, el PAC responde 401 - El rango de la fecha de generación no debe de ser mayor a 72 horas.

Depurar una petición, con o sin agente

Toda respuesta de la API trae el header X-Request-Id. Si la petición llegó al PAC, su evento guarda lo que se envió y lo que se respondió.

Con el MCP, el agente usa buscar_eventos con ese requestId y abre el detalle con ver_evento. Sin agente, es la misma consulta en la API:

curl https://api.uuid.mx/v1/eventos?requestId=65983fe2-0585-4af4-a6dd-980e2ba82f92 \
  -H 'Authorization: Bearer uuid_sandbox_…'
curl https://api.uuid.mx/v1/eventos/<id> \
  -H 'Authorization: Bearer uuid_sandbox_…'

GET /v1/eventos también filtra por uuid (toda la historia de una factura) o por el rango desde/hasta.

Los rechazos que ocurren antes de llegar al PAC (emisor no registrado, certificado vencido, sin saldo) no dejan evento: su mensaje viene completo en la respuesta.