Add tool_prefix option to MCP servers and error on conflicting tool names (#1266)

Wh1isper · DouweM · web-flow · commit 475e6c1711de · 2025-05-22T14:05:32.000-06:00
Co-authored-by: Douwe Maan &lt;douwe@pydantic.dev&gt;
diff --git a/docs/mcp/client.md b/docs/mcp/client.md
@@ -118,3 +118,70 @@ async def main():
 ```
 
 1. See [MCP Run Python](run-python.md) for more information.
+
+## Using Tool Prefixes to Avoid Naming Conflicts
+
+When connecting to multiple MCP servers that might provide tools with the same name, you can use the `tool_prefix` parameter to avoid naming conflicts. This parameter adds a prefix to all tool names from a specific server.
+
+### How It Works
+
+- If `tool_prefix` is set, all tools from that server will be prefixed with `{tool_prefix}_`
+- When listing tools, the prefixed names are shown to the model
+- When calling tools, the prefix is automatically removed before sending the request to the server
+
+This allows you to use multiple servers that might have overlapping tool names without conflicts.
+
+### Example with HTTP Server
+
+```python {title="mcp_tool_prefix_http_client.py" py="3.10"}
+from pydantic_ai import Agent
+from pydantic_ai.mcp import MCPServerHTTP
+
+# Create two servers with different prefixes
+weather_server = MCPServerHTTP(
+    url='http://localhost:3001/sse',
+    tool_prefix='weather'  # Tools will be prefixed with 'weather_'
+)
+
+calculator_server = MCPServerHTTP(
+    url='http://localhost:3002/sse',
+    tool_prefix='calc'  # Tools will be prefixed with 'calc_'
+)
+
+# Both servers might have a tool named 'get_data', but they'll be exposed as:
+# - 'weather_get_data'
+# - 'calc_get_data'
+agent = Agent('openai:gpt-4o', mcp_servers=[weather_server, calculator_server])
+```
+
+### Example with Stdio Server
+
+```python {title="mcp_tool_prefix_stdio_client.py" py="3.10"}
+from pydantic_ai import Agent
+from pydantic_ai.mcp import MCPServerStdio
+
+python_server = MCPServerStdio(
+    'deno',
+    args=[
+        'run',
+        '-N',
+        'jsr:@pydantic/mcp-run-python',
+        'stdio',
+    ],
+    tool_prefix='py'  # Tools will be prefixed with 'py_'
+)
+
+js_server = MCPServerStdio(
+    'node',
+    args=[
+        'run',
+        'mcp-js-server.js',
+        'stdio',
+    ],
+    tool_prefix='js'  # Tools will be prefixed with 'js_'
+)
+
+agent = Agent('openai:gpt-4o', mcp_servers=[python_server, js_server])
+```
+
+When the model interacts with these servers, it will see the prefixed tool names, but the prefixes will be automatically handled when making tool calls.
diff --git a/pydantic_ai_slim/pydantic_ai/_agent_graph.py b/pydantic_ai_slim/pydantic_ai/_agent_graph.py
@@ -222,27 +222,40 @@ async def _prepare_request_parameters(
     ctx: GraphRunContext[GraphAgentState, GraphAgentDeps[DepsT, NodeRunEndT]],
 ) -> models.ModelRequestParameters:
     """Build tools and create an agent model."""
-    function_tool_defs: list[ToolDefinition] = []
+    function_tool_defs_map: dict[str, ToolDefinition] = {}
 
     run_context = build_run_context(ctx)
 
     async def add_tool(tool: Tool[DepsT]) -> None:
         ctx = run_context.replace_with(retry=tool.current_retry, tool_name=tool.name)
         if tool_def := await tool.prepare_tool_def(ctx):
-            function_tool_defs.append(tool_def)
+            # prepare_tool_def may change tool_def.name
+            if tool_def.name in function_tool_defs_map:
+                if tool_def.name != tool.name:
+                    # Prepare tool def may have renamed the tool
+                    raise exceptions.UserError(
+                        f"Renaming tool '{tool.name}' to '{tool_def.name}' conflicts with existing tool."
+                    )
+                else:
+                    raise exceptions.UserError(f'Tool name conflicts with existing tool: {tool.name!r}.')
+            function_tool_defs_map[tool_def.name] = tool_def
 
     async def add_mcp_server_tools(server: MCPServer) -> None:
         if not server.is_running:
             raise exceptions.UserError(f'MCP server is not running: {server}')
         tool_defs = await server.list_tools()
-        # TODO(Marcelo): We should check if the tool names are unique. If not, we should raise an error.
-        function_tool_defs.extend(tool_defs)
+        for tool_def in tool_defs:
+            if tool_def.name in function_tool_defs_map:
+                raise exceptions.UserError(
+                    f"MCP Server '{server}' defines a tool whose name conflicts with existing tool: {tool_def.name!r}. Consider using `tool_prefix` to avoid name conflicts."
+                )
+            function_tool_defs_map[tool_def.name] = tool_def
 
     await asyncio.gather(
         *map(add_tool, ctx.deps.function_tools.values()),
         *map(add_mcp_server_tools, ctx.deps.mcp_servers),
     )
-
+    function_tool_defs = list(function_tool_defs_map.values())
     if ctx.deps.prepare_tools:
         # Prepare the tools using the provided function
         # This also acts over tool definitions pulled from MCP servers
diff --git a/pydantic_ai_slim/pydantic_ai/mcp.py b/pydantic_ai_slim/pydantic_ai/mcp.py
@@ -46,6 +46,13 @@ class MCPServer(ABC):
     """
 
     is_running: bool = False
+    tool_prefix: str | None = None
+    """A prefix to add to all tools that are registered with the server.
+
+    If not empty, will include a trailing underscore(`_`).
+
+    e.g. if `tool_prefix='foo'`, then a tool named `bar` will be registered as `foo_bar`
+    """
 
     _client: ClientSession
     _read_stream: MemoryObjectReceiveStream[JSONRPCMessage | Exception]
@@ -57,7 +64,10 @@ class MCPServer(ABC):
     async def client_streams(
         self,
     ) -> AsyncIterator[
-        tuple[MemoryObjectReceiveStream[JSONRPCMessage | Exception], MemoryObjectSendStream[JSONRPCMessage]]
+        tuple[
+            MemoryObjectReceiveStream[JSONRPCMessage | Exception],
+            MemoryObjectSendStream[JSONRPCMessage],
+        ]
     ]:
         """Create the streams for the MCP server."""
         raise NotImplementedError('MCP Server subclasses must implement this method.')
@@ -68,6 +78,14 @@ def _get_log_level(self) -> LoggingLevel | None:
         """Get the log level for the MCP server."""
         raise NotImplementedError('MCP Server subclasses must implement this method.')
 
+    def get_prefixed_tool_name(self, tool_name: str) -> str:
+        """Get the tool name with prefix if `tool_prefix` is set."""
+        return f'{self.tool_prefix}_{tool_name}' if self.tool_prefix else tool_name
+
+    def get_unprefixed_tool_name(self, tool_name: str) -> str:
+        """Get original tool name without prefix for calling tools."""
+        return tool_name.removeprefix(f'{self.tool_prefix}_') if self.tool_prefix else tool_name
+
     async def list_tools(self) -> list[ToolDefinition]:
         """Retrieve tools that are currently active on the server.
 
@@ -78,7 +96,7 @@ async def list_tools(self) -> list[ToolDefinition]:
         tools = await self._client.list_tools()
         return [
             ToolDefinition(
-                name=tool.name,
+                name=self.get_prefixed_tool_name(tool.name),
                 description=tool.description or '',
                 parameters_json_schema=tool.inputSchema,
             )
@@ -100,7 +118,7 @@ async def call_tool(
         Raises:
             ModelRetry: If the tool call fails.
         """
-        result = await self._client.call_tool(tool_name, arguments)
+        result = await self._client.call_tool(self.get_unprefixed_tool_name(tool_name), arguments)
 
         content = [self._map_tool_result_part(part) for part in result.content]
 
@@ -126,7 +144,10 @@ async def __aenter__(self) -> Self:
         return self
 
     async def __aexit__(
-        self, exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
     ) -> bool | None:
         await self._exit_stack.aclose()
         self.is_running = False
@@ -223,11 +244,22 @@ async def main():
     cwd: str | Path | None = None
     """The working directory to use when spawning the process."""
 
+    tool_prefix: str | None = None
+    """A prefix to add to all tools that are registered with the server.
+
+    If not empty, will include a trailing underscore(`_`).
+
+    e.g. if `tool_prefix='foo'`, then a tool named `bar` will be registered as `foo_bar`
+    """
+
     @asynccontextmanager
     async def client_streams(
         self,
     ) -> AsyncIterator[
-        tuple[MemoryObjectReceiveStream[JSONRPCMessage | Exception], MemoryObjectSendStream[JSONRPCMessage]]
+        tuple[
+            MemoryObjectReceiveStream[JSONRPCMessage | Exception],
+            MemoryObjectSendStream[JSONRPCMessage],
+        ]
     ]:
         server = StdioServerParameters(command=self.command, args=list(self.args), env=self.env, cwd=self.cwd)
         async with stdio_client(server=server) as (read_stream, write_stream):
@@ -236,6 +268,9 @@ async def client_streams(
     def _get_log_level(self) -> LoggingLevel | None:
         return self.log_level
 
+    def __repr__(self) -> str:
+        return f'MCPServerStdio(command={self.command!r}, args={self.args!r}, tool_prefix={self.tool_prefix!r})'
+
 
 @dataclass
 class MCPServerHTTP(MCPServer):
@@ -303,16 +338,33 @@ async def main():
     If `None`, no log level will be set.
     """
 
+    tool_prefix: str | None = None
+    """A prefix to add to all tools that are registered with the server.
+
+    If not empty, will include a trailing underscore (`_`).
+
+    For example, if `tool_prefix='foo'`, then a tool named `bar` will be registered as `foo_bar`
+    """
+
     @asynccontextmanager
     async def client_streams(
         self,
     ) -> AsyncIterator[
-        tuple[MemoryObjectReceiveStream[JSONRPCMessage | Exception], MemoryObjectSendStream[JSONRPCMessage]]
+        tuple[
+            MemoryObjectReceiveStream[JSONRPCMessage | Exception],
+            MemoryObjectSendStream[JSONRPCMessage],
+        ]
     ]:  # pragma: no cover
         async with sse_client(
-            url=self.url, headers=self.headers, timeout=self.timeout, sse_read_timeout=self.sse_read_timeout
+            url=self.url,
+            headers=self.headers,
+            timeout=self.timeout,
+            sse_read_timeout=self.sse_read_timeout,
         ) as (read_stream, write_stream):
             yield read_stream, write_stream
 
     def _get_log_level(self) -> LoggingLevel | None:
         return self.log_level
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f'MCPServerHTTP(url={self.url!r}, tool_prefix={self.tool_prefix!r})'
diff --git a/tests/test_mcp.py b/tests/test_mcp.py
@@ -1,5 +1,6 @@
 """Tests for the MCP (Model Context Protocol) server implementation."""
 
+import re
 from pathlib import Path
 
 import pytest
@@ -54,6 +55,13 @@ async def test_stdio_server():
         assert result == snapshot('32.0')
 
 
+async def test_stdio_server_with_tool_prefix():
+    server = MCPServerStdio('python', ['-m', 'tests.mcp_server'], tool_prefix='foo')
+    async with server:
+        tools = await server.list_tools()
+        assert all(tool.name.startswith('foo_') for tool in tools)
+
+
 async def test_stdio_server_with_cwd():
     test_dir = Path(__file__).parent
     server = MCPServerStdio('python', ['mcp_server.py'], cwd=test_dir)
@@ -156,6 +164,41 @@ async def test_agent_with_stdio_server(allow_model_requests: None, agent: Agent)
         )
 
 
+async def test_agent_with_conflict_tool_name(agent: Agent):
+    @agent.tool_plain
+    def get_none() -> None:  # pragma: no cover
+        """Return nothing"""
+        return None
+
+    async with agent.run_mcp_servers():
+        with pytest.raises(
+            UserError,
+            match=re.escape(
+                "MCP Server 'MCPServerStdio(command='python', args=['-m', 'tests.mcp_server'], tool_prefix=None)' defines a tool whose name conflicts with existing tool: 'get_none'. Consider using `tool_prefix` to avoid name conflicts."
+            ),
+        ):
+            await agent.run('Get me a conflict')
+
+
+async def test_agent_with_prefix_tool_name(openai_api_key: str):
+    server = MCPServerStdio('python', ['-m', 'tests.mcp_server'], tool_prefix='foo')
+    model = OpenAIModel('gpt-4o', provider=OpenAIProvider(api_key=openai_api_key))
+    agent = Agent(
+        model,
+        mcp_servers=[server],
+    )
+
+    @agent.tool_plain
+    def get_none() -> None:  # pragma: no cover
+        """Return nothing"""
+        return None
+
+    async with agent.run_mcp_servers():
+        # This means that we passed the _prepare_request_parameters check and there is no conflict in the tool name
+        with pytest.raises(RuntimeError, match='Model requests are not allowed, since ALLOW_MODEL_REQUESTS is False'):
+            await agent.run('No conflict')
+
+
 async def test_agent_with_server_not_running(openai_api_key: str):
     server = MCPServerStdio('python', ['-m', 'tests.mcp_server'])
     model = OpenAIModel('gpt-4o', provider=OpenAIProvider(api_key=openai_api_key))
@@ -281,7 +324,9 @@ async def test_tool_returning_text_resource(allow_model_requests: None, agent: A
                 ModelResponse(
                     parts=[
                         ToolCallPart(
-                            tool_name='get_product_name', args='{}', tool_call_id='call_LaiWltzI39sdquflqeuF0EyE'
+                            tool_name='get_product_name',
+                            args='{}',
+                            tool_call_id='call_LaiWltzI39sdquflqeuF0EyE',
                         )
                     ],
                     usage=Usage(
@@ -354,7 +399,9 @@ async def test_tool_returning_image_resource(allow_model_requests: None, agent:
                 ModelResponse(
                     parts=[
                         ToolCallPart(
-                            tool_name='get_image_resource', args='{}', tool_call_id='call_nFsDHYDZigO0rOHqmChZ3pmt'
+                            tool_name='get_image_resource',
+                            args='{}',
+                            tool_call_id='call_nFsDHYDZigO0rOHqmChZ3pmt',
                         )
                     ],
                     usage=Usage(
@@ -435,7 +482,11 @@ async def test_tool_returning_image(allow_model_requests: None, agent: Agent, im
                 ),
                 ModelResponse(
                     parts=[
-                        ToolCallPart(tool_name='get_image', args='{}', tool_call_id='call_Q7xG8CCG0dyevVfUS0ubsDdN')
+                        ToolCallPart(
+                            tool_name='get_image',
+                            args='{}',
+                            tool_call_id='call_Q7xG8CCG0dyevVfUS0ubsDdN',
+                        )
                     ],
                     usage=Usage(
                         requests=1,
@@ -581,7 +632,9 @@ async def test_tool_returning_error(allow_model_requests: None, agent: Agent):
                 ModelResponse(
                     parts=[
                         ToolCallPart(
-                            tool_name='get_error', args='{"value":false}', tool_call_id='call_rETXZWddAGZSHyVHAxptPGgc'
+                            tool_name='get_error',
+                            args='{"value":false}',
+                            tool_call_id='call_rETXZWddAGZSHyVHAxptPGgc',
                         )
                     ],
                     usage=Usage(
@@ -614,7 +667,9 @@ async def test_tool_returning_error(allow_model_requests: None, agent: Agent):
                 ModelResponse(
                     parts=[
                         ToolCallPart(
-                            tool_name='get_error', args='{"value":true}', tool_call_id='call_4xGyvdghYKHN8x19KWkRtA5N'
+                            tool_name='get_error',
+                            args='{"value":true}',
+                            tool_call_id='call_4xGyvdghYKHN8x19KWkRtA5N',
                         )
                     ],
                     usage=Usage(
@@ -758,7 +813,9 @@ async def test_tool_returning_multiple_items(allow_model_requests: None, agent:
                 ModelResponse(
                     parts=[
                         ToolCallPart(
-                            tool_name='get_multiple_items', args='{}', tool_call_id='call_kL0TvjEVQBDGZrn1Zv7iNYOW'
+                            tool_name='get_multiple_items',
+                            args='{}',
+                            tool_call_id='call_kL0TvjEVQBDGZrn1Zv7iNYOW',
                         )
                     ],
                     usage=Usage(
diff --git a/tests/test_tools.py b/tests/test_tools.py
