fix(mcp): encode prefixed tool names unambiguously

Author: IgnazioDS

src/agents/agent.py

@@ -151,8 +151,8 @@ class MCPConfig(TypedDict):
     """
 
     include_server_in_tool_names: NotRequired[bool]
-    """If True, MCP tools are exposed as `<server_name>_<tool_name>` to avoid collisions across
-    servers that publish the same tool names. Defaults to False.
+    """If True, MCP tools are exposed with an unambiguous server-specific prefix to avoid
+    collisions across servers that publish the same tool names. Defaults to False.
     """
 
 

src/agents/mcp/util.py

@@ -265,7 +265,11 @@ async def get_function_tools(
                 convert_schemas_to_strict,
                 agent,
                 failure_error_function=failure_error_function,
-                tool_name_override=f"{tool_name_prefix}{tool.name}" if tool_name_prefix else None,
+                tool_name_override=(
+                    cls._prefixed_tool_name(tool_name_prefix, tool.name)
+                    if tool_name_prefix
+                    else None
+                ),
             )
             for tool in tools
         ]
@@ -280,6 +284,10 @@ def _server_tool_name_prefix(server_name: str) -> str:
             normalized = "server"
         return f"{normalized}_"
 
+    @staticmethod
+    def _prefixed_tool_name(tool_name_prefix: str, tool_name: str) -> str:
+        return f"mcp_{len(tool_name_prefix)}_{tool_name_prefix}{tool_name}"
+
     @classmethod
     def _server_tool_name_prefixes(cls, servers: list[MCPServer]) -> dict[int, str]:
         normalized_to_servers: dict[str, list[MCPServer]] = {}

tests/mcp/test_mcp_util.py

@@ -120,10 +120,12 @@ async def test_get_all_function_tools_can_prefix_with_server_name():
 
     tools = await agent.get_mcp_tools(run_context)
     tool_names = {tool.name for tool in tools}
-    assert tool_names == {"GitHub_MCP_Server_create_issue", "linear_create_issue"}
+    assert tool_names == {"mcp_18_GitHub_MCP_Server_create_issue", "mcp_7_linear_create_issue"}
 
-    github_tool = next(tool for tool in tools if tool.name == "GitHub_MCP_Server_create_issue")
-    linear_tool = next(tool for tool in tools if tool.name == "linear_create_issue")
+    github_tool = next(
+        tool for tool in tools if tool.name == "mcp_18_GitHub_MCP_Server_create_issue"
+    )
+    linear_tool = next(tool for tool in tools if tool.name == "mcp_7_linear_create_issue")
     assert isinstance(github_tool, FunctionTool)
     assert isinstance(linear_tool, FunctionTool)
 
@@ -165,7 +167,7 @@ async def test_get_all_function_tools_prefix_falls_back_for_empty_server_name_sl
     assert len(tools) == 1
     prefixed_tool = tools[0]
     assert isinstance(prefixed_tool, FunctionTool)
-    assert prefixed_tool.name == "server_search"
+    assert prefixed_tool.name == "mcp_7_server_search"
 
     tool_context = ToolContext(
         context=None,
@@ -197,7 +199,7 @@ async def test_get_all_function_tools_disambiguates_colliding_server_name_prefix
     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.startswith("mcp_27_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):
@@ -287,7 +289,7 @@ def resolve_meta(context):
 
     prefixed_tool = tools[0]
     assert isinstance(prefixed_tool, FunctionTool)
-    assert prefixed_tool.name == "GitHub_MCP_Server_create_issue"
+    assert prefixed_tool.name == "mcp_18_GitHub_MCP_Server_create_issue"
 
     tool_context = ToolContext(
         context=None,