> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.uuid.mx/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.uuid.mx/_mcp/server.

# Conecta tu agente (MCP)

uuid.mx tiene un servidor [MCP](https://modelcontextprotocol.io) 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](https://portal.uuid.mx/api-keys).

## Conectar

> **Warning**
>
> 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.

**`Claude Code`**

```sh Claude Code
# 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_…"
```

**`Claude Code (.mcp.json del proyecto)`**

```json Claude Code (.mcp.json del proyecto)
{
  "mcpServers": {
    "uuidmx": {
      "type": "http",
      "url": "https://api.uuid.mx/mcp",
      "headers": { "Authorization": "Bearer ${UUID_API_KEY}" }
    }
  }
}
```

**`Cursor (.cursor/mcp.json)`**

```json Cursor (.cursor/mcp.json)
{
  "mcpServers": {
    "uuidmx": {
      "url": "https://api.uuid.mx/mcp",
      "headers": { "Authorization": "Bearer ${env:UUID_API_KEY}" }
    }
  }
}
```

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.

> **Warning**
>
> 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.

> **Tip**
>
> `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:

```sh
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.