Xero MCP Scopes Explained

Q: What scope should I use first for Xero MCP?

Use accounting.settings.read for the first Demo Company test. It lets the server read basic organisation details without granting invoice, payment, bank transaction, or write access.

Xero MCP scopes decide what the AI can reach. They are not a detail to clean up later. If the scope list is too broad, your assistant may have access to records or actions that the user never intended to expose.

This guide explains the practical scope choices for Xero MCP, especially when using Xero’s official MCP server.

The Safest First Scope

Start with:

accounting.settings.read

This scope is enough to test a harmless organisation-details request. It should be your first Demo Company test because it proves that authentication works without opening invoice, payment, bank transaction, journal, or payroll data.

Xero Custom Connection scope configuration page Use the scope selector deliberately. Do not copy broad or write-capable screenshots into production.

Read Scopes Versus Write Scopes

In Xero’s Accounting API, read scopes are usually explicit:

accounting.invoices.read
accounting.payments.read
accounting.banktransactions.read
accounting.manualjournals.read

The matching scopes without .read are broader and can support write-capable operations:

accounting.invoices
accounting.payments
accounting.banktransactions
accounting.manualjournals

For most self-serve finance Q&A, choose read scopes. Write-capable scopes belong in controlled workflows with a trusted operator, not in a broad “ask anything about Xero” rollout.

Common Scope Groups for Xero MCP

Use this as a planning map, not a copy-paste list.

Goal	Starting scopes
Test organisation details	`accounting.settings.read`
Read invoice lists and balances	`accounting.settings.read accounting.invoices.read`
Read contacts	The current contact scope required by Xero, listed in the official MCP server docs as `accounting.contacts`
Read payments	`accounting.settings.read accounting.payments.read`
Read bank transactions	`accounting.settings.read accounting.banktransactions.read`
Read reports	Add the exact report scope required by the official server, such as `accounting.reports.aged.read`, `accounting.reports.balancesheet.read`, `accounting.reports.profitandloss.read`, or `accounting.reports.trialbalance.read`
Payroll tests	Add payroll scopes only for the supported country and approved user group

The exact scope names available to your app can vary with Xero’s granular-scope rollout and the type of connection. Always confirm in Xero Developer before publishing setup instructions internally.

Granular Scopes After April 2026

Xero introduced granular Accounting API scopes in 2026. For Custom Connections created from 29 April 2026, new granular scopes apply. Xero’s FAQ also notes that older broad scopes can continue during the transition if they remain in an existing configuration, but removed broad scopes cannot be re-added.

That means two Xero MCP setups can behave differently:

An older Custom Connection may still have broad scopes.
A newer Custom Connection uses granular scopes.
Changing an activated Custom Connection can require re-authorisation.

When troubleshooting a scope problem, always check when the Custom Connection was created and whether it was edited after activation.

The Official Xero MCP Server Scope Behavior

The official Xero MCP server supports two auth modes:

Custom Connections with Client ID and Client Secret
Bearer token mode for clients that handle OAuth at runtime

The server documentation says Custom Connections require different scope sets depending on when the connection was created. It also allows overriding scopes with the XERO_SCOPES environment variable.

Example:

XERO_SCOPES=accounting.settings.read accounting.invoices.read

Keep XERO_SCOPES aligned with the scopes actually authorised in Xero Developer. If they do not match, expect invalid_scope or missing tools.

Scopes to Avoid in a First Test

Do not use these for the first connectivity check:

Invoice write scopes
Payment write scopes
Bank transaction write scopes
Manual journal write scopes
Payroll scopes
Deprecated broad scopes unless you are maintaining an existing connection

First prove the server can read organisation details. Then add exactly one data area at a time.

A Practical Scope Review Checklist

Before using Xero MCP against real data, answer these:

Which tools will users actually need?
Which scopes does each tool require?
Does any scope allow create, update, approve, or delete behaviour?
Is this a Custom Connection or a multi-tenant OAuth app?
Who can edit the scope list later?
Will changes force re-authorisation?
Where is the final approved scope list documented?

FAQ

What scope should I use first for Xero MCP?

Use accounting.settings.read for the first Demo Company test. It lets the server read basic organisation details without granting invoice, payment, bank transaction, or write access.

Are Xero MCP scopes read-only by default?

No. Xero scopes are explicit permissions. Read scopes usually end in .read. Scopes without .read often allow create or update behaviour for that area.

What changed for Xero Custom Connection scopes in 2026?

Xero introduced granular Accounting API scopes in 2026. New Custom Connections from 29 April 2026 use granular scopes, while older broad scopes continue for existing configurations during Xero’s transition window.

Next, see Xero MCP Custom Connections vs OAuth Apps or the full Xero MCP guide.