feat: add option to prefix tool name w/ server name (#387)

Adds a `tool_name_prefix` argument to `MultiServerMCPClient`. If `True`,
tool names are prefixed with the server name using an underscore
separator (e.g., `"weather_search"` instead of `"search"`). This helps
avoid conflicts when multiple servers have tools with the same name.
Defaults to `False` (backwards compat).

In the future, I could see us extending this to use a custom callable,
but I don't think that's important in the short term (haven't gotten any
requests for this).

Fixes #273

Author: sydney-runkle

langchain_mcp_adapters/client.py

@@ -54,6 +54,7 @@ def __init__(
         *,
         callbacks: Callbacks | None = None,
         tool_interceptors: list[ToolCallInterceptor] | None = None,
+        tool_name_prefix: bool = False,
     ) -> None:
         """Initialize a `MultiServerMCPClient` with MCP servers connections.
 
@@ -63,6 +64,10 @@ def __init__(
             callbacks: Optional callbacks for handling notifications and events.
             tool_interceptors: Optional list of tool call interceptors for modifying
                 requests and responses.
+            tool_name_prefix: If `True`, tool names are prefixed with the server name
+                using an underscore separator (e.g., `"weather_search"` instead of
+                `"search"`). This helps avoid conflicts when multiple servers have tools
+                with the same name. Defaults to `False`.
 
         !!! example "Basic usage (starting a new session on each tool call)"
 
@@ -104,6 +109,7 @@ def __init__(
         )
         self.callbacks = callbacks or Callbacks()
         self.tool_interceptors = tool_interceptors or []
+        self.tool_name_prefix = tool_name_prefix
 
     @asynccontextmanager
     async def session(
@@ -171,6 +177,7 @@ async def get_tools(self, *, server_name: str | None = None) -> list[BaseTool]:
                 callbacks=self.callbacks,
                 server_name=server_name,
                 tool_interceptors=self.tool_interceptors,
+                tool_name_prefix=self.tool_name_prefix,
             )
 
         all_tools: list[BaseTool] = []
@@ -183,6 +190,7 @@ async def get_tools(self, *, server_name: str | None = None) -> list[BaseTool]:
                     callbacks=self.callbacks,
                     server_name=name,
                     tool_interceptors=self.tool_interceptors,
+                    tool_name_prefix=self.tool_name_prefix,
                 )
             )
             load_mcp_tool_tasks.append(load_mcp_tool_task)

langchain_mcp_adapters/tools.py

@@ -277,6 +277,7 @@ def convert_mcp_tool_to_langchain_tool(
     callbacks: Callbacks | None = None,
     tool_interceptors: list[ToolCallInterceptor] | None = None,
     server_name: str | None = None,
+    tool_name_prefix: bool = False,
 ) -> BaseTool:
     """Convert an MCP tool to a LangChain tool.
 
@@ -290,6 +291,8 @@ def convert_mcp_tool_to_langchain_tool(
         callbacks: Optional callbacks for handling notifications and events
         tool_interceptors: Optional list of interceptors for tool call processing
         server_name: Name of the server this tool belongs to
+        tool_name_prefix: If `True` and `server_name` is provided, the tool name will be
+            prefixed w/ server name (e.g., `"weather_search"` instead of `"search"`)
 
     Returns:
         a LangChain tool
@@ -415,8 +418,13 @@ async def execute_tool(request: MCPToolCallRequest) -> MCPToolCallResult:
     meta = {"_meta": meta} if meta is not None else {}
     metadata = {**base, **meta} or None
 
+    # Apply server name prefix if requested
+    lc_tool_name = tool.name
+    if tool_name_prefix and server_name:
+        lc_tool_name = f"{server_name}_{tool.name}"
+
     return StructuredTool(
-        name=tool.name,
+        name=lc_tool_name,
         description=tool.description or "",
         args_schema=tool.inputSchema,
         coroutine=call_tool,
@@ -432,6 +440,7 @@ async def load_mcp_tools(
     callbacks: Callbacks | None = None,
     tool_interceptors: list[ToolCallInterceptor] | None = None,
     server_name: str | None = None,
+    tool_name_prefix: bool = False,
 ) -> list[BaseTool]:
     """Load all available MCP tools and convert them to LangChain [tools](https://docs.langchain.com/oss/python/langchain/tools).
 
@@ -441,6 +450,8 @@ async def load_mcp_tools(
         callbacks: Optional `Callbacks` for handling notifications and events.
         tool_interceptors: Optional list of interceptors for tool call processing.
         server_name: Name of the server these tools belong to.
+        tool_name_prefix: If `True` and `server_name` is provided, tool names will be
+            prefixed w/ server name (e.g., `"weather_search"` instead of `"search"`).
 
     Returns:
         List of LangChain [tools](https://docs.langchain.com/oss/python/langchain/tools).
@@ -480,6 +491,7 @@ async def load_mcp_tools(
             callbacks=callbacks,
             tool_interceptors=tool_interceptors,
             server_name=server_name,
+            tool_name_prefix=tool_name_prefix,
         )
         for tool in tools
     ]

tests/test_tools.py

@@ -992,3 +992,188 @@ class CustomAgentState(AgentState):
             isinstance(msg, ToolMessage) and msg.content == "Counter updated!"
             for msg in result["messages"]
         )
+
+
+# Tests for tool_name_prefix functionality
+
+
+def _create_weather_search_server():
+    """Create a weather server with a search tool."""
+    server = FastMCP(port=8185)
+
+    @server.tool()
+    def search(query: str) -> str:
+        """Search for weather information"""
+        return f"Weather results for: {query}"
+
+    return server
+
+
+def _create_flights_search_server():
+    """Create a flights server with a search tool."""
+    server = FastMCP(port=8186)
+
+    @server.tool()
+    def search(destination: str) -> str:
+        """Search for flights"""
+        return f"Flight results to: {destination}"
+
+    return server
+
+
+@pytest.mark.skipif(not LANGCHAIN_INSTALLED, reason="langchain not installed")
+async def test_parallel_tool_invocation_across_multiple_servers(socket_enabled) -> None:
+    """Test that two servers with identically named tools can be invoked in parallel.
+
+    This test verifies that:
+    1. Two MCP servers can each expose a tool with the same name (search)
+    2. With tool_name_prefix=True, they get unique LangChain names
+        (weather_search, flights_search)
+    3. When an LLM calls both tools in parallel,
+       each tool is routed to the correct server
+    4. The correct results come back from each server
+    """
+    from langchain.agents import AgentState, create_agent  # noqa: PLC0415
+    from langgraph.checkpoint.memory import MemorySaver  # noqa: PLC0415
+
+    with (
+        run_streamable_http(_create_weather_search_server, 8185),
+        run_streamable_http(_create_flights_search_server, 8186),
+    ):
+        client = MultiServerMCPClient(
+            {
+                "weather": {
+                    "url": "http://localhost:8185/mcp",
+                    "transport": "streamable_http",
+                },
+                "flights": {
+                    "url": "http://localhost:8186/mcp",
+                    "transport": "streamable_http",
+                },
+            },
+            tool_name_prefix=True,
+        )
+        tools = await client.get_tools()
+
+        # Verify we have both prefixed tools
+        assert len(tools) == 2
+        tool_names = {t.name for t in tools}
+        assert tool_names == {"weather_search", "flights_search"}
+
+        # Simulate an LLM calling both tools in parallel (common pattern for agents)
+        model = FixedGenericFakeChatModel(
+            messages=iter(
+                [
+                    AIMessage(
+                        content="",
+                        tool_calls=[
+                            {
+                                "name": "weather_search",
+                                "args": {"query": "sunny in Paris"},
+                                "id": "call_weather",
+                                "type": "tool_call",
+                            },
+                            {
+                                "name": "flights_search",
+                                "args": {"destination": "Tokyo"},
+                                "id": "call_flights",
+                                "type": "tool_call",
+                            },
+                        ],
+                    ),
+                    AIMessage(content="Here are your results."),
+                ]
+            )
+        )
+
+        agent = create_agent(
+            model,
+            tools,
+            state_schema=AgentState,
+            checkpointer=MemorySaver(),
+        )
+
+        # Run the agent - both tools should be called in parallel
+        result = await agent.ainvoke(
+            {"messages": [HumanMessage(content="Search weather and flights")]},
+            {"configurable": {"thread_id": "test_parallel"}},
+        )
+
+        # Verify both tools were called and returned correct results
+        tool_messages = [
+            msg for msg in result["messages"] if isinstance(msg, ToolMessage)
+        ]
+        assert len(tool_messages) == 2
+
+        # Create a mapping of tool_call_id to content for easier assertion
+        results_by_id = {msg.tool_call_id: msg.content for msg in tool_messages}
+
+        # Verify the weather search was routed to the weather server
+        assert results_by_id["call_weather"] == [
+            {
+                "type": "text",
+                "text": "Weather results for: sunny in Paris",
+                "id": IsLangChainID,
+            }
+        ]
+
+        # Verify the flights search was routed to the flights server
+        assert results_by_id["call_flights"] == [
+            {
+                "type": "text",
+                "text": "Flight results to: Tokyo",
+                "id": IsLangChainID,
+            }
+        ]
+
+
+async def test_get_tools_with_name_conflict(socket_enabled) -> None:
+    """Test fetching tools with name conflict using tool_name_prefix.
+
+    This test verifies that:
+    1. Without tool_name_prefix, both servers would have conflicting "search" tool names
+    2. With tool_name_prefix=True, tools get unique names
+        (weather_search, flights_search)
+    """
+    with (
+        run_streamable_http(_create_weather_search_server, 8185),
+        run_streamable_http(_create_flights_search_server, 8186),
+    ):
+        # First, verify that without prefix both tools would have the same name
+        client_no_prefix = MultiServerMCPClient(
+            {
+                "weather": {
+                    "url": "http://localhost:8185/mcp",
+                    "transport": "streamable_http",
+                },
+                "flights": {
+                    "url": "http://localhost:8186/mcp",
+                    "transport": "streamable_http",
+                },
+            },
+            tool_name_prefix=False,
+        )
+        tools_no_prefix = await client_no_prefix.get_tools()
+        # Both tools are named "search" without prefix
+        assert all(t.name == "search" for t in tools_no_prefix)
+
+        # Now test with prefix - tools should be disambiguated
+        client = MultiServerMCPClient(
+            {
+                "weather": {
+                    "url": "http://localhost:8185/mcp",
+                    "transport": "streamable_http",
+                },
+                "flights": {
+                    "url": "http://localhost:8186/mcp",
+                    "transport": "streamable_http",
+                },
+            },
+            tool_name_prefix=True,
+        )
+        tools = await client.get_tools()
+
+        # Verify we have both prefixed tools with unique names
+        assert len(tools) == 2
+        tool_names = {t.name for t in tools}
+        assert tool_names == {"weather_search", "flights_search"}