feat: add title field support to FastMCP

Add optional title field to tools, resources, prompts, and resource templates
in FastMCP to enable human-readable display names. Also includes a utility
function get_display_name() for consistent title/name precedence handling.

- Add title parameter to @tool, @resource, and @prompt decorators
- Add title field to Tool, Resource, Prompt, and ResourceTemplate models
- Implement get_display_name() utility with proper precedence rules
- Add comprehensive tests for title functionality

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: felixweinberger

src/mcp/server/fastmcp/prompts/base.py

@@ -58,6 +58,7 @@ class Prompt(BaseModel):
     """A prompt template that can be rendered with parameters."""
 
     name: str = Field(description="Name of the prompt")
+    title: str | None = Field(None, description="Human-readable title of the prompt")
     description: str | None = Field(None, description="Description of what the prompt does")
     arguments: list[PromptArgument] | None = Field(None, description="Arguments that can be passed to the prompt")
     fn: Callable[..., PromptResult | Awaitable[PromptResult]] = Field(exclude=True)
@@ -67,6 +68,7 @@ def from_function(
         cls,
         fn: Callable[..., PromptResult | Awaitable[PromptResult]],
         name: str | None = None,
+        title: str | None = None,
         description: str | None = None,
     ) -> "Prompt":
         """Create a Prompt from a function.
@@ -103,6 +105,7 @@ def from_function(
 
         return cls(
             name=func_name,
+            title=title,
             description=description or fn.__doc__ or "",
             arguments=arguments,
             fn=fn,

src/mcp/server/fastmcp/resources/base.py

@@ -21,6 +21,7 @@ class Resource(BaseModel, abc.ABC):
 
     uri: Annotated[AnyUrl, UrlConstraints(host_required=False)] = Field(default=..., description="URI of the resource")
     name: str | None = Field(description="Name of the resource", default=None)
+    title: str | None = Field(description="Human-readable title of the resource", default=None)
     description: str | None = Field(description="Description of the resource", default=None)
     mime_type: str = Field(
         default="text/plain",

src/mcp/server/fastmcp/resources/resource_manager.py

@@ -51,6 +51,7 @@ def add_template(
         fn: Callable[..., Any],
         uri_template: str,
         name: str | None = None,
+        title: str | None = None,
         description: str | None = None,
         mime_type: str | None = None,
     ) -> ResourceTemplate:
@@ -59,6 +60,7 @@ def add_template(
             fn,
             uri_template=uri_template,
             name=name,
+            title=title,
             description=description,
             mime_type=mime_type,
         )

src/mcp/server/fastmcp/resources/templates.py

@@ -17,6 +17,7 @@ class ResourceTemplate(BaseModel):
 
     uri_template: str = Field(description="URI template with parameters (e.g. weather://{city}/current)")
     name: str = Field(description="Name of the resource")
+    title: str | None = Field(description="Human-readable title of the resource", default=None)
     description: str | None = Field(description="Description of what the resource does")
     mime_type: str = Field(default="text/plain", description="MIME type of the resource content")
     fn: Callable[..., Any] = Field(exclude=True)
@@ -28,6 +29,7 @@ def from_function(
         fn: Callable[..., Any],
         uri_template: str,
         name: str | None = None,
+        title: str | None = None,
         description: str | None = None,
         mime_type: str | None = None,
     ) -> ResourceTemplate:
@@ -45,6 +47,7 @@ def from_function(
         return cls(
             uri_template=uri_template,
             name=func_name,
+            title=title,
             description=description or fn.__doc__ or "",
             mime_type=mime_type or "text/plain",
             fn=fn,
@@ -71,6 +74,7 @@ async def create_resource(self, uri: str, params: dict[str, Any]) -> Resource:
             return FunctionResource(
                 uri=uri,  # type: ignore
                 name=self.name,
+                title=self.title,
                 description=self.description,
                 mime_type=self.mime_type,
                 fn=lambda: result,  # Capture result in closure

src/mcp/server/fastmcp/resources/types.py

@@ -72,6 +72,7 @@ def from_function(
         fn: Callable[..., Any],
         uri: str,
         name: str | None = None,
+        title: str | None = None,
         description: str | None = None,
         mime_type: str | None = None,
     ) -> "FunctionResource":
@@ -86,6 +87,7 @@ def from_function(
         return cls(
             uri=AnyUrl(uri),
             name=func_name,
+            title=title,
             description=description or fn.__doc__ or "",
             mime_type=mime_type or "text/plain",
             fn=fn,

src/mcp/server/fastmcp/server.py

@@ -236,6 +236,7 @@ async def list_tools(self) -> list[MCPTool]:
         return [
             MCPTool(
                 name=info.name,
+                title=info.title,
                 description=info.description,
                 inputSchema=info.parameters,
                 annotations=info.annotations,
@@ -269,6 +270,7 @@ async def list_resources(self) -> list[MCPResource]:
             MCPResource(
                 uri=resource.uri,
                 name=resource.name or "",
+                title=resource.title,
                 description=resource.description,
                 mimeType=resource.mime_type,
             )
@@ -281,6 +283,7 @@ async def list_resource_templates(self) -> list[MCPResourceTemplate]:
             MCPResourceTemplate(
                 uriTemplate=template.uri_template,
                 name=template.name,
+                title=template.title,
                 description=template.description,
             )
             for template in templates
@@ -304,6 +307,7 @@ def add_tool(
         self,
         fn: AnyFunction,
         name: str | None = None,
+        title: str | None = None,
         description: str | None = None,
         annotations: ToolAnnotations | None = None,
     ) -> None:
@@ -315,14 +319,16 @@ def add_tool(
         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
         """
-        self._tool_manager.add_tool(fn, name=name, description=description, annotations=annotations)
+        self._tool_manager.add_tool(fn, name=name, title=title, description=description, annotations=annotations)
 
     def tool(
         self,
         name: str | None = None,
+        title: str | None = None,
         description: str | None = None,
         annotations: ToolAnnotations | None = None,
     ) -> Callable[[AnyFunction], AnyFunction]:
@@ -334,6 +340,7 @@ def tool(
 
         Args:
             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
 
@@ -359,7 +366,7 @@ async def async_tool(x: int, context: Context) -> str:
             )
 
         def decorator(fn: AnyFunction) -> AnyFunction:
-            self.add_tool(fn, name=name, description=description, annotations=annotations)
+            self.add_tool(fn, name=name, title=title, description=description, annotations=annotations)
             return fn
 
         return decorator
@@ -377,6 +384,7 @@ def resource(
         uri: str,
         *,
         name: str | None = None,
+        title: str | None = None,
         description: str | None = None,
         mime_type: str | None = None,
     ) -> Callable[[AnyFunction], AnyFunction]:
@@ -394,6 +402,7 @@ def resource(
         Args:
             uri: URI for the resource (e.g. "resource://my-resource" or "resource://{param}")
             name: Optional name for the resource
+            title: Optional human-readable title for the resource
             description: Optional description of the resource
             mime_type: Optional MIME type for the resource
 
@@ -443,6 +452,7 @@ def decorator(fn: AnyFunction) -> AnyFunction:
                     fn=fn,
                     uri_template=uri,
                     name=name,
+                    title=title,
                     description=description,
                     mime_type=mime_type,
                 )
@@ -452,6 +462,7 @@ def decorator(fn: AnyFunction) -> AnyFunction:
                     fn=fn,
                     uri=uri,
                     name=name,
+                    title=title,
                     description=description,
                     mime_type=mime_type,
                 )
@@ -468,11 +479,14 @@ def add_prompt(self, prompt: Prompt) -> None:
         """
         self._prompt_manager.add_prompt(prompt)
 
-    def prompt(self, name: str | None = None, description: str | None = None) -> Callable[[AnyFunction], AnyFunction]:
+    def prompt(
+        self, name: str | None = None, title: str | None = None, description: str | None = None
+    ) -> Callable[[AnyFunction], AnyFunction]:
         """Decorator to register a prompt.
 
         Args:
             name: Optional name for the prompt (defaults to function name)
+            title: Optional human-readable title for the prompt
             description: Optional description of what the prompt does
 
         Example:
@@ -510,7 +524,7 @@ async def analyze_file(path: str) -> list[Message]:
             )
 
         def decorator(func: AnyFunction) -> AnyFunction:
-            prompt = Prompt.from_function(func, name=name, description=description)
+            prompt = Prompt.from_function(func, name=name, title=title, description=description)
             self.add_prompt(prompt)
             return func
 
@@ -812,6 +826,7 @@ async def list_prompts(self) -> list[MCPPrompt]:
         return [
             MCPPrompt(
                 name=prompt.name,
+                title=prompt.title,
                 description=prompt.description,
                 arguments=[
                     MCPPromptArgument(

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

@@ -22,6 +22,7 @@ class Tool(BaseModel):
 
     fn: Callable[..., Any] = Field(exclude=True)
     name: str = Field(description="Name of the tool")
+    title: str | None = Field(None, description="Human-readable title of the tool")
     description: str = Field(description="Description of what the tool does")
     parameters: dict[str, Any] = Field(description="JSON schema for tool parameters")
     fn_metadata: FuncMetadata = Field(
@@ -36,6 +37,7 @@ def from_function(
         cls,
         fn: Callable[..., Any],
         name: str | None = None,
+        title: str | None = None,
         description: str | None = None,
         context_kwarg: str | None = None,
         annotations: ToolAnnotations | None = None,
@@ -69,6 +71,7 @@ def from_function(
         return cls(
             fn=fn,
             name=func_name,
+            title=title,
             description=func_doc,
             parameters=parameters,
             fn_metadata=func_arg_metadata,

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

@@ -46,11 +46,12 @@ def add_tool(
         self,
         fn: Callable[..., Any],
         name: str | None = None,
+        title: str | None = None,
         description: str | None = None,
         annotations: ToolAnnotations | None = None,
     ) -> Tool:
         """Add a tool to the server."""
-        tool = Tool.from_function(fn, name=name, description=description, annotations=annotations)
+        tool = Tool.from_function(fn, name=name, title=title, description=description, annotations=annotations)
         existing = self._tools.get(tool.name)
         if existing:
             if self.warn_on_duplicate_tools:

src/mcp/shared/metadata_utils.py

@@ -0,0 +1,30 @@
+"""Utility functions for working with metadata in MCP types."""
+
+from mcp.types import Implementation, Prompt, Resource, ResourceTemplate, Tool
+
+
+def get_display_name(obj: Tool | Resource | Prompt | ResourceTemplate | Implementation) -> str:
+    """
+    Get the display name for an MCP object with proper precedence.
+
+    For tools: title > annotations.title > name
+    For other objects: title > name
+
+    Args:
+        obj: An MCP object with name and optional title fields
+
+    Returns:
+        The display name to use for UI presentation
+    """
+    if isinstance(obj, Tool):
+        # Tools have special precedence: title > annotations.title > name
+        if hasattr(obj, "title") and obj.title is not None:
+            return obj.title
+        if obj.annotations and hasattr(obj.annotations, "title") and obj.annotations.title is not None:
+            return obj.annotations.title
+        return obj.name
+    else:
+        # All other objects: title > name
+        if hasattr(obj, "title") and obj.title is not None:
+            return obj.title
+        return obj.name