fix(mcp): disambiguate colliding server prefixes

Author: IgnazioDS

src/agents/mcp/util.py

@@ -3,6 +3,7 @@
 import asyncio
 import copy
 import functools
+import hashlib
 import inspect
 import json
 from collections.abc import Awaitable
@@ -212,6 +213,9 @@ async def get_all_function_tools(
         """Get all function tools from a list of MCP servers."""
         tools = []
         tool_names: set[str] = set()
+        server_tool_name_prefixes = (
+            cls._server_tool_name_prefixes(servers) if include_server_in_tool_names else {}
+        )
         for server in servers:
             server_tools = await cls.get_function_tools(
                 server,
@@ -220,6 +224,7 @@ async def get_all_function_tools(
                 agent,
                 failure_error_function=failure_error_function,
                 include_server_in_tool_names=include_server_in_tool_names,
+                tool_name_prefix=server_tool_name_prefixes.get(id(server)),
             )
             server_tool_names = {tool.name for tool in server_tools}
             if len(server_tool_names & tool_names) > 0:
@@ -241,16 +246,18 @@ async def get_function_tools(
         agent: AgentBase,
         failure_error_function: ToolErrorFunction | None = default_tool_error_function,
         include_server_in_tool_names: bool = False,
+        tool_name_prefix: str | None = None,
     ) -> list[Tool]:
         """Get all function tools from a single MCP server."""
 
         with mcp_tools_span(server=server.name) as span:
             tools = await server.list_tools(run_context, agent)
             span.span_data.result = [tool.name for tool in tools]
 
-        tool_name_prefix = (
-            cls._server_tool_name_prefix(server.name) if include_server_in_tool_names else ""
-        )
+        if tool_name_prefix is None:
+            tool_name_prefix = (
+                cls._server_tool_name_prefix(server.name) if include_server_in_tool_names else ""
+            )
         return [
             cls.to_function_tool(
                 tool,
@@ -273,6 +280,30 @@ def _server_tool_name_prefix(server_name: str) -> str:
             normalized = "server"
         return f"{normalized}_"
 
+    @classmethod
+    def _server_tool_name_prefixes(cls, servers: list[MCPServer]) -> dict[int, str]:
+        normalized_to_servers: dict[str, list[MCPServer]] = {}
+        for server in servers:
+            normalized_prefix = cls._server_tool_name_prefix(server.name)[:-1]
+            normalized_to_servers.setdefault(normalized_prefix, []).append(server)
+
+        prefixes: dict[int, str] = {}
+        for normalized_prefix, grouped_servers in normalized_to_servers.items():
+            if len(grouped_servers) == 1:
+                prefixes[id(grouped_servers[0])] = f"{normalized_prefix}_"
+                continue
+
+            seen_prefixes: set[str] = set()
+            for index, server in enumerate(grouped_servers, start=1):
+                hash_suffix = hashlib.sha1(server.name.encode("utf-8")).hexdigest()[:8]
+                prefix = f"{normalized_prefix}_{hash_suffix}"
+                if prefix in seen_prefixes:
+                    prefix = f"{prefix}_{index}"
+                seen_prefixes.add(prefix)
+                prefixes[id(server)] = f"{prefix}_"
+
+        return prefixes
+
     @classmethod
     def to_function_tool(
         cls,

tests/mcp/test_mcp_util.py

@@ -178,6 +178,43 @@ async def test_get_all_function_tools_prefix_falls_back_for_empty_server_name_sl
     assert server.tool_calls == ["search"]
 
 
+@pytest.mark.asyncio
+async def test_get_all_function_tools_disambiguates_colliding_server_name_prefixes():
+    server1 = FakeMCPServer(server_name="GitHub MCP Server")
+    server1.add_tool("create_issue", {})
+
+    server2 = FakeMCPServer(server_name="GitHub_MCP_Server")
+    server2.add_tool("create_issue", {})
+
+    run_context = RunContextWrapper(context=None)
+    agent = Agent(
+        name="test_agent",
+        instructions="Test agent",
+        mcp_servers=[server1, server2],
+        mcp_config={"include_server_in_tool_names": True},
+    )
+
+    tools = await agent.get_mcp_tools(run_context)
+    tool_names = {tool.name for tool in tools}
+    assert len(tool_names) == 2
+    assert all(tool_name.startswith("GitHub_MCP_Server_") for tool_name in tool_names)
+    assert all(tool_name.endswith("_create_issue") for tool_name in tool_names)
+
+    for idx, tool in enumerate(tools, start=1):
+        assert isinstance(tool, FunctionTool)
+        tool_context = ToolContext(
+            context=None,
+            tool_name=tool.name,
+            tool_call_id=f"prefixed_collision_{idx}",
+            tool_arguments='{"title":"collision"}',
+        )
+        result = await tool.on_invoke_tool(tool_context, '{"title":"collision"}')
+        assert isinstance(result, dict)
+
+    assert server1.tool_calls == ["create_issue"]
+    assert server2.tool_calls == ["create_issue"]
+
+
 @pytest.mark.asyncio
 async def test_invoke_mcp_tool():
     """Test that the invoke_mcp_tool function invokes an MCP tool and returns the result."""