Conectar tu agente por MCP

URL del servidor MCP: https://mcp.factucat.com/mcp (HTTP). Compatible con Claude, ChatGPT, Cursor y Codex. MCP está en todos los planes desde Free, timbrado incluido.

Cómo autenticarte

• OAuth (con tu cuenta): para conectores remotos como Claude y ChatGPT. Inicias sesión en FactuCat, revisas los permisos y eliges el RFC emisor antes de aceptar.
• API key: para Cursor, Codex, Claude Code o agentes propios. Créala en Configuración → API keys (se muestra una sola vez), guárdala en FACTUCAT_API_KEY y dale solo los permisos que necesita. Se envía como Authorization: Bearer fc_live_… o Authorization: Bearer fc_test_…. Empieza con una llave de prueba.

Timbrar y cancelar en producción solo funciona si tu conexión está habilitada en modo live. Mientras no lo esté, el consentimiento OAuth no permite pedir permisos para timbrar o cancelar y las llaves live quedan en solo lectura. Las consultas siguen funcionando.

Claude

1. En los conectores de Claude, agrega un conector personalizado con la URL https://mcp.factucat.com/mcp.
2. Inicia sesión en FactuCat, revisa los permisos, elige el RFC emisor y acepta.
3. Abre una conversación y pide que revise tu conexión.

Claude Code, con FACTUCAT_API_KEY definida:

claude mcp add --transport http factucat https://mcp.factucat.com/mcp --header "Authorization: Bearer ${FACTUCAT_API_KEY}"

ChatGPT

1. En conectores o apps de ChatGPT, crea un conector MCP personalizado con la URL https://mcp.factucat.com/mcp y autenticación OAuth.
2. Completa el consentimiento en FactuCat: inicia sesión, revisa permisos y selecciona el RFC emisor.
3. Usa el conector y pide que revise tu conexión.

La disponibilidad de conectores personalizados depende de tu plan y de la configuración de ChatGPT.

Cursor

Define FACTUCAT_API_KEY en el entorno desde el que abres Cursor y agrega a ~/.cursor/mcp.json o .cursor/mcp.json:

{
  "mcpServers": {
    "factucat": {
      "url": "https://mcp.factucat.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:FACTUCAT_API_KEY}"
      }
    }
  }
}

Codex

Define FACTUCAT_API_KEY y agrega a ~/.codex/config.toml:

[mcp_servers.factucat]
url = "https://mcp.factucat.com/mcp"
bearer_token_env_var = "FACTUCAT_API_KEY"

Permisos

Permiso	Qué permite
customer:read	Consultar clientes
customer:write	Crear clientes
invoice:read	Consultar borradores, facturas, XML y PDF
invoice:write	Preparar y editar borradores
invoice:stamp	Timbrar facturas, con confirmación
invoice:cancel	Cancelar facturas, con confirmación
payroll:read	Consultar empleados, lotes y recibos · plan Miau
payroll:write	Timbrar lotes o cancelar recibos, con confirmación · plan Miau
offline_access	Mantener la conexión sin volver a iniciar sesión · solo OAuth

Si la credencial no tiene el permiso, la herramienta responde con un error de permiso. Las llaves del plan API no incluyen payroll:*.

Confirmaciones e idempotencia

Timbrar y cancelar son de dos pasos:

1. invoice_stamp {draft_id, idempotency_key} (o invoice_cancel, payroll_batch_stamp) sin confirmation_token devuelve confirmation_required: una vista previa y un token firmado ligado al contenido que vence en 5 minutos.
2. Tras tu confirmación, el agente repite la llamada con el confirmation_token y la misma idempotency_key. Si cambia el borrador o vence el token, hay que pedir otra vista previa.

Reintentar con la misma idempotency_key recupera el resultado y no timbra dos veces.

Ejemplo de timbrado: customers_list → draft_create {customerId} → draft_add_item {draft_id, description, quantity, unitPrice, productCode} → invoice_stamp (vista previa) → invoice_stamp con token. Cancelación: invoice_cancel {invoice_id, reason: "02", idempotency_key}; el motivo 01 requiere replacementInvoiceId de una factura sustituta ya timbrada. Para revisar la conexión: whoami {}.