Factumático MCP · 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>.

{
  "mcpServers": {
    "factumatico": {
      "type": "http",
      "url": "https://mcp.factumatico.com/mcp",
      "headers": { "Authorization": "Bearer PON_AQUI_TU_LLAVE" }
    }
  }
}

No pegues tu llave en un chat. Va en el archivo de configuración de tu cliente MCP o en una variable de entorno. Y el CSD (.cer, .key y contraseña) se carga solo en la página de activación, nunca en una conversación.

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

Herramienta	Qué hace	Parámetros	Ambiente
`factumatico_stamp_test_invoice`	Timbra un CFDI de PRUEBA (sandbox SAT, sin validez fiscal). Consume 1 timbrado de tu trial. Ambiente sandbox forzado.	`total`, `concepto`, `receptor_rfc`	Prueba
`factumatico_trial_status`	Muestra el estado de tu trial: timbrados usados, limite y restantes, y fecha de expiracion de tu key.	sin parámetros	Prueba
`factumatico_help`	Explica que puedes hacer con tu llave de Factumatico y cuales son tus limites.	sin parámetros	Prueba

Con Plan Agente y CSD validado, se añaden

Herramienta	Qué hace	Parámetros	Ambiente
`factumatico_stamp_invoice`	Timbra un CFDI 4.0 REAL con validez fiscal usando tu propio CSD. Consume un timbre de tu plan. Tipo ingreso, IVA 16% trasladado.	`receptor`, `conceptos`, `forma_pago`, `serie`	Producción
`factumatico_cancel_invoice`	Cancela ante el SAT un CFDI REAL emitido por ti. Solo puedes cancelar facturas de tu propia cuenta.	`uuid`, `motivo`, `uuid_sustituto`	Producción

Lo que todavía NO existe por MCP: consultar tus facturas emitidas, descargar XML/PDF de forma independiente, dar de alta clientes o productos, y la contabilidad. El XML y el PDF llegan en la respuesta de la herramienta que timbra, no por una llamada aparte. Si tu integración los necesita de otra forma, escríbenos antes de comprar.

Qué incluye el Plan Agente

Concepto	Detalle
Precio	$499 MXN IVA incluido por 30 días
Emisor	Un (1) RFC emisor. Es la empresa que factura con su CSD
Receptores	Los que quieras: el límite es del emisor, no de a quién le facturas
Timbrados	Hasta 10,000 por periodo
Importe por CFDI	Máximo $50,000.00 MXN
Renovación	Manual. Al terminar los 30 días se vuelve a pagar desde la página
Factura de la suscripción	La emite Grupo Factumático y Soluciones S.A. de C.V.

Errores frecuentes

Respuesta	Qué pasó	Qué hacer
`authentication_required`	No mandaste la cabecera `Authorization`	Añade `Bearer` y tu llave
`invalid_trial_key`	La llave no existe o fue sustituida por otra	Pide recuperarla desde la página: te llega un enlace al correo registrado
`trial_key_expired`	Se acabó la vigencia	Contrata o renueva el Plan Agente
`trial_limit_reached`	Agotaste los timbrados del periodo	Renueva. Pagar sigue funcionando aunque el cupo esté agotado
Timbra pero sin validez fiscal	Tu llave sigue en pruebas	Sube tu CSD en /activar; hasta entonces el ambiente es sandbox

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.