Documentación

Primera prueba, sin tarjeta

La llave de prueba es gratuita y sale por correo. Timbra 2 CFDI de prueba en el sandbox del SAT y caduca a los 7 días. No tiene validez fiscal: sirve para ver el circuito completo antes de pagar nada.

curl -X POST https://mcp.factumatico.com/api/mcp/trial/issue \
  -H 'Content-Type: application/json' \
  -d '{"email":"tu@correo.com"}'

Respuesta: un JSON con api_key que empieza por sk_test_. Se muestra una sola vez y también llega al correo.

Conectar tu agente

Endpoint: https://mcp.factumatico.com/mcp · JSON-RPC 2.0 sobre HTTP · protocolo MCP 2025-06-18 · autenticación Authorization: Bearer <TU_LLAVE>.

Elige tu cliente y salta a su apartado. La columna «cómo» dice de qué va cada uno:

Claude Code — un comando

claude mcp add --transport http factumatico https://mcp.factumatico.com/mcp \
  --header "Authorization: Bearer TU_LLAVE"

Comprueba con /mcp dentro de Claude Code, o claude mcp get factumatico. Debe decir connected; si dice failed, el detalle trae el código HTTP —un 401 es llave inválida o caducada—. Añade --scope user si lo quieres en todos tus proyectos.

Claude Desktop — paso a paso

1. Abre el archivo de configuración. En Claude Desktop: menú Ajustes → Desarrollador → botón Editar configuración. Eso abre la carpeta con el archivo:

Ábrelo con el Bloc de notas o cualquier editor de texto.

2. Pega esto y cambia TU_LLAVE por la que te llegó por correo (empieza por sk_test_):

{
  "mcpServers": {
    "factumatico": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.factumatico.com/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": { "AUTH_HEADER": "Bearer TU_LLAVE" }
    }
  }
}

Qué es cada cosa, por si tienes que adaptarlo:

2b. Si ya tenías otros servidores, añade factumatico como una entrada más dentro de la lista que ya existe — fíjate en la coma después de la llave de cierre del servidor anterior, y en que el archivo conserva lo demás (coworkUserFilesPath, preferences…) tal cual estaba:

{
  "mcpServers": {
    "otro-servidor": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://ejemplo.com/mcp"]
    },                                      <-- coma entre servidores
    "factumatico": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.factumatico.com/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": { "AUTH_HEADER": "Bearer TU_LLAVE" }
    }
  },
  "coworkUserFilesPath": "C:\Users\TuUsuario\Claude",
  "preferences": { }
}

Fíjate en que "mcpServers" aparece una sola vez y en que todo el archivo empieza con un { y termina con un }. Si el editor te marca error, pega el contenido en un validador de JSON: te dirá la línea exacta.

3. Cierra Claude Desktop del todo y vuelve a abrirlo. No basta con cerrar la ventana: en Windows, click derecho en el icono de la bandeja → Salir; en macOS, Cmd+Q. La configuración solo se lee al arrancar.

4. Comprueba que quedó. En una conversación, pulsa el icono de «Añadir archivos, conectores y más» (abajo a la izquierda del cuadro de texto) → Conectores. Debe aparecer factumatico con sus herramientas. Pídele entonces: «lista las herramientas de factumatico».

Si no aparece: el registro dice por qué. En Windows, %APPDATA%\Claude\logs\mcp-server-factumatico.log; en macOS, ~/Library/Logs/Claude/mcp-server-factumatico.log. Lo más común, por orden: el JSON quedó con dos "mcpServers" o una coma de más, falta Node.js, o la llave está mal copiada.

ChatGPT (aplicación de escritorio)

En Ajustes → Conexiones/Complementos → MCP → Conectar a un MCP personalizado, con Tipo: STDIO:

Si eliges HTTP con transmisión en tiempo real, la URL es la misma (https://mcp.factumatico.com/mcp), pero solo servirá si esa pantalla te deja añadir la cabecera Authorization. Si no, quédate con STDIO: el resultado es el mismo.

ChatGPT en el navegador

Los conectores del ChatGPT web (Modo desarrollador) piden URL y un método de autenticación entre OAuth, sin autenticación o mixta: no hay hueco para una cabecera Bearer. Todavía no lo soportamos por esa vía y no lo hemos probado; usa la aplicación de escritorio o Claude Code. Cuando publiquemos OAuth lo diremos aquí.

Cursor, n8n y otros

Si el cliente acepta servidores HTTP con cabeceras, apúntalo a https://mcp.factumatico.com/mcp con Authorization: Bearer TU_LLAVE. Si solo acepta comandos locales, usa el mismo bloque de mcp-remote de arriba.

El recorrido, paso a paso

# 1. initialize
curl -X POST https://mcp.factumatico.com/mcp -H 'Authorization: Bearer TU_LLAVE' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"mi-agente","version":"1.0"}}}'

# 2. tools/list — devuelve exactamente las herramientas de las tablas de abajo
curl -X POST https://mcp.factumatico.com/mcp -H 'Authorization: Bearer TU_LLAVE' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

# 3. tools/call — un CFDI de prueba
curl -X POST https://mcp.factumatico.com/mcp -H 'Authorization: Bearer TU_LLAVE' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"factumatico_stamp_test_invoice","arguments":{"total":116.00,"concepto":"Prueba de integracion"}}}'

La respuesta del paso 3 trae el folio fiscal (UUID) del CFDI de prueba y descuenta uno de tus timbrados. Si algo falla, el mensaje dice qué falta.

Herramientas disponibles

Esto es todo lo que el servidor MCP expone hoy. Factumático tiene por dentro cientos de herramientas; ninguna otra está disponible por esta vía.

Con llave de prueba

Con la llave de producción se añaden

Tu negocio, no solo tus facturas (25)

Estas herramientas operan sobre los datos de tu propia empresa y están disponibles con la llave de producción, en cuanto tu CSD queda validado. No gastan timbrados: dar de alta un cliente no es timbrar.

Clientes (8)

Dar de alta, actualizar, buscar y consultar el saldo y el historial de tus clientes.

Productos y servicios (9)

Tu catálogo: altas, precios, imágenes, existencias y estadísticas.

Marca (5)

El logo que sale en tus facturas: subirlo, mejorarlo o generarlo con IA.

Series y folios (3)

Series de facturación, el siguiente folio y los datos por omisión de tus CFDI.

Tus dos llaves: pruebas y producción

Una cuenta de Factumático tiene dos credenciales distintas, y el modo lo eliges según cuál pongas en tu agente. No hay ningún interruptor escondido: cambiar de pruebas a producción es cambiar esa línea de tu configuración.

Cómo se obtiene la llave de producción

1. Contrata el Plan Agente.
2. Carga tu CSD (.cer, .key y contraseña) en la página de activación. Lo validamos en el momento.
3. Entra a tu panel y pulsa «Emitir mi llave de producción». Te pedimos confirmación: a partir de ahí tus CFDI tienen validez fiscal.
4. La llave aparece una sola vez en pantalla y te llega por correo. De ella solo guardamos una huella, así que si se pierde hay que emitir otra.

Qué incluye el Plan Agente

Errores frecuentes

Para pegarle a tu agente

Si prefieres que lo haga él, este bloque le dice qué hacer sin exponer secretos:

Vas a integrar Factumatico MCP (timbrado de CFDI 4.0 en Mexico).

1. Lee https://mcp.factumatico.com/documentacion
2. Conecta al servidor MCP https://mcp.factumatico.com/mcp con la credencial
   que te dare por un canal seguro. NO la escribas en el chat ni en el codigo.
3. Llama a tools/list y dime exactamente que herramientas te autoriza.
4. Ejecuta UNA prueba en sandbox: factumatico_stamp_test_invoice con
   total 116.00 y concepto "Prueba de integracion". Enseñame el resultado.

Reglas: no emitas ni canceles ningun CFDI real sin que yo lo confirme antes,
y no me pidas el CSD ni su contraseña por chat: eso se carga en la web.

Qué datos pedimos y para qué

Son dos cosas distintas y conviene no mezclarlas:

• Tus datos de contacto (nombre y correo al contratar): sirven para el cobro y para mandarte la llave. Puedes ser el desarrollador que integra, no hace falta que seas la empresa que factura.
• La empresa emisora (al activar): es quien aparecerá en los CFDI. Se pide su nombre, denominación o razón social, tal como aparece en tu Constancia de Situación Fiscal, su RFC, su régimen fiscal y su código postal, porque el SAT los exige en el comprobante.

El CSD se comprueba de verdad: que el certificado y la llave se correspondan, que la contraseña abra la llave y que el RFC del certificado sea el que nos diste. Eso es validar el certificado; no es una consulta al SAT sobre tu situación fiscal.