feat(core): support user defined fallback protocol array

anubhav756 · anubhav756 · commit c648adcc13be · 2026-07-04T04:16:39.000+05:30
diff --git a/packages/toolbox-adk/src/toolbox_adk/client.ts b/packages/toolbox-adk/src/toolbox_adk/client.ts
@@ -46,7 +46,7 @@ export class ToolboxClient {
     url: string,
     session?: AxiosInstance | null,
     clientHeaders?: ClientHeadersConfig | null,
-    protocol: Protocol = Protocol.MCP,
+    protocol: Protocol | Protocol[] = Protocol.MCP,
   ) {
     this.coreClient = new CoreToolboxClient(
       url,
diff --git a/packages/toolbox-core/README.md b/packages/toolbox-core/README.md
@@ -69,11 +69,23 @@ The core package provides a framework-agnostic way to interact with your MCP Too
 
 - [Transport Protocols](https://mcp-toolbox.dev/documentation/connect-to/toolbox-sdks/javascript-sdk/core/#transport-protocols)
 - [Loading Tools](https://mcp-toolbox.dev/documentation/connect-to/toolbox-sdks/javascript-sdk/core/#loading-tools)
+
 - [Invoking Tools](https://mcp-toolbox.dev/documentation/connect-to/toolbox-sdks/javascript-sdk/core/#invoking-tools)
 - [Client to Server Authentication](https://mcp-toolbox.dev/documentation/connect-to/toolbox-sdks/javascript-sdk/core/#client-to-server-authentication)
 - [Authenticating Tools](https://mcp-toolbox.dev/documentation/connect-to/toolbox-sdks/javascript-sdk/core/#authenticating-tools)
 - [Binding Parameter Values](https://mcp-toolbox.dev/documentation/connect-to/toolbox-sdks/javascript-sdk/core/#binding-parameter-values)
 
+## Protocol Negotiation
+
+By default, the client negotiates the newest protocol version supported by the server. You can provide a custom list of supported protocols to restrict negotiation to specific versions or a single version. Ensure you pass the [`Protocol`](src/toolbox_core/protocol.ts) enum constants. Both `Protocol.MCP_LATEST` and `Protocol.MCP_DRAFT` are supported as well.
+
+```javascript
+import { ToolboxClient, Protocol } from '@toolbox-sdk/core';
+
+// Pass a custom list of supported protocols as the fourth argument
+const client = new ToolboxClient(URL, undefined, undefined, [Protocol.MCP_LATEST, Protocol.MCP_DRAFT]);
+```
+
 # Contributing
 
 Contributions are welcome! Please refer to the [DEVELOPER.md](./DEVELOPER.md)
diff --git a/packages/toolbox-core/src/toolbox_core/client.ts b/packages/toolbox-core/src/toolbox_core/client.ts
@@ -51,6 +51,7 @@ class ToolboxClient {
   #url: string;
   #transport: ITransport;
   #clientHeaders: ClientHeadersConfig;
+  #supportedProtocols: string[] | undefined;
 
   /**
    * The negotiated protocol version currently in use.
@@ -72,21 +73,53 @@ class ToolboxClient {
     url: string,
     session?: AxiosInstance | null,
     clientHeaders?: ClientHeadersConfig | null,
-    protocol: Protocol = Protocol.MCP,
+    protocol: Protocol | Protocol[] | string[] | string = Protocol.MCP,
     clientName?: string,
     clientVersion?: string,
   ) {
     this.#url = url;
     this.#clientHeaders = clientHeaders || {};
     warnIfHttpAndHeaders(url, this.#clientHeaders);
-    if (!getSupportedMcpVersions().includes(protocol)) {
-      throw new Error(`Unsupported protocol version: ${protocol}`);
+    
+    let initialProtocol: Protocol;
+    if (Array.isArray(protocol)) {
+      if (protocol.length === 0) {
+        throw new Error('Protocol array cannot be empty');
+      }
+      
+      const globalSupported = getSupportedMcpVersions();
+      
+      for (const p of protocol) {
+        if (!globalSupported.includes(p as Protocol)) {
+          throw new Error(`Invalid protocol version '${p}'. Must be one of: ${globalSupported.join(', ')}`);
+        }
+      }
+      
+      const sorted: string[] = [];
+      
+      for (const globalVer of globalSupported) {
+        if (protocol.includes(globalVer as any)) {
+          sorted.push(globalVer);
+        }
+      }
+      
+      if (sorted.length === 0) {
+        throw new Error('None of the provided protocols are supported');
+      }
+      
+      this.#supportedProtocols = sorted;
+      initialProtocol = sorted[0] as Protocol; // Start with the highest requested version
+    } else {
+      initialProtocol = protocol as Protocol;
+      if (!getSupportedMcpVersions().includes(initialProtocol)) {
+        throw new Error(`Unsupported protocol version: ${initialProtocol}`);
+      }
     }
 
-    this.#transport = this.#createTransport(
+    this.#transport = this.#createTransportWithProtocols(
       url,
       session || undefined,
-      protocol,
+      initialProtocol,
       clientName,
       clientVersion,
     );
@@ -146,6 +179,20 @@ class ToolboxClient {
     }
   }
 
+  #createTransportWithProtocols(
+    url: string,
+    session: AxiosInstance | undefined,
+    protocol: Protocol,
+    clientName?: string,
+    clientVersion?: string,
+  ): ITransport {
+    const transport = this.#createTransport(url, session, protocol, clientName, clientVersion);
+    if (this.#supportedProtocols) {
+      transport.supportedProtocols = this.#supportedProtocols;
+    }
+    return transport;
+  }
+
   /**
    * Resolves client headers from their provider functions.
    * @returns {Promise<Record<string, string>>} A promise that resolves to the resolved headers.
@@ -217,6 +264,42 @@ class ToolboxClient {
     return {tool, usedAuthKeys, usedBoundKeys};
   }
 
+  async #executeWithFallback<T>(action: () => Promise<T>): Promise<T> {
+    try {
+      return await action();
+    } catch (e: unknown) {
+      if (e instanceof ProtocolNegotiationError) {
+        const serverVersion = e.fallbackVersion as string;
+        let mutuallySupported: string[] | null = null;
+
+        if (this.#supportedProtocols.includes(serverVersion as Protocol)) {
+          mutuallySupported = [serverVersion];
+        } else {
+          const allVersions = getSupportedMcpVersions();
+          if (allVersions.includes(serverVersion as Protocol)) {
+            const idx = allVersions.indexOf(serverVersion as Protocol);
+            const serverSupported = allVersions.slice(idx);
+            mutuallySupported = this.#supportedProtocols.filter(v =>
+              serverSupported.includes(v),
+            );
+          }
+        }
+
+        if (!mutuallySupported || mutuallySupported.length === 0) {
+          throw new Error('No mutually supported protocol version');
+        }
+
+        this.#transport = this.#createTransportWithProtocols(
+          this.#url,
+          undefined,
+          mutuallySupported[0] as Protocol,
+        );
+        return await action();
+      }
+      throw e;
+    }
+  }
+
   /**
    * Asynchronously loads a tool from the server.
    * Retrieves the schema for the specified tool from the Toolbox server and
@@ -238,21 +321,10 @@ class ToolboxClient {
   ): Promise<ToolboxTool> {
     warnIfHttpAndHeaders(this.#transport.baseUrl, authTokenGetters);
     const headers = await this.#resolveClientHeaders();
-    let manifest;
-    try {
-      manifest = await this.#transport.toolGet(name, headers);
-    } catch (e: unknown) {
-      if (e instanceof ProtocolNegotiationError) {
-        this.#transport = this.#createTransport(
-          this.#url,
-          undefined,
-          e.fallbackVersion as Protocol,
-        );
-        manifest = await this.#transport.toolGet(name, headers);
-      } else {
-        throw e;
-      }
-    }
+    const manifest = await this.#executeWithFallback(() =>
+      this.#transport.toolGet(name, headers),
+    );
+
 
     if (
       manifest.tools &&
@@ -323,21 +395,10 @@ class ToolboxClient {
     const toolsetName = name || '';
     const headers = await this.#resolveClientHeaders();
 
-    let manifest;
-    try {
-      manifest = await this.#transport.toolsList(toolsetName, headers);
-    } catch (e: unknown) {
-      if (e instanceof ProtocolNegotiationError) {
-        this.#transport = this.#createTransport(
-          this.#url,
-          undefined,
-          e.fallbackVersion as Protocol,
-        );
-        manifest = await this.#transport.toolsList(toolsetName, headers);
-      } else {
-        throw e;
-      }
-    }
+    const manifest = await this.#executeWithFallback(() =>
+      this.#transport.toolsList(toolsetName, headers),
+    );
+
     const tools: ToolboxTool[] = [];
 
     const overallUsedAuthKeys: Set<string> = new Set();
diff --git a/packages/toolbox-core/src/toolbox_core/mcp/transportBase.ts b/packages/toolbox-core/src/toolbox_core/mcp/transportBase.ts
@@ -45,6 +45,7 @@ export abstract class McpHttpTransportBase implements ITransport {
   protected _mcpBaseUrl: string;
   protected _protocolVersion: string;
   protected _serverVersion: string | null = null;
+  public supportedProtocols?: string[];
 
   protected _manageSession: boolean;
   protected _session: AxiosInstance;
diff --git a/packages/toolbox-core/src/toolbox_core/mcp/v20250618/mcp.ts b/packages/toolbox-core/src/toolbox_core/mcp/v20250618/mcp.ts
@@ -16,7 +16,7 @@ import {AxiosError} from 'axios';
 import {McpHttpTransportBase} from '../transportBase.js';
 import * as types from './types.js';
 
-import {ZodManifest} from '../../protocol.js';
+import {ZodManifest, Protocol, getSupportedMcpVersions} from '../../protocol.js';
 import {logApiError, ProtocolNegotiationError} from '../../errorUtils.js';
 import {warnIfHttpAndHeaders} from '../../utils.js';
 
@@ -122,6 +122,11 @@ export class McpHttpTransportV20250618 extends McpHttpTransportBase {
         const errObj = errorData.error;
 
         if (typeof errObj === 'string' && errObj.includes('invalid protocol version')) {
+          const supported = this.supportedProtocols || getSupportedMcpVersions();
+          const currentIdx = supported.indexOf(this._protocolVersion as Protocol);
+          if (currentIdx !== -1 && currentIdx + 1 < supported.length) {
+            throw new ProtocolNegotiationError(supported[currentIdx + 1]);
+          }
           throw new ProtocolNegotiationError(Protocol.MCP_v20250618);
         }
 
@@ -136,7 +141,7 @@ export class McpHttpTransportV20250618 extends McpHttpTransportBase {
             const supported = (errData as Record<string, unknown>).supported;
             if (Array.isArray(supported) && supported.length > 0) {
               let mutuallySupportedVersion: string | null = null;
-              for (const ourVer of getSupportedMcpVersions()) {
+              for (const ourVer of (this.supportedProtocols || getSupportedMcpVersions())) {
                 if (supported.includes(ourVer)) {
                   mutuallySupportedVersion = ourVer;
                   break;
diff --git a/packages/toolbox-core/src/toolbox_core/mcp/v20251125/mcp.ts b/packages/toolbox-core/src/toolbox_core/mcp/v20251125/mcp.ts
@@ -16,7 +16,7 @@ import {AxiosError} from 'axios';
 import {McpHttpTransportBase} from '../transportBase.js';
 import * as types from './types.js';
 
-import {ZodManifest} from '../../protocol.js';
+import {ZodManifest, Protocol, getSupportedMcpVersions} from '../../protocol.js';
 import {logApiError, ProtocolNegotiationError} from '../../errorUtils.js';
 import {warnIfHttpAndHeaders} from '../../utils.js';
 
@@ -122,6 +122,11 @@ export class McpHttpTransportV20251125 extends McpHttpTransportBase {
         const errObj = errorData.error;
 
         if (typeof errObj === 'string' && errObj.includes('invalid protocol version')) {
+          const supported = this.supportedProtocols || getSupportedMcpVersions();
+          const currentIdx = supported.indexOf(this._protocolVersion as Protocol);
+          if (currentIdx !== -1 && currentIdx + 1 < supported.length) {
+            throw new ProtocolNegotiationError(supported[currentIdx + 1]);
+          }
           throw new ProtocolNegotiationError(Protocol.MCP_v20250618);
         }
 
@@ -136,7 +141,7 @@ export class McpHttpTransportV20251125 extends McpHttpTransportBase {
             const supported = (errData as Record<string, unknown>).supported;
             if (Array.isArray(supported) && supported.length > 0) {
               let mutuallySupportedVersion: string | null = null;
-              for (const ourVer of getSupportedMcpVersions()) {
+              for (const ourVer of (this.supportedProtocols || getSupportedMcpVersions())) {
                 if (supported.includes(ourVer)) {
                   mutuallySupportedVersion = ourVer;
                   break;
diff --git a/packages/toolbox-core/src/toolbox_core/mcp/v20260618/mcp.ts b/packages/toolbox-core/src/toolbox_core/mcp/v20260618/mcp.ts
@@ -123,7 +123,7 @@ export class McpHttpTransportV20260618 extends McpHttpTransportBase {
             const supported = (err.data as Record<string, unknown>).supported;
             if (Array.isArray(supported) && supported.length > 0) {
               let mutuallySupportedVersion: string | null = null;
-              for (const ourVer of getSupportedMcpVersions()) {
+              for (const ourVer of (this.supportedProtocols || getSupportedMcpVersions())) {
                 if (supported.includes(ourVer)) {
                   mutuallySupportedVersion = ourVer;
                   break;
@@ -172,6 +172,11 @@ export class McpHttpTransportV20260618 extends McpHttpTransportBase {
         const errObj = errorData.error;
 
         if (typeof errObj === 'string' && errObj.includes('invalid protocol version')) {
+          const supported = this.supportedProtocols || getSupportedMcpVersions();
+          const currentIdx = supported.indexOf(this._protocolVersion as Protocol);
+          if (currentIdx !== -1 && currentIdx + 1 < supported.length) {
+            throw new ProtocolNegotiationError(supported[currentIdx + 1]);
+          }
           throw new ProtocolNegotiationError(Protocol.MCP_v20250618);
         }
 
@@ -186,7 +191,7 @@ export class McpHttpTransportV20260618 extends McpHttpTransportBase {
             const supported = (errData as Record<string, unknown>).supported;
             if (Array.isArray(supported) && supported.length > 0) {
               let mutuallySupportedVersion: string | null = null;
-              for (const ourVer of getSupportedMcpVersions()) {
+              for (const ourVer of (this.supportedProtocols || getSupportedMcpVersions())) {
                 if (supported.includes(ourVer)) {
                   mutuallySupportedVersion = ourVer;
                   break;
diff --git a/packages/toolbox-core/src/toolbox_core/transport.types.ts b/packages/toolbox-core/src/toolbox_core/transport.types.ts
@@ -26,6 +26,11 @@ export interface ITransport {
    */
   readonly protocolVersion: string;
 
+  /**
+   * The list of supported protocols that the client claims to support.
+   */
+  supportedProtocols?: string[];
+
   /**
    * The base URL for the transport.
    */
diff --git a/packages/toolbox-core/test/e2e/test.e2e.ts b/packages/toolbox-core/test/e2e/test.e2e.ts
@@ -24,7 +24,9 @@ import {CustomGlobal} from './types.js';
 import {authTokenGetter} from './utils.js';
 import {ZodTypeAny} from 'zod';
 
-const testBaseUrls = ['http://localhost:5000', 'http://localhost:5001'];
+const TOOLBOX_SERVER_URL_STABLE = 'http://localhost:5000';
+const TOOLBOX_SERVER_URL_DRAFT = 'http://localhost:5001';
+const testBaseUrls = [TOOLBOX_SERVER_URL_STABLE, TOOLBOX_SERVER_URL_DRAFT];
 
 testBaseUrls.forEach(testBaseUrl => {
   describe.each(getSupportedMcpVersions())(
@@ -662,13 +664,49 @@ testBaseUrls.forEach(testBaseUrl => {
       expect(typeof response).toBe('string');
       expect(response).toContain('row1');
 
-      if (testBaseUrl === 'http://localhost:5001') {
+      if (testBaseUrl === TOOLBOX_SERVER_URL_DRAFT) {
         // 5001 supports draft, so no fallback
         expect(client.protocolVersion).toBe(Protocol.MCP_v2026_DRAFT);
       } else {
         // 5000 does not support draft, so fallback
         expect(client.protocolVersion).not.toBe(Protocol.MCP_v2026_DRAFT);
       }
     });
+
+    it('should correctly negotiate Protocol.MCP_LATEST', async () => {
+      const client = new ToolboxClient(
+        testBaseUrl,
+        undefined,
+        undefined,
+        Protocol.MCP_LATEST,
+      );
+
+      const tool = await client.loadTool('get-n-rows');
+      const response = await tool({num_rows: '1'});
+      expect(typeof response).toBe('string');
+      expect(response).toContain('row1');
+
+      expect(client.protocolVersion).toBe(Protocol.MCP_LATEST);
+    });
+
+    it('should correctly negotiate with a custom list [Protocol.MCP_v20241105, Protocol.MCP_v20250326, Protocol.MCP_LATEST, Protocol.MCP_DRAFT]', async () => {
+      const client = new ToolboxClient(
+        testBaseUrl,
+        undefined,
+        undefined,
+        [Protocol.MCP_v20241105, Protocol.MCP_v20250326, Protocol.MCP_LATEST, Protocol.MCP_DRAFT],
+      );
+
+      const tool = await client.loadTool('get-n-rows');
+      const response = await tool({num_rows: '1'});
+      expect(typeof response).toBe('string');
+      expect(response).toContain('row1');
+
+      if (testBaseUrl === TOOLBOX_SERVER_URL_DRAFT) {
+        expect(client.protocolVersion).toBe(Protocol.MCP_DRAFT);
+      } else {
+        expect(client.protocolVersion).toBe(Protocol.MCP_LATEST);
+      }
+    });
   });
 });
diff --git a/packages/toolbox-core/test/mcp/test.v20250618.ts b/packages/toolbox-core/test/mcp/test.v20250618.ts
diff --git a/packages/toolbox-core/test/mcp/test.v20251125.ts b/packages/toolbox-core/test/mcp/test.v20251125.ts
diff --git a/packages/toolbox-core/test/test.client.ts b/packages/toolbox-core/test/test.client.ts
