Scopes y permisos

Cada tool MCP declara el scope que una credencial debe tener para invocarla. Los scopes funcionan de forma ligeramente distinta según el canal:

• Las API keys se crean directamente con scopes detallados (resource:action, p. ej. invoices:read) — el mismo catálogo cerrado que usa la API REST. También puedes conceder el super-scope *.
• Los tokens OAuth reciben scopes con punto (resource.action, p. ej. invoices.read) en la pantalla de consentimiento. El servidor los traduce a los scopes detallados automáticamente, de modo que ambos canales aplican el mismo conjunto en el límite de la tool.

Catálogo de consentimiento OAuth

Estos son los scopes que un usuario puede conceder a una app de terceros en la pantalla de consentimiento. Hay 59 scopes simples más 3 macros.

Scopes simples

Cada uno concede una capacidad. La columna Maps to muestra el scope detallado que aplican las tools — la capa de consentimiento traduce los scopes OAuth con punto a estos automáticamente. La columna Sensitive marca los scopes que la pantalla de consentimiento destaca y no marca por defecto.

Perfil

CRM — clientes y proveedores

Catálogo — productos, series, impuestos

Ventas — facturas, presupuestos, proformas, albaranes

Compras

Facturas recurrentes

Cumplimiento (VeriFactu)

Webhooks

Personal — control horario

Datos de empleados, fichajes, ausencias, horarios de trabajo, presencia, festivos y exportaciones de nómina. Todos los scopes de personal son sensibles (PII de empleado y datos de cumplimiento) y requieren el módulo de plan control_horario — consulta Gating por plan y módulo. Las lecturas, employees.write y la generación de exportaciones de nómina se conceden en la pantalla de consentimiento; las acciones privilegiadas de escritura y transición no tienen scope OAuth con punto y son solo API key (listadas más abajo en los scopes detallados).

Macros

Paquetes de conveniencia que se expanden a una lista de scopes simples en el momento de emitir el token. El token persiste los scopes expandidos — las macros nunca se almacenan.

El super-scope *

Una credencial que tiene * cubre todos los scopes — las 391 tools en el caso de una API key. Es el equivalente a una clave de propietario. Resérvalo para migraciones puntuales o automatizaciones de propietario totalmente confiables; para todo lo demás, prefiere el conjunto de scopes más reducido. El super-scope está disponible para las API keys; el consentimiento OAuth concede scopes explícitos (o macros), nunca un * directo.

Cómo los scopes OAuth se convierten en scopes detallados

Cuando se emite un token OAuth, sus scopes con punto se traducen una vez al catálogo detallado que aplican las tools. Conviene conocer algunas reconciliaciones:

• recurring.* se mapea al recurso recurring_invoices:*.
• invoices.create_corrective se mapea a invoices:write (crear es una escritura).
• invoices.annul se mapea a invoices:void.
• Las acciones de ciclo de vida (*.convert, *.sign, *.pause, *.resume, *.generate_now, *.mark_paid, quotes.convert_to_invoice) se mapean al scope :transition del recurso.
• Cualquier scope de lectura sobre un documento también concede las utilidades de lectura transversales pdfs:read (descargar su PDF/recibo) y events:read (su registro de actividad).
• verifactu.write y delivery_notes:gdpr_forget no tienen scope OAuth con punto — son inalcanzables vía OAuth por diseño.
• facturae:read / facturae:write aún no están en el catálogo de consentimiento OAuth — las tools de FacturaE (FACe) solo son accesibles con API key por ahora.

Scopes detallados sin scope OAuth (solo API key)

Algunos scopes detallados viven en el catálogo cerrado recurso:accion que usan las API keys, pero no tienen equivalente OAuth con punto — nunca se conceden a través de una pantalla de consentimiento de terceros y solo son accesibles con API key. Concédelos directamente en la key (o vía el super-scope *). Algunos están gateados por un módulo de integración —entonces la empresa de la key debe tener el plan correspondiente (consulta Gating por plan y módulo)—; el resto son scopes de cuenta propia y de gestoría.

Estos scopes habilitan las tools de Pagos y pasarelas.

Un segundo grupo de scopes solo para API key gobierna la gestión de cuenta propia y de gestoría — tus propias credenciales y, para asesorías, las empresas hijas que gestionas y sus API keys. companies:* requiere el módulo del plan de gestoría; el resto no tienen gating de módulo.

Un tercer grupo cubre las acciones de escritura y transición de personal (control horario). Sus lecturas se conceden por OAuth (consulta los scopes de consentimiento de Personal más arriba), pero estos scopes privilegiados no tienen equivalente OAuth con punto — son solo API key, el espejo de verifactu:write. Todos requieren el módulo de plan control_horario.

Gating por plan y módulo

La mayoría de las tools publicadas solo aplican una comprobación de scope: son accesibles en cuanto la credencial tiene el scope requerido. Dos familias además están limitadas por módulo. Las tools de Pagos y pasarelas mapean sus scopes (stripe_autoinvoicing:*, payouts:read) al módulo integration_stripe. Las tools de personal (Empleados, Asientos de empleado, Horarios de trabajo, Control horario, Ausencias, Presencia, Festivos) mapean sus scopes (employees:*, time_entries:*, absences:*, work_schedules:*, presence:read, holidays:read, payroll_exports:*) al módulo control_horario. Cuando el plan de la empresa no incluye el módulo, el servidor oculta esas tools de tools/list y devuelve module_not_in_plan (-32005) ante una llamada directa.

• Los límites de uso del plan (p. ej. cuotas mensuales de documentos) se aplican en el momento de la llamada y se manifiestan como plan_limit_exceeded (-32004). Consulta Errores y límites de peticiones.

Toda la superficie pública MCP también requiere que la empresa tenga un plan de Factuarea activo — el acceso a la API está incluido en todos los planes; de lo contrario, cada llamada devuelve addon_not_active (-32007).