Xero MCP Troubleshooting: invalid_scope & invalid_client

Q: Why does Xero MCP return invalid_scope?

The scopes in XERO_SCOPES usually do not match the scopes authorised in Xero Developer, or the Custom Connection is using a different scope model than expected.

Xero MCP setup usually fails in a small number of places: scopes, credentials, app type, local stdio configuration, or the wrong Xero organisation.

Use this guide as a checklist. Start with the safest test: Xero’s built-in Demo Company and one read-only organisation-details request.

Quick Diagnostic Table

Error or symptom	First thing to check
`invalid_scope`	`XERO_SCOPES` matches Xero Developer exactly
`invalid_client`	Client ID and Secret are from the authorised Custom Connection
No Xero tools appear	MCP client command, args, environment variables, restart
Server shows no terminal output	Normal for stdio; test from the MCP client
ChatGPT cannot connect	ChatGPT needs remote HTTPS MCP, not local stdio
Subscription required	Confirm Demo Company or Custom Connection eligibility

`invalid_scope`

This usually means the scope list in your MCP configuration does not match the scopes authorised in Xero Developer.

Check:

Spaces between scopes, not commas
No quotes copied into a UI field unless the UI adds them itself
The Custom Connection has been authorised after scope changes
You are using read scopes for read tests
The connection was created before or after Xero’s April 2026 Custom Connection scope change

For the first test, simplify to:

XERO_SCOPES=accounting.settings.read

Then authorise the same scope in Xero Developer and restart your MCP client.

`invalid_client`

This means the server cannot authenticate with Xero using the credentials you supplied.

Check:

The Client ID and Client Secret are copied from the same Xero app.
The secret has not been rotated.
There are no leading or trailing spaces.
The values are stored as environment variables, not pasted into the wrong config field.
You are not mixing credentials from a different Custom Connection.

Use placeholders in docs and screenshots:

XERO_CLIENT_ID=YOUR_XERO_CLIENT_ID
XERO_CLIENT_SECRET=YOUR_XERO_CLIENT_SECRET

Never commit real values to source control.

No Xero Tools Appear

If your MCP client opens but no Xero tools appear, the client may not be launching the server.

For local clients, confirm:

Node.js and npm are installed.
The command is npx or the absolute path to npx.
The args are separate values: -y and @xeroapi/xero-mcp-server@latest.
Environment variables are present in the MCP client config.
The app was fully restarted after saving the MCP config.

For a cloned local build, confirm:

npm install
npm run build
ls -l dist/index.js

Then use an absolute path to dist/index.js.

ChatGPT Cannot Connect to the Xero MCP Server

ChatGPT does not directly launch a local stdio server from your computer. It needs a remote MCP endpoint over HTTPS, or a supported secure tunnel for development.

If you only have this local config, it is for clients like Claude Desktop or Codex:

{
  "command": "npx",
  "args": ["-y", "@xeroapi/xero-mcp-server@latest"]
}

For ChatGPT, use How to Connect Xero MCP to ChatGPT.

`Subscription required to connect`

For first tests, confirm you selected Xero’s built-in Demo Company, not a normal organisation renamed “Demo Company.” Xero says Custom Connections can be tested with the demo company at no charge.

For a real organisation, this message can mean the required Custom Connection setup or subscription is not available for that organisation.

Xero Demo Company authorisation screen Confirm the organisation during authorisation. Use the built-in Demo Company for the first test before connecting production books.

Custom Connection Re-Authorisation Problems

Changing a Custom Connection can deactivate it until it is re-authorised. This often appears after:

Adding scopes
Removing old broad scopes
Changing the authorising user
Switching connection details

If the connection worked yesterday and fails today, check whether someone changed the Custom Connection in Xero Developer.

Payroll Tools Do Not Work

Payroll support depends on the region and the scopes available to the organisation. The official Xero MCP README notes that payroll-specific queries should use a Demo Company region where payroll is supported, such as NZ or UK.

Do not use payroll scopes in a general finance Q&A pilot unless payroll access has been explicitly approved.

Reports Return Errors

Reports need the matching report scope. Xero also adds and changes API validation over time. For example, Xero enforces a 200 tracking-column limit on the Profit and Loss report, and requests that exceed it return a 400 error. If a report fails, narrow the request and check whether the selected tracking options or report parameters are too broad.

Clean Restart Checklist

When in doubt:

Reduce scopes to accounting.settings.read.
Re-authorise the Xero Custom Connection.
Replace the Client ID and Client Secret in the MCP client.
Fully quit and reopen the MCP client.
Test only list-organisation-details.
Add one scope group at a time.

FAQ

Why does Xero MCP return invalid_scope?

The scopes in XERO_SCOPES usually do not match the scopes authorised in Xero Developer, or the Custom Connection is using a different scope model than expected.

Why does Xero MCP return invalid_client?

The Client ID or Client Secret is wrong, belongs to a different app, was rotated, or is not from the Custom Connection you authorised.

Why does Xero show Subscription required to connect?

For first tests, confirm you are using Xero’s built-in Demo Company. Real organisations may need the required Custom Connection subscription or eligible setup.

For a clean setup path, go back to How to Set Up Xero MCP Server (Developer Guide). For scope planning, read Xero MCP Scopes Explained.