Support granular OAuth scopes for new Custom Connections (#139)

* add support for granular scopes

* Update README and xero-client to support granular scopes for custom connections

* Rename scope constants for clarity

* Improve error handling for token retrieval in CustomConnectionsXeroClient

* remove redundant scopes

* Make custom connection scopes configurable (#136)

* Make custom connections scopes configurable
* update README

* Update README.md with new release date

---------

Co-authored-by: Amanda Ducrou <amanda@scopego.co>

Author: saleem-aasim-xero

README.md

@@ -47,7 +47,18 @@ It is also the recommended approach if you are integrating this into 3rd party M
 
 Set up a Custom Connection following these instructions: https://developer.xero.com/documentation/guides/oauth2/custom-connections/
 
-Currently the following scopes are required for all sessions: [scopes](src/clients/xero-client.ts#L91-L92)
+##### Required Scopes
+
+Custom connections require different scopes depending on when they were created. **All scopes in the relevant list must be added to your custom connection:**
+
+| Custom Connection Created | Required Scopes |
+|---------------------------|-----------------|
+| Before Apr 29, 2026 | [SCOPES_V1](src/clients/xero-client.ts#L82-L90) (bundled permissions) |
+| From Apr 29, 2026 | [SCOPES_V2](src/clients/xero-client.ts#L93-L112) (granular permissions) |
+
+> **Note:** The MCP server automatically tries V1 scopes first and falls back to V2 if needed.
+> 
+> You can override these by setting the `XERO_SCOPES` environment variable to a space-separated list of scopes.
 
 ##### Integrating the MCP server with Claude Desktop
 
@@ -61,13 +72,16 @@ To add the MCP server to Claude go to Settings > Developer > Edit config and add
       "args": ["-y", "@xeroapi/xero-mcp-server@latest"],
       "env": {
         "XERO_CLIENT_ID": "your_client_id_here",
-        "XERO_CLIENT_SECRET": "your_client_secret_here"
+        "XERO_CLIENT_SECRET": "your_client_secret_here",
+        "XERO_SCOPES": "accounting.invoices accounting.contacts accounting.settings"
       }
     }
   }
 }
 ```
 
+The `XERO_SCOPES` variable is optional. If omitted, the default scopes listed above will be used.
+
 NOTE: If you are using [Node Version Manager](https://github.com/nvm-sh/nvm) `"command": "npx"` section change it to be the full path to the executable, ie: `your_home_directory/.nvm/versions/node/v22.14.0/bin/npx` on Mac / Linux or `"your_home_directory\\.nvm\\versions\\node\\v22.14.0\\bin\\npx"` on Windows
 
 #### 2. Bearer Token

src/clients/xero-client.ts

@@ -78,6 +78,34 @@ class CustomConnectionsXeroClient extends MCPXeroClient {
   private readonly clientId: string;
   private readonly clientSecret: string;
 
+  // Legacy scopes (deprecated but still supported for existing apps)
+  private readonly XERO_DEFAULT_AUTH_SCOPES_V1 = [
+    "accounting.transactions",
+    "accounting.contacts",
+    "accounting.settings",
+    "accounting.reports.read",
+    "payroll.settings",
+    "payroll.employees",
+    "payroll.timesheets",
+  ].join(" ");
+
+  // Granular scopes (required for new apps)
+  private readonly XERO_DEFAULT_AUTH_SCOPES_V2 = [
+    "accounting.invoices",
+    "accounting.payments",
+    "accounting.banktransactions",
+    "accounting.manualjournals",
+    "accounting.reports.aged.read",
+    "accounting.reports.balancesheet.read",
+    "accounting.reports.profitandloss.read",
+    "accounting.reports.trialbalance.read",
+    "accounting.contacts",
+    "accounting.settings",
+    "payroll.settings",
+    "payroll.employees",
+    "payroll.timesheets",
+  ].join(" ");
+
   constructor(config: {
     clientId: string;
     clientSecret: string;
@@ -88,49 +116,80 @@ class CustomConnectionsXeroClient extends MCPXeroClient {
     this.clientSecret = config.clientSecret;
   }
 
+  private formatTokenError(error: unknown, context: string): Error {
+    const axiosError = error as AxiosError;
+    const data = axiosError.response?.data;
+    const message =
+      typeof data === "object" ? JSON.stringify(data) : data || axiosError.message;
+    return new Error(`Failed to get Xero token${context}: ${message}`);
+  }
+
   public async getClientCredentialsToken(): Promise<TokenSet> {
-    const scope =
-      "accounting.transactions accounting.contacts accounting.settings accounting.reports.read payroll.settings payroll.employees payroll.timesheets";
+    // If XERO_SCOPES is set, use that
+    if (process.env.XERO_SCOPES) {                                                                                                                                                     
+      try {
+        return await this.requestToken(process.env.XERO_SCOPES);
+      } catch (envError) {
+        throw this.formatTokenError(envError, " with XERO_SCOPES");
+      }
+    }
+
+    // Else if XERO_SCOPES is not set, try V1 scopes first (for existing apps), fallback to V2 scopes (for new apps) only on invalid_scope error
+    try {
+      return await this.requestToken(this.XERO_DEFAULT_AUTH_SCOPES_V1);
+    } catch (error) {
+      const axiosError = error as AxiosError;
+      const isInvalidScope =
+        axiosError.response?.status === 400 &&
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (axiosError.response?.data as any)?.error === "invalid_scope";
+
+      if (!isInvalidScope) {
+        throw this.formatTokenError(error, " with V1 scopes");
+      }
+
+      try {
+        return await this.requestToken(this.XERO_DEFAULT_AUTH_SCOPES_V2);
+      } catch (v2Error) {
+        throw this.formatTokenError(v2Error, " with V2 scopes");
+      }
+    }
+  }
+
+  private async requestToken(scope: string): Promise<TokenSet> {
     const credentials = Buffer.from(
       `${this.clientId}:${this.clientSecret}`,
     ).toString("base64");
 
-    try {
-      const response = await axios.post(
-        "https://identity.xero.com/connect/token",
-        `grant_type=client_credentials&scope=${encodeURIComponent(scope)}`,
-        {
-          headers: {
-            Authorization: `Basic ${credentials}`,
-            "Content-Type": "application/x-www-form-urlencoded",
-            Accept: "application/json",
-          },
-        },
-      );
-
-      // Get the tenant ID from the connections endpoint
-      const token = response.data.access_token;
-      const connectionsResponse = await axios.get(
-        "https://api.xero.com/connections",
-        {
-          headers: {
-            Authorization: `Bearer ${token}`,
-            Accept: "application/json",
-          },
+    const response = await axios.post(
+      "https://identity.xero.com/connect/token",
+      `grant_type=client_credentials&scope=${encodeURIComponent(scope)}`,
+      {
+        headers: {
+          Authorization: `Basic ${credentials}`,
+          "Content-Type": "application/x-www-form-urlencoded",
+          Accept: "application/json",
         },
-      );
+      },
+    );
 
-      if (connectionsResponse.data && connectionsResponse.data.length > 0) {
-        this.tenantId = connectionsResponse.data[0].tenantId;
-      }
+    // Get the tenant ID from the connections endpoint
+    const token = response.data.access_token;
+    const connectionsResponse = await axios.get(
+      "https://api.xero.com/connections",
+      {
+        headers: {
+          Authorization: `Bearer ${token}`,
+          Accept: "application/json",
+        },
+      },
+    );
 
-      return response.data;
-    } catch (error) {
-      const axiosError = error as AxiosError;
-      throw new Error(
-        `Failed to get Xero token: ${axiosError.response?.data || axiosError.message}`,
-      );
+    if (connectionsResponse.data && connectionsResponse.data.length > 0) {
+      this.tenantId = connectionsResponse.data[0].tenantId;
     }
+
+    return response.data;
   }
 
   public async authenticate() {