refactor!: make tool registration object-based

BREAKING CHANGE: MCPServer.add_tool() and ToolManager.add_tool() now require prebuilt Tool objects. Use Tool.from_function() or the @mcp.tool() decorator to construct tools before registration.

Author: mplemay

docs/migration.md

@@ -428,6 +428,34 @@ async def my_tool(x: int, ctx: Context) -> str:
 
 The internal layers (`ToolManager.call_tool`, `Tool.run`, `Prompt.render`, `ResourceTemplate.create_resource`, etc.) now require `context` as a positional argument.
 
+### Tool registration now accepts prebuilt `Tool` objects
+
+`MCPServer.add_tool()` and `ToolManager.add_tool()` now expect a fully constructed `Tool` instance, matching the resource registration pattern. Build tools with `Tool.from_function(...)` or register them through the `@mcp.tool()` decorator, which still handles construction for you.
+
+**Before (v1):**
+
+```python
+def add(a: int, b: int) -> int:
+    return a + b
+
+mcp.add_tool(add)
+```
+
+**After (v2):**
+
+```python
+from mcp.server.mcpserver.tools import Tool
+
+
+def add(a: int, b: int) -> int:
+    return a + b
+
+
+mcp.add_tool(Tool.from_function(add))
+```
+
+If you need to customize the tool metadata before registration, build the `Tool` first and then pass it to `add_tool()`.
+
 ### Registering lowlevel handlers on `MCPServer` (workaround)
 
 `MCPServer` does not expose public APIs for `subscribe_resource`, `unsubscribe_resource`, or `set_logging_level` handlers. In v1, the workaround was to reach into the private lowlevel server and use its decorator methods:

src/mcp/server/mcpserver/server.py

@@ -455,45 +455,13 @@ async def read_resource(
             # If an exception happens when reading the resource, we should not leak the exception to the client.
             raise ResourceError(f"Error reading resource {uri}") from exc
 
-    def add_tool(
-        self,
-        fn: Callable[..., Any],
-        name: str | None = None,
-        title: str | None = None,
-        description: str | None = None,
-        annotations: ToolAnnotations | None = None,
-        icons: list[Icon] | None = None,
-        meta: dict[str, Any] | None = None,
-        structured_output: bool | None = None,
-    ) -> None:
+    def add_tool(self, tool: Tool) -> None:
         """Add a tool to the server.
 
-        The tool function can optionally request a Context object by adding a parameter
-        with the Context type annotation. See the @tool decorator for examples.
-
         Args:
-            fn: The function to register as a tool
-            name: Optional name for the tool (defaults to function name)
-            title: Optional human-readable title for the tool
-            description: Optional description of what the tool does
-            annotations: Optional ToolAnnotations providing additional tool information
-            icons: Optional list of icons for the tool
-            meta: Optional metadata dictionary for the tool
-            structured_output: Controls whether the tool's output is structured or unstructured
-                - If None, auto-detects based on the function's return type annotation
-                - If True, creates a structured tool (return type annotation permitting)
-                - If False, unconditionally creates an unstructured tool
+            tool: A Tool instance to add
         """
-        self._tool_manager.add_tool(
-            fn,
-            name=name,
-            title=title,
-            description=description,
-            annotations=annotations,
-            icons=icons,
-            meta=meta,
-            structured_output=structured_output,
-        )
+        self._tool_manager.add_tool(tool)
 
     def remove_tool(self, name: str) -> None:
         """Remove a tool from the server by name.
@@ -562,7 +530,7 @@ async def async_tool(x: int, context: Context) -> str:
             )
 
         def decorator(fn: _CallableT) -> _CallableT:
-            self.add_tool(
+            tool = Tool.from_function(
                 fn,
                 name=name,
                 title=title,
@@ -572,6 +540,7 @@ def decorator(fn: _CallableT) -> _CallableT:
                 meta=meta,
                 structured_output=structured_output,
             )
+            self.add_tool(tool)
             return fn
 
         return decorator

src/mcp/server/mcpserver/tools/base.py

@@ -4,7 +4,7 @@
 from functools import cached_property
 from typing import TYPE_CHECKING, Any
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, field_validator
 
 from mcp.server.mcpserver.exceptions import ToolError
 from mcp.server.mcpserver.utilities.context_injection import find_context_parameter
@@ -36,6 +36,12 @@ class Tool(BaseModel):
     icons: list[Icon] | None = Field(default=None, description="Optional list of icons for this tool")
     meta: dict[str, Any] | None = Field(default=None, description="Optional metadata for this tool")
 
+    @field_validator("name")
+    @classmethod
+    def validate_name(cls, name: str) -> str:
+        validate_and_warn_tool_name(name)
+        return name
+
     @cached_property
     def output_schema(self) -> dict[str, Any] | None:
         return self.fn_metadata.output_schema
@@ -56,8 +62,6 @@ def from_function(
         """Create a Tool from a function."""
         func_name = name or fn.__name__
 
-        validate_and_warn_tool_name(func_name)
-
         if func_name == "<lambda>":
             raise ValueError("You must provide a name for lambda functions")
 

src/mcp/server/mcpserver/tools/tool_manager.py

@@ -1,12 +1,10 @@
 from __future__ import annotations
 
-from collections.abc import Callable
 from typing import TYPE_CHECKING, Any
 
 from mcp.server.mcpserver.exceptions import ToolError
 from mcp.server.mcpserver.tools.base import Tool
 from mcp.server.mcpserver.utilities.logging import get_logger
-from mcp.types import Icon, ToolAnnotations
 
 if TYPE_CHECKING:
     from mcp.server.context import LifespanContextT, RequestT
@@ -25,13 +23,10 @@ def __init__(
         tools: list[Tool] | None = None,
     ):
         self._tools: dict[str, Tool] = {}
+        self.warn_on_duplicate_tools = warn_on_duplicate_tools
         if tools is not None:
             for tool in tools:
-                if warn_on_duplicate_tools and tool.name in self._tools:
-                    logger.warning(f"Tool already exists: {tool.name}")
-                self._tools[tool.name] = tool
-
-        self.warn_on_duplicate_tools = warn_on_duplicate_tools
+                self.add_tool(tool)
 
     def get_tool(self, name: str) -> Tool | None:
         """Get tool by name."""
@@ -43,26 +38,9 @@ def list_tools(self) -> list[Tool]:
 
     def add_tool(
         self,
-        fn: Callable[..., Any],
-        name: str | None = None,
-        title: str | None = None,
-        description: str | None = None,
-        annotations: ToolAnnotations | None = None,
-        icons: list[Icon] | None = None,
-        meta: dict[str, Any] | None = None,
-        structured_output: bool | None = None,
+        tool: Tool,
     ) -> Tool:
-        """Add a tool to the server."""
-        tool = Tool.from_function(
-            fn,
-            name=name,
-            title=title,
-            description=description,
-            annotations=annotations,
-            icons=icons,
-            meta=meta,
-            structured_output=structured_output,
-        )
+        """Add a tool to the manager."""
         existing = self._tools.get(tool.name)
         if existing:
             if self.warn_on_duplicate_tools: