chore: Bump FastMCP to v3.x and make the necessary changes to support it (#425)

Co-authored-by: Oliver Meyer <42039965+olivermeyer@users.noreply.github.com>

Author: neelay-aign

pyproject.toml

@@ -125,6 +125,7 @@ dependencies = [
     "truststore>=0.10.4,<1",
     "urllib3>=2.6.3,<3", # CVE-2026-21441 requires >= 2.6.3
     "wsidicom>=0.28.1,<1",
+    "fastmcp>=3.0.0,<4",
     # Transitive overrides
     # WARNING: one cannot negate or downgrade a dependency required here. use override-dependencies for that.
     "rfc3987; sys_platform == 'never'", # GPLv3
@@ -138,7 +139,6 @@ dependencies = [
     "lxml>=6.0.2",                      # For python 3.14 pre-built wheels
     "filelock>=3.20.1",                 # CVE-2025-68146
     "marshmallow>=3.26.2",              # CVE-2025-68480
-    "fastmcp>=2.0.0,<3",                # MCP server - Major version 3 is in beta as of 26/01/2026 and has not been released on PyPI. Upgrade once a stable release is out.
 ]
 
 [project.optional-dependencies]

src/aignostics/utils/_mcp.py

@@ -54,7 +54,7 @@ def mcp_create_server(server_name: str = MCP_SERVER_NAME) -> FastMCP:
 
     Creates a new FastMCP server instance and mounts all discovered MCP servers
     from the SDK and plugins. Each mounted server's tools are namespaced
-    automatically using FastMCP's built-in prefix feature.
+    automatically using FastMCP's built-in namespace feature.
 
     Args:
         server_name: Human-readable name for the MCP server.
@@ -76,7 +76,7 @@ def mcp_create_server(server_name: str = MCP_SERVER_NAME) -> FastMCP:
                 continue
             seen_names.add(server.name)
             logger.info(f"Mounting MCP server: {server.name}")
-            mcp.mount(server, prefix=server.name)
+            mcp.mount(server, namespace=server.name)
             count += 1
 
     logger.info(f"Mounted {count} MCP servers")
@@ -115,7 +115,7 @@ def mcp_list_tools(server_name: str = MCP_SERVER_NAME) -> list[dict[str, Any]]:
             'name' and 'description' keys.
     """
     server = mcp_create_server(server_name)
-    # FastMCP's get_tools() is async because mounted servers may need to
+    # FastMCP's list_tools() is async because mounted servers may need to
     # lazily initialize resources. We use asyncio.run() to bridge sync/async.
-    tools = asyncio.run(server.get_tools())
-    return [{"name": name, "description": tool.description or ""} for name, tool in tools.items()]
+    tools = asyncio.run(server.list_tools())
+    return [{"name": tool.name, "description": tool.description or ""} for tool in tools]

tests/aignostics/utils/mcp_test.py

@@ -98,8 +98,8 @@ def plugin2_tool() -> str:
         assert isinstance(server, FastMCP)
         assert server.name == MCP_SERVER_NAME
         # Verify exactly 2 tools from both plugins are mounted with namespacing
-        tools = asyncio.run(server.get_tools())
-        tool_names = list(tools.keys())
+        tools = asyncio.run(server.list_tools())
+        tool_names = [t.name for t in tools]
         assert len(tool_names) == 2
         # Verify namespacing: tools should be prefixed with server name
         plugin1_tools = [n for n in tool_names if "plugin1" in n]
@@ -139,8 +139,8 @@ def unique_tool() -> str:
         # Verify warning was logged for duplicate
         assert "Duplicate MCP server name 'duplicate_name'" in caplog.text
         # Verify only first duplicate and unique server were mounted (2 servers, not 3)
-        tools = asyncio.run(server.get_tools())
-        tool_names = list(tools.keys())
+        tools = asyncio.run(server.list_tools())
+        tool_names = [t.name for t in tools]
         assert len(tool_names) == 2
         # dup1_tool should be present (first occurrence)
         assert any("dup1_tool" in name for name in tool_names)

tests/resources/mcp_dummy_plugin/pyproject.toml

@@ -7,7 +7,7 @@ name = "mcp-dummy-plugin"
 version = "0.0.1"
 description = "Dummy MCP plugin for integration testing of plugin auto-discovery."
 requires-python = ">=3.11"
-dependencies = ["fastmcp>=2.0.0,<3", "typer>=0.12", "aignostics"]
+dependencies = ["fastmcp>=3.0.0,<4", "typer>=0.12", "aignostics"]
 
 [project.entry-points."aignostics.plugins"]
 mcp_dummy_plugin = "mcp_dummy_plugin"