π The fast, Pythonic way to build MCP servers and clients.
Add tool_names parameter to mount() for name overrides (#2619)
Jeremiah Lowinb8ae95a4bbca
diff --git a/src/fastmcp/server/server.py b/src/fastmcp/server/server.pyindex eb0263d3f..6178b849a 100644--- a/src/fastmcp/server/server.py+++ b/src/fastmcp/server/server.py@@ -465,7 +465,7 @@ class FastMCP(Generic[LifespanResultT]):# execute in the parent's Docket contextfor mounted in self._mounted_servers:await self._register_mounted_server_functions(- mounted.server, docket, mounted.prefix+ mounted.server, docket, mounted.prefix, mounted.tool_names)# Set Docket in ContextVar so CurrentDocket can access it@@ -507,7 +507,11 @@ class FastMCP(Generic[LifespanResultT]):_current_server.reset(server_token)async def _register_mounted_server_functions(- self, server: FastMCP, docket: Docket, prefix: str | None+ self,+ server: FastMCP,+ docket: Docket,+ prefix: str | None,+ tool_names: dict[str, str] | None = None,) -> None:"""Register task-enabled functions from a mounted server with Docket.@@ -519,12 +523,18 @@ class FastMCP(Generic[LifespanResultT]):docket: The Docket instance to register withprefix: The mount prefix to prepend to function names (matchesclient-facing tool/prompt names)+ tool_names: Optional mapping of original tool names to custom names"""# Register tools with prefixed names to avoid collisionsfor tool in server._tool_manager._tools.values():if isinstance(tool, FunctionTool) and tool.task_config.mode != "forbidden":- # Use same naming as client-facing tool keys- fn_name = f"{prefix}_{tool.key}" if prefix else tool.key+ # Apply tool_names override first, then prefix (matches get_tools logic)+ if tool_names and tool.key in tool_names:+ fn_name = tool_names[tool.key]+ elif prefix:+ fn_name = f"{prefix}_{tool.key}"+ else:+ fn_name = tool.keynamed_fn = _create_named_fn_wrapper(tool.fn, fn_name)docket.register(named_fn)@@ -568,7 +578,7 @@ class FastMCP(Generic[LifespanResultT]):else (prefix or nested.prefix))await self._register_mounted_server_functions(- nested.server, docket, nested_prefix+ nested.server, docket, nested_prefix, nested.tool_names)@asynccontextmanager@@ -936,7 +946,13 @@ class FastMCP(Generic[LifespanResultT]):try:child_tools = await mounted.server.get_tools()for key, tool in child_tools.items():- new_key = f"{mounted.prefix}_{key}" if mounted.prefix else key+ # Check for manual override first, then apply prefix+ if mounted.tool_names and key in mounted.tool_names:+ new_key = mounted.tool_names[key]+ elif mounted.prefix:+ new_key = f"{mounted.prefix}_{key}"+ else:+ new_key = keyall_tools[new_key] = tool.model_copy(key=new_key)except Exception as e:logger.warning(@@ -1216,9 +1232,15 @@ class FastMCP(Generic[LifespanResultT]):if not self._should_enable_component(tool):continue- key = tool.key- if mounted.prefix:+ # Check for manual override first, then apply prefix+ if mounted.tool_names and tool.key in mounted.tool_names:+ key = mounted.tool_names[tool.key]+ elif mounted.prefix:key = f"{mounted.prefix}_{tool.key}"+ else:+ key = tool.key++ if key != tool.key:tool = tool.model_copy(key=key)# Later mounted servers override earlier onesall_tools[key] = tool@@ -1488,9 +1510,13 @@ class FastMCP(Generic[LifespanResultT]):if not self._should_enable_component(prompt):continue- key = prompt.key+ # Apply prefix to prompt keyif mounted.prefix:key = f"{mounted.prefix}_{prompt.key}"+ else:+ key = prompt.key++ if key != prompt.key:prompt = prompt.model_copy(key=key)# Later mounted servers override earlier onesall_prompts[key] = prompt@@ -1630,7 +1656,20 @@ class FastMCP(Generic[LifespanResultT]):# Try mounted servers in reverse order (later wins)for mounted in reversed(self._mounted_servers):try_name = tool_name- if mounted.prefix:++ # First check if tool_name is an overridden name (reverse lookup)+ if mounted.tool_names:+ for orig_key, override_name in mounted.tool_names.items():+ if override_name == tool_name:+ try_name = orig_key+ break+ else:+ # Not an override, try standard prefix stripping+ if mounted.prefix:+ if not tool_name.startswith(f"{mounted.prefix}_"):+ continue+ try_name = tool_name[len(mounted.prefix) + 1 :]+ elif mounted.prefix:if not tool_name.startswith(f"{mounted.prefix}_"):continuetry_name = tool_name[len(mounted.prefix) + 1 :]@@ -2649,6 +2688,7 @@ class FastMCP(Generic[LifespanResultT]):server: FastMCP[LifespanResultT],prefix: str | None = None,as_proxy: bool | None = None,+ tool_names: dict[str, str] | None = None,) -> None:"""Mount another FastMCP server on this server with an optional prefix.@@ -2693,6 +2733,9 @@ class FastMCP(Generic[LifespanResultT]):as_proxy: Whether to treat the mounted server as a proxy. If None (default),automatically determined based on whether the server has a custom lifespan(True if it has a custom lifespan, False otherwise).+ tool_names: Optional mapping of original tool names to custom names. Use this+ to override prefixed names. Keys are the original tool names from the+ mounted server."""from fastmcp.server.proxy import FastMCPProxy@@ -2713,6 +2756,7 @@ class FastMCP(Generic[LifespanResultT]):mounted_server = MountedServer(prefix=prefix,server=server,+ tool_names=tool_names,)self._mounted_servers.append(mounted_server)@@ -2972,6 +3016,7 @@ class FastMCP(Generic[LifespanResultT]):class MountedServer:prefix: str | Noneserver: FastMCP[Any]+ tool_names: dict[str, str] | None = Nonedef add_resource_prefix(uri: str, prefix: str) -> str:diff --git a/tests/server/test_mount.py b/tests/server/test_mount.pyindex 928a0b8a0..5c23eaf80 100644--- a/tests/server/test_mount.py+++ b/tests/server/test_mount.py@@ -1361,3 +1361,66 @@ class TestDeeplyNestedMount:# Tool at level 4 should workresult = await client.call_tool("l1_l2_l3_deep_tool", {})assert result.data == "very deep"+++class TestToolNameOverrides:+ """Test tool and prompt name overrides in mount() (issue #2596)."""++ async def test_tool_names_override_applied_in_get_tools(self):+ """Test that tool_names override is reflected in get_tools()."""+ sub = FastMCP("Sub")++ @sub.tool+ def original_tool() -> str:+ return "test"++ main = FastMCP("Main")+ main.mount(+ sub,+ prefix="prefix",+ tool_names={"original_tool": "custom_name"},+ )++ tools = await main.get_tools()+ assert "custom_name" in tools+ assert "prefix_original_tool" not in tools++ async def test_tool_names_override_applied_in_list_tools(self):+ """Test that tool_names override is reflected in list_tools()."""+ sub = FastMCP("Sub")++ @sub.tool+ def original_tool() -> str:+ return "test"++ main = FastMCP("Main")+ main.mount(+ sub,+ prefix="prefix",+ tool_names={"original_tool": "custom_name"},+ )++ async with Client(main) as client:+ tools = await client.list_tools()+ tool_names = [t.name for t in tools]+ assert "custom_name" in tool_names+ assert "prefix_original_tool" not in tool_names++ async def test_tool_call_with_overridden_name(self):+ """Test that overridden tool can be called by its new name."""+ sub = FastMCP("Sub")++ @sub.tool+ def original_tool() -> str:+ return "success"++ main = FastMCP("Main")+ main.mount(+ sub,+ prefix="prefix",+ tool_names={"original_tool": "renamed"},+ )++ async with Client(main) as client:+ result = await client.call_tool("renamed", {})+ assert result.data == "success"