feat: support user-defined fallback protocols array

packages/toolbox-adk/tests/constants.py

@@ -0,0 +1,16 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+TOOLBOX_SERVER_URL_STABLE = "http://localhost:5000"
+TOOLBOX_SERVER_URL_DRAFT = "http://localhost:5001"

packages/toolbox-adk/tests/integration/conftest.py

@@ -29,8 +29,7 @@
 from google.auth import compute_engine
 from google.cloud import secretmanager, storage
 
-TOOLBOX_SERVER_URL_STABLE = "http://localhost:5000"
-TOOLBOX_SERVER_URL_DRAFT = "http://localhost:5001"
+from tests.constants import TOOLBOX_SERVER_URL_DRAFT, TOOLBOX_SERVER_URL_STABLE
 
 
 #### Define Utility Functions

packages/toolbox-adk/tests/integration/test_integration.py

@@ -31,10 +31,9 @@
 from pydantic import ValidationError
 from toolbox_core.protocol import Protocol
 
+from tests.constants import TOOLBOX_SERVER_URL_STABLE
 from toolbox_adk import CredentialStrategy, ToolboxTool, ToolboxToolset
 
-TOOLBOX_SERVER_URL = "http://localhost:5000"
-
 pytestmark = pytest.mark.usefixtures("patch_toolbox_client_url")
 
 # Ensure TOOLBOX_VERSION is set for the fixture
@@ -54,7 +53,7 @@ async def test_load_toolset_and_run(self):
         # Auth: TOOLBOX_IDENTITY for simplicity in this local test as we don't have ADK identity setup.
 
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             toolset_name="my-toolset",
             credentials=CredentialStrategy.toolbox_identity(),
         )
@@ -88,7 +87,7 @@ async def test_load_toolset_and_run(self):
     async def test_load_toolset_with_default_protocol(self):
         """Test initializing toolset with default protocol (MCP)."""
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             toolset_name="my-toolset",
             credentials=CredentialStrategy.toolbox_identity(),
         )
@@ -112,7 +111,7 @@ async def test_load_toolset_with_default_protocol(self):
     async def test_load_toolset_with_explicit_protocol(self):
         """Test initializing toolset with specific protocol (MCP_v20251125)."""
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             toolset_name="my-toolset",
             credentials=CredentialStrategy.toolbox_identity(),
             protocol=Protocol.MCP_v20251125,
@@ -136,7 +135,7 @@ async def test_load_toolset_with_explicit_protocol(self):
 
     async def test_partial_loading_by_names(self):
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             tool_names=["get-n-rows"],
             credentials=CredentialStrategy.toolbox_identity(),
         )
@@ -156,7 +155,7 @@ async def test_partial_loading_by_names(self):
     async def test_bound_params_e2e(self):
         # Test binding param at toolset level
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             tool_names=["get-n-rows"],
             bound_params={"num_rows": "2"},
             credentials=CredentialStrategy.toolbox_identity(),
@@ -172,7 +171,7 @@ async def test_bound_params_e2e(self):
 
     async def test_3lo_flow_simulation(self):
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             # Load a specific tool that we know the arguments for
             tool_names=["get-n-rows"],
             credentials=CredentialStrategy.user_identity(
@@ -269,7 +268,7 @@ async def test_3lo_flow_simulation(self):
     async def test_manual_token_integration(self):
         """Test the MANUAL_TOKEN strategy."""
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             toolset_name="my-toolset",
             credentials=CredentialStrategy.manual_token(token="fake-manual-token"),
         )
@@ -288,7 +287,7 @@ async def test_manual_credentials_integration(self):
         mock_creds.token = "fake-creds-token"
 
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             toolset_name="my-toolset",
             credentials=CredentialStrategy.manual_credentials(credentials=mock_creds),
         )
@@ -301,7 +300,7 @@ async def test_manual_credentials_integration(self):
     async def test_api_key_integration(self):
         """Test the API_KEY strategy."""
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             toolset_name="my-toolset",
             credentials=CredentialStrategy.api_key(key="my-key", header_name="x-foo"),
         )
@@ -337,7 +336,7 @@ async def test_adk_integration_optional_params(self):
 
         # 3. Use in Toolset
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             toolset_name="my-toolset",
             credentials=strategy,
         )
@@ -361,7 +360,7 @@ async def test_header_collision(self):
         creds_token = "Bearer strategy-token"
 
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             toolset_name="my-toolset",
             additional_headers={"Authorization": manual_override},
             credentials=CredentialStrategy.manual_token(token="strategy-token"),
@@ -395,7 +394,7 @@ async def test_load_toolset_specific(
     ):
         """Load a specific toolset"""
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             toolset_name=toolset_name,
             credentials=CredentialStrategy.toolbox_identity(),
         )
@@ -410,7 +409,7 @@ async def test_load_toolset_specific(
     async def test_load_toolset_default(self):
         """Load the default toolset, i.e. all tools."""
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             credentials=CredentialStrategy.toolbox_identity(),
         )
         try:
@@ -433,7 +432,7 @@ async def test_load_toolset_default(self):
     async def test_run_tool(self):
         """Invoke a tool."""
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             tool_names=["get-n-rows"],
             credentials=CredentialStrategy.toolbox_identity(),
         )
@@ -455,7 +454,7 @@ async def test_run_tool(self):
     async def test_run_tool_missing_params(self):
         """Invoke a tool with missing params."""
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             tool_names=["get-n-rows"],
             credentials=CredentialStrategy.toolbox_identity(),
         )
@@ -474,7 +473,7 @@ async def test_run_tool_missing_params(self):
     async def test_run_tool_wrong_param_type(self):
         """Invoke a tool with wrong param type."""
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             tool_names=["get-n-rows"],
             credentials=CredentialStrategy.toolbox_identity(),
         )
@@ -498,7 +497,7 @@ class TestBindParams:
     async def test_bind_params(self):
         """Bind a param to an existing tool."""
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             tool_names=["get-n-rows"],
             bound_params={"num_rows": "3"},
             credentials=CredentialStrategy.toolbox_identity(),
@@ -520,7 +519,7 @@ async def test_bind_params(self):
     async def test_bind_params_callable(self):
         """Bind a callable param to an existing tool."""
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             tool_names=["get-n-rows"],
             bound_params={"num_rows": lambda: "3"},
             credentials=CredentialStrategy.toolbox_identity(),
@@ -546,7 +545,7 @@ class TestAuth:
     async def test_run_tool_unauth_with_auth(self, auth_token2: str):
         """Tests running a tool that doesn't require auth, with auth provided."""
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             tool_names=["get-row-by-id"],
             auth_token_getters={"my-test-auth": lambda: auth_token2},
             credentials=CredentialStrategy.toolbox_identity(),
@@ -563,7 +562,7 @@ async def test_run_tool_unauth_with_auth(self, auth_token2: str):
     async def test_run_multiple_tools_unauth_with_auth(self, auth_token2: str):
         """Tests running multiple tools that don't require auth, verifying formatting of tool lists."""
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             tool_names=["get-row-by-id", "search-rows"],
             auth_token_getters={"my-test-auth": lambda: auth_token2},
             credentials=CredentialStrategy.toolbox_identity(),
@@ -580,7 +579,7 @@ async def test_run_multiple_tools_unauth_with_auth(self, auth_token2: str):
     async def test_run_multiple_tools_partial_auth_usage(self, auth_token2: str):
         """Tests that when some tokens are used and some aren't across diverse tools, only the truly unused tokens appear in the error."""
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             tool_names=[
                 "get-row-by-id-auth",
                 "search-rows",
@@ -605,7 +604,7 @@ async def test_run_tool_no_auth(self):
         """Tests running a tool requiring auth without providing auth."""
         # Note: We load it without auth getters. Invocation should fail.
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             tool_names=["get-row-by-id-auth"],
             credentials=CredentialStrategy.toolbox_identity(),
         )
@@ -625,7 +624,7 @@ async def test_run_tool_no_auth(self):
     async def test_run_tool_wrong_auth(self, auth_token2: str):
         """Tests running a tool with incorrect auth."""
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             tool_names=["get-row-by-id-auth"],
             auth_token_getters={"my-test-auth": lambda: auth_token2},
             credentials=CredentialStrategy.toolbox_identity(),
@@ -646,7 +645,7 @@ async def test_run_tool_wrong_auth(self, auth_token2: str):
     async def test_run_tool_auth(self, auth_token1: str):
         """Tests running a tool with correct auth."""
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             tool_names=["get-row-by-id-auth"],
             auth_token_getters={"my-test-auth": lambda: auth_token1},
             credentials=CredentialStrategy.toolbox_identity(),
@@ -668,7 +667,7 @@ async def get_token_asynchronously():
             return auth_token1
 
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             tool_names=["get-row-by-id-auth"],
             auth_token_getters={"my-test-auth": get_token_asynchronously},
             credentials=CredentialStrategy.toolbox_identity(),
@@ -694,7 +693,7 @@ class TestOptionalParams:
     async def test_run_tool_with_optional_params_omitted(self):
         """Invoke a tool providing only the required parameter."""
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             tool_names=["search-rows"],
             credentials=CredentialStrategy.toolbox_identity(),
         )
@@ -713,7 +712,7 @@ async def test_run_tool_with_optional_params_omitted(self):
     async def test_run_tool_with_all_valid_params(self):
         """Invoke a tool providing all parameters."""
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             tool_names=["search-rows"],
             credentials=CredentialStrategy.toolbox_identity(),
         )
@@ -733,7 +732,7 @@ async def test_run_tool_with_all_valid_params(self):
     async def test_run_tool_with_missing_required_param(self):
         """Invoke a tool without its required parameter."""
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             tool_names=["search-rows"],
             credentials=CredentialStrategy.toolbox_identity(),
         )
@@ -758,7 +757,7 @@ class TestMapParams:
     async def test_run_tool_with_map_params(self):
         """Invoke a tool with valid map parameters."""
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             tool_names=["process-data"],
             credentials=CredentialStrategy.toolbox_identity(),
         )
@@ -789,7 +788,7 @@ async def test_run_tool_with_map_params(self):
     async def test_run_tool_with_wrong_map_value_type(self):
         """Invoke a tool with a map parameter having the wrong value type."""
         toolset = ToolboxToolset(
-            server_url=TOOLBOX_SERVER_URL,
+            server_url=TOOLBOX_SERVER_URL_STABLE,
             tool_names=["process-data"],
             credentials=CredentialStrategy.toolbox_identity(),
         )

packages/toolbox-core/README.md

@@ -63,6 +63,7 @@ The core package provides a framework-agnostic way to interact with your Toolbox
 - [Authenticating Tools](https://mcp-toolbox.dev/documentation/connect-to/toolbox-sdks/python-sdk/core/#authenticating-tools)
 - [Binding Parameter Values](https://mcp-toolbox.dev/documentation/connect-to/toolbox-sdks/python-sdk/core/#parameter-binding)
 - [OpenTelemetry](https://mcp-toolbox.dev/documentation/connect-to/toolbox-sdks/python-sdk/core/#opentelemetry)
+- [Protocol Negotiation](https://mcp-toolbox.dev/documentation/connect-to/toolbox-sdks/python-sdk/core/#protocol-negotiation)
 
 
 # Contributing