feat(mcp): optional server-name prefix for colliding tool names

[OiPunk]

Summary

This PR adds an opt-in way to avoid MCP tool name collisions across multiple servers.

When Agent.mcp_config["prefix_tool_names_with_server_name"] = True, MCP tools are exposed to the model as:

<sanitized_server_name>_<tool_name>

This keeps current behavior unchanged by default (duplicate names still raise an error), but gives users a first-class way to run multiple MCP servers that expose the same tool names.

Fixes #464

Changes

• Add prefix_tool_names_with_server_name to MCPConfig
• Thread config through Agent.get_mcp_tools() -> MCPUtil.get_all_function_tools()
• Add server-name prefixing logic in MCP util with sanitization and fallback ("server_")
• Keep MCP server invocation using original MCP tool name while exposing the prefixed name to the model
• Update MCP docs with configuration example and notes
• Add regression tests for:
  • default duplicate-name failure behavior
  • successful collision avoidance with server-name prefixes
  • fallback prefix for non-sluggable server names
  • prefixed-name error logging path

Testing

• uv run ruff check src/agents/agent.py src/agents/mcp/util.py tests/mcp/test_mcp_util.py
• uv run mypy . --exclude site
• uv run pytest tests/mcp/test_mcp_util.py -q
• uv run coverage run -m pytest tests/mcp/test_mcp_util.py -q
• uv run coverage report -m src/agents/mcp/util.py

Coverage

• tests/mcp/test_mcp_util.py: 37 passed
• src/agents/mcp/util.py: 90% (existing uncovered branches remain; new collision/prefix paths are covered by added tests)

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f6b9328f53

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[harshai07]

This is a well-thought-out change. Introducing server-based namespacing removes ambiguity when duplicate tool names exist across MCP servers and improves overall agent reliability. The sanitization, logging updates, and documentation make the feature complete. Nice work!

[seratch]

I haven't done any e2e tests with this branch yet. Please do manual testing with examples/* in addition to unit tests.

[OiPunk]

Addressed both requested changes in commit 8f48920:\n\n1. Renamed MCP config key from to across implementation and tests.\n2. Removed all changes from this PR so it only contains code/test updates.\n\nLocal verification:\n- All checks passed!\n- (38 passed)\n\nI will run example-level manual checks next and report back in this PR thread.

[OiPunk]

Quick update on the requested changes:

• Renamed the MCP config key to include_server_in_tool_names in code and tests.
• Removed docs/mcp.md changes from this PR, so the PR now contains only code + tests.

Validation done locally:

• ruff check on modified files: pass
• pytest tests/mcp/test_mcp_util.py: 38 passed
• Manual MCP example-style integration check with two real filesystem MCP servers via npx:
  • include_server_in_tool_names=True produced server-prefixed tool names
  • prefixed tool invocation succeeded end-to-end

Commit: 8f48920

[OiPunk]

Pushed follow-up format fix for CI lint in commit f47fe53. The full test workflow has been retriggered and is running now.

[OiPunk]

Quick follow-up: the requested rename and doc-split are already applied, and I also ran manual MCP example-style validation with two real servers and posted the verification details in-thread. If this now looks good, could you please take another look when you have time?