Scopes & permissions

Every MCP tool declares the scope a credential must hold to call it. Scopes work slightly differently per channel:

• API keys are created directly with fine-grained scopes (resource:action, e.g. invoices:read) — the same closed catalog the REST API uses. You can also grant the super-scope *.
• OAuth tokens are granted dotted scopes (resource.action, e.g. invoices.read) on the consent screen. The server translates these to the fine-grained scopes automatically, so both channels enforce the same set at the tool boundary.

OAuth consent catalog

These are the scopes a user can grant a third-party app on the consent screen. There are 62 simple scopes plus 3 macros.

Simple scopes

Each grants one capability. The Maps to column shows the fine-grained scope the tools enforce — the consent layer translates dotted OAuth scopes to these automatically. The Sensitive column marks scopes the consent screen flags and does not pre-check.

Profile

Contacts

Catalog — products, price lists, series, taxes

Sales — invoices, quotes, pro-formas, delivery notes

Purchases

Recurring invoices

Compliance and tax reports

Webhooks

Workforce — control horario

Employee, time-tracking, absence, work-schedule, presence, holiday and payroll-export data. Every workforce scope is sensitive (employee PII and compliance data) and requires the control_horario plan module — see Plan & module gating. Reads, employees.write and payroll-export generation are grantable on the consent screen; the privileged write and transition actions have no OAuth dotted scope and are API-key-only (listed under the fine-grained scopes below).

Automations

Automation rules and their run history. Every automation scope is sensitive: a rule can send emails and fire webhooks on the account owner's behalf, and the run history carries the business payloads its actions moved (amounts, recipients, outcomes). All three require the automations plan module — see Plan & module gating. Reading and writing rules and reading the run history are grantable on the consent screen; deleting a rule is not — automations:delete has no OAuth dotted scope and is API-key-only (listed under the fine-grained scopes below).

automations.read and automation_runs.read are granted separately on purpose. The first one covers the rule book: the rules themselves, their sealed versions, the trigger/action catalog and the dry run that reports what a rule would do without doing it. The second one covers what the rules actually did: every run, its steps, their typed discard reasons and the frozen trigger payload each run carries. An app can read which automations exist without reading the business data every execution touched.

Macro scopes

Convenience bundles that expand to a list of simple scopes at token-issue time. The token persists the expanded scopes — macros are never stored.

The super-scope *

A credential holding * covers every scope — all 457 tools for an API key. It's the equivalent of an owner key. Reserve it for one-off migrations or fully-trusted owner automations; prefer the narrowest scope set for everything else. The super-scope is available to API keys; OAuth consent grants explicit scopes (or macros), never a raw *.

How OAuth scopes become fine scopes

When an OAuth token is issued, its dotted scopes are translated once to the fine-grained catalog the tools enforce. A few reconciliations are worth knowing:

• recurring.* maps to the recurring_invoices:* resource.
• invoices.create_corrective maps to invoices:write (creating is a write).
• invoices.annul maps to invoices:void.
• Lifecycle actions (*.convert, *.sign, *.pause, *.resume, *.generate_now, *.mark_paid, quotes.convert_to_invoice) map to the resource's :transition scope.
• Any read scope on a document also grants the transversal read utilities pdfs:read (download its PDF/receipt) and events:read (its activity log).
• verifactu.write and delivery_notes:gdpr_forget have no OAuth dotted scope — they are unreachable via OAuth by design.

Fine-grained scopes without an OAuth scope (API key only)

A few fine-grained scopes live in the closed resource:action catalog API keys use, but have no dotted OAuth equivalent — they are never granted through a third-party consent screen and are reachable only with an API key. Grant them on the key directly (or via the super-scope *). Some are gated by an integration module — the key's company must then hold the corresponding plan (see Plan & module gating); the rest are first-party account and gestoría scopes.

These power the Payments & gateways tools.

A second group of API-key-only scopes governs first-party account and gestoría management — your own credentials and, for accountancies, the child sub-companies you manage and their API keys. companies:* requires the gestoría plan module; the rest have no module gate.

A third group covers workforce (control horario) write and transition actions. Their read counterparts are OAuth-grantable (see the Workforce consent scopes above), but these privileged scopes have no OAuth dotted equivalent — they are API-key-only, the mirror of verifactu:write. All require the control_horario plan module.

A fourth group is the automation engine's delete scope. Its three siblings — automations.read, automations.write and automation_runs.read — are OAuth-grantable (see the Automations consent scopes above), but removing someone's automation is destructive and cannot be undone through the API, so it stays out of the consent catalog by design — the same call made for verifactu:write. It requires the automations plan module.

A final group covers the remaining first-party catalog and observability tools that have no dotted OAuth consent scope:

Plan & module gating

Most published tools apply only a scope check — they're reachable as soon as the credential holds the required scope. Three families are also module-gated. The Price-list tools map price_lists:* to products. The Payments & gateways tools map their scopes (stripe_autoinvoicing:*, payouts:read, integration_events:*) to the integration_stripe module. The workforce tools (Employees, Employee seats, Work schedules, Time tracking, Absences, Presence, Holidays) map their scopes (employees:*, time_entries:*, absences:*, work_schedules:*, presence:read, holidays:read, payroll_exports:*) to the control_horario module. The Automations tools map their scopes (automations:*, automation_runs:read) to the automations module. When the company's plan lacks the module, the server hides those tools from tools/list and returns module_not_in_plan (-32005) on a direct call.

• Plan usage limits (e.g. monthly document quotas) are enforced at call time and surface as plan_limit_exceeded (-32004). See Errors & rate limits.

The whole public MCP surface also requires the company to have an active Factuarea plan — API access is included in every plan; otherwise every call returns addon_not_active (-32007).

Store permissions

Store management uses stores:read and stores:write; provider-specific scopes are woocommerce_store:read, woocommerce_store:write, shopify_store:read and shopify_store:write. Connection-test operations require the provider write scope. These scopes are assigned to API keys and are outside OAuth consent. See ecommerce stores for the operation matrix.