Fix MCP tool name conflicts by adding server name prefixes

[fadeoreo]

Problem

When two MCP servers have tools with the same internal tool name, running agent list MCP: list tools from server xxxx will hang, and after the tool list is (supposedly) returned, the agent cannot work properly.

During troubleshooting, issues such as network, protocol, registration, or async problems were suspected, but the real cause was that one of the MCP tools had a conflicting tool name, making it impossible for the agent SDK to distinguish between tools from different servers.

Solution

This PR implements server name prefixing for MCP tool names to ensure global uniqueness and avoid conflicts:

1. Prefixes tool names with server name: Tool names are prefixed with {server_name}_{tool_name} format (e.g., serverA_run, serverB_run)
2. Preserves original names: The original tool name is stored in the original_name attribute for actual tool calls
3. Maintains backward compatibility: Tool invocation still uses the original name when calling the MCP server

Changes Made

Core Implementation

• src/agents/mcp/server.py: Modified list_tools() method to add server name prefixes and preserve original names
• src/agents/mcp/util.py: Updated invoke_mcp_tool() to use original names for tool calls

Testing

• tests/mcp/test_tool_name_conflicts.py: Comprehensive test suite with 9 test cases covering:
  • Basic prefixing functionality
  • Multiple server conflict resolution
  • MCPUtil integration
  • Legacy behavior regression testing
  • Edge cases (empty names, special characters)
  • Tool invocation verification

Example

Before (Conflict)

Server1: [run, echo]
Server2: [run, list]
Result: ❌ Conflict on 'run' tool name → agent list hangs

After (Resolved)

Server1: [server1_run, server1_echo]
Server2: [server2_run, server2_list]
Result: ✅ All tool names are unique → agent list works correctly

Fixes #1167

[seratch]

At a glance, the changes look good to me. Can you resolve the lint and typecheck failures?

[fadeoreo]

Okay, I'll try it.

[seratch]

Can you check the mypy errors in tests?

uv run mypy .
tests/mcp/test_tool_name_conflicts.py:35: error: Missing type parameters for generic type "dict"  [type-arg]
tests/mcp/test_tool_name_conflicts.py:66: error: "Tool" has no attribute "original_name"  [attr-defined]
tests/mcp/test_tool_name_conflicts.py:205: error: Missing type parameters for generic type "dict"  [type-arg]
tests/mcp/test_tool_name_conflicts.py:279: error: "Tool" has no attribute "original_name"  [attr-defined]
tests/mcp/test_tool_name_conflicts.py:308: error: "Tool" has no attribute "original_name"  [attr-defined]
tests/mcp/test_tool_name_conflicts.py:325: error: "Tool" has no attribute "original_name"  [attr-defined]
tests/mcp/test_tool_name_conflicts.py:343: error: "Tool" has no attribute "original_name"  [attr-defined]
Found 7 errors in 1 file (checked 269 source files)
make: *** [Makefile:20: mypy] Error 1
Error: Process completed with exit code 2.

[fadeoreo]

Ok, I will handle these errors.

[mshsheikh]

Ok, I will handle these errors.

@fadeoreo if you need help, I can fix this.

[seratch]

There are still lint issues:

Run make lint
uv run ruff check
tests/mcp/test_tool_name_conflicts.py:66:13: B010 [*] Do not call `setattr` with a constant attribute value. It is not any safer than normal property access.
   |
64 |             )
65 |             # Store original name
66 |             setattr(tool_copy, "original_name", tool.name)
   |             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ B010
67 |             # Add server name prefix
68 |             tool_copy.name = f"{self.name}_{tool.name}"
   |
   = help: Replace `setattr` with assignment

Found 1 error.
[*] 1 fixable with the `--fix` option.
make: *** [Makefile:16: lint] Error 1
Error: Process completed with exit code 2.

[rm-openai]

I like the idea! But we can't just prefix the tool name with server name by default. It should be opt-in (i.e. a param that says prefix_tool_names...)

[fadeoreo]

Okay, I'll add it and update the code