Xero MCP Custom Connections vs OAuth Apps
Choose the right Xero auth model for MCP: Custom Connections for one organisation, OAuth apps for multi-tenant flows, and hosted options for teams.
On this page +
Xero MCP setup usually starts with one auth decision: Custom Connection or OAuth app.
Both can connect software to Xero, but they fit different jobs. A Custom Connection is good for one organisation and a controlled setup. A normal OAuth app is better when users or customers need to authorise their own Xero organisations.
The Short Answer
| Use case | Best fit |
|---|---|
| Local MCP test with the Demo Company | Custom Connection |
| One company’s internal Xero MCP setup | Custom Connection |
| Several client organisations | OAuth app |
| Public SaaS product | OAuth app |
| ChatGPT or hosted team access | Hosted remote MCP layer or OAuth-backed service |
If you are following How to Set Up Xero MCP Server (Developer Guide), use a Custom Connection first.
What a Xero Custom Connection Is
A Custom Connection is Xero’s one-to-one integration shape for a single organisation. Xero’s FAQ states that a Custom Connection can only connect to one organisation.
For Xero MCP, that simplicity is useful:
- You create a Xero Developer app.
- You choose Custom Connection.
- You select scopes.
- The authorising user approves the connection.
- The MCP server uses Client ID and Client Secret.
There is no normal user-facing OAuth consent flow inside your app. Xero sends the authorising user through the approval flow when the Custom Connection is created or changed.
Custom Connections are a clean first route for one Xero organisation.
What a Normal OAuth App Is
A normal Xero OAuth app is for user-driven authorisation. The app redirects a user to Xero, the user approves scopes, and the app receives tokens. If the app requests offline_access, it can refresh access tokens without the user approving again.
Use this when:
- You support more than one Xero organisation.
- Different users need to connect their own Xero accounts.
- You are building a SaaS product.
- Your MCP server needs runtime auth rather than one fixed Client ID and Secret.
- You need a public or multi-tenant ChatGPT app.
This path is more flexible, but it is also more engineering work.
How This Maps to Xero MCP
The official Xero MCP server supports:
- Custom Connections using
XERO_CLIENT_IDandXERO_CLIENT_SECRET - Bearer token mode using
XERO_CLIENT_BEARER_TOKEN
The Custom Connection route is the recommended local starting point because it is straightforward for one organisation. Bearer token mode is better when another client or service handles OAuth and passes a token to the MCP server.
Key Differences
| Question | Custom Connection | OAuth app |
|---|---|---|
| Number of organisations | One | Many |
| Best for | Internal setup, local test | SaaS, multi-tenant, user auth |
| Token handling | Client credentials style | Access and refresh tokens |
| User consent | Authorisation email/setup flow | OAuth redirect flow |
| MCP fit | Local or internal server | Hosted app or product |
| Complexity | Lower | Higher |
Scope Changes and Re-Authorisation
Scopes matter in both models. For Custom Connections, changing the connection can deactivate it until it is re-authorised. Xero also introduced granular Accounting API scopes in 2026, so newer Custom Connections use a more specific scope model than older broad-scope connections.
Plan scopes before you connect production data. For a first MCP test, use:
accounting.settings.readThen add invoice, payment, contact, report, or payroll scopes only as needed. See Xero MCP Scopes Explained for the scope map.
Which One Should You Choose?
Choose Custom Connection when:
- You are connecting one Xero organisation.
- You are testing with the Demo Company.
- A technical owner will manage the MCP setup.
- You do not need a public app or many customer tenants.
Choose OAuth app when:
- You need many organisations.
- Users need to authorise their own Xero access.
- You are building a hosted MCP endpoint for ChatGPT or another remote client.
- You need refresh-token handling and app-level auth controls.
Choose hosted access when:
- The end users are not developers.
- You need per-user permissions.
- You need audit logging.
- You want read-only answers in Slack, Teams, ChatGPT, Claude, Gemini, or SMS.
FAQ
Should I use a Xero Custom Connection for MCP?
Use a Custom Connection for a one-organisation internal or development setup. It is the simplest route for many local MCP tests.
When should I use a normal Xero OAuth app?
Use a normal OAuth app when you need multiple Xero organisations, user-driven authorisation, refresh tokens, or a product used by many customers.
Can a Xero Custom Connection connect to multiple organisations?
No. Xero states that a Custom Connection can connect to only one organisation.
For setup steps, read How to Set Up Xero MCP Server (Developer Guide). For team access, see Kipper’s Xero MCP connector.