Implementation of SEP 973 - Additional metadata + icons support (#1357)

Author: pja-ant

README.md

@@ -516,6 +516,41 @@ def debug_error(error: str) -> list[base.Message]:
 _Full example: [examples/snippets/servers/basic_prompt.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/basic_prompt.py)_
 <!-- /snippet-source -->
 
+### Icons
+
+MCP servers can provide icons for UI display. Icons can be added to the server implementation, tools, resources, and prompts:
+
+```python
+from mcp.server.fastmcp import FastMCP, Icon
+
+# Create an icon from a file path or URL
+icon = Icon(
+    src="icon.png",
+    mimeType="image/png",
+    sizes="64x64"
+)
+
+# Add icons to server
+mcp = FastMCP(
+    "My Server",
+    website_url="https://example.com",
+    icons=[icon]
+)
+
+# Add icons to tools, resources, and prompts
+@mcp.tool(icons=[icon])
+def my_tool():
+    """Tool with an icon."""
+    return "result"
+
+@mcp.resource("demo://resource", icons=[icon])
+def my_resource():
+    """Resource with an icon."""
+    return "content"
+```
+
+_Full example: [examples/fastmcp/icons_demo.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/fastmcp/icons_demo.py)_
+
 ### Images
 
 FastMCP provides an `Image` class that automatically handles image data:
@@ -898,6 +933,8 @@ The FastMCP server instance accessible via `ctx.fastmcp` provides access to serv
 
 - `ctx.fastmcp.name` - The server's name as defined during initialization
 - `ctx.fastmcp.instructions` - Server instructions/description provided to clients
+- `ctx.fastmcp.website_url` - Optional website URL for the server
+- `ctx.fastmcp.icons` - Optional list of icons for UI display
 - `ctx.fastmcp.settings` - Complete server configuration object containing:
   - `debug` - Debug mode flag
   - `log_level` - Current logging level

examples/fastmcp/icons_demo.py

@@ -0,0 +1,55 @@
+"""
+FastMCP Icons Demo Server
+
+Demonstrates using icons with tools, resources, prompts, and implementation.
+"""
+
+import base64
+from pathlib import Path
+
+from mcp.server.fastmcp import FastMCP, Icon
+
+# Load the icon file and convert to data URI
+icon_path = Path(__file__).parent / "mcp.png"
+icon_data = base64.standard_b64encode(icon_path.read_bytes()).decode()
+icon_data_uri = f"data:image/png;base64,{icon_data}"
+
+icon_data = Icon(src=icon_data_uri, mimeType="image/png", sizes="64x64")
+
+# Create server with icons in implementation
+mcp = FastMCP("Icons Demo Server", website_url="https://github.com/modelcontextprotocol/python-sdk", icons=[icon_data])
+
+
+@mcp.tool(icons=[icon_data])
+def demo_tool(message: str) -> str:
+    """A demo tool with an icon."""
+    return message
+
+
+@mcp.resource("demo://readme", icons=[icon_data])
+def readme_resource() -> str:
+    """A demo resource with an icon"""
+    return "This resource has an icon"
+
+
+@mcp.prompt("prompt_with_icon", icons=[icon_data])
+def prompt_with_icon(text: str) -> str:
+    """A demo prompt with an icon"""
+    return text
+
+
+@mcp.tool(
+    icons=[
+        Icon(src=icon_data_uri, mimeType="image/png", sizes="16x16"),
+        Icon(src=icon_data_uri, mimeType="image/png", sizes="32x32"),
+        Icon(src=icon_data_uri, mimeType="image/png", sizes="64x64"),
+    ]
+)
+def multi_icon_tool(action: str) -> str:
+    """A tool demonstrating multiple icons."""
+    return "multi_icon_tool"
+
+
+if __name__ == "__main__":
+    # Run the server
+    mcp.run()

examples/fastmcp/mcp.png

@@ -2,8 +2,10 @@
 
 from importlib.metadata import version
 
+from mcp.types import Icon
+
 from .server import Context, FastMCP
 from .utilities.types import Audio, Image
 
 __version__ = version("mcp")
-__all__ = ["FastMCP", "Context", "Image", "Audio"]
+__all__ = ["FastMCP", "Context", "Image", "Audio", "Icon"]

src/mcp/server/fastmcp/__init__.py

@@ -11,7 +11,7 @@
 
 from mcp.server.fastmcp.utilities.context_injection import find_context_parameter, inject_context
 from mcp.server.fastmcp.utilities.func_metadata import func_metadata
-from mcp.types import ContentBlock, TextContent
+from mcp.types import ContentBlock, Icon, TextContent
 
 if TYPE_CHECKING:
     from mcp.server.fastmcp.server import Context
@@ -71,6 +71,7 @@ class Prompt(BaseModel):
     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)
+    icons: list[Icon] | None = Field(default=None, description="Optional list of icons for this prompt")
     context_kwarg: str | None = Field(None, description="Name of the kwarg that should receive context", exclude=True)
 
     @classmethod
@@ -80,6 +81,7 @@ def from_function(
         name: str | None = None,
         title: str | None = None,
         description: str | None = None,
+        icons: list[Icon] | None = None,
         context_kwarg: str | None = None,
     ) -> Prompt:
         """Create a Prompt from a function.
@@ -128,6 +130,7 @@ def from_function(
             description=description or fn.__doc__ or "",
             arguments=arguments,
             fn=fn,
+            icons=icons,
             context_kwarg=context_kwarg,
         )
 

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

@@ -13,6 +13,8 @@
     field_validator,
 )
 
+from mcp.types import Icon
+
 
 class Resource(BaseModel, abc.ABC):
     """Base class for all resources."""
@@ -28,6 +30,7 @@ class Resource(BaseModel, abc.ABC):
         description="MIME type of the resource content",
         pattern=r"^[a-zA-Z0-9]+/[a-zA-Z0-9\-+.]+$",
     )
+    icons: list[Icon] | None = Field(default=None, description="Optional list of icons for this resource")
 
     @field_validator("name", mode="before")
     @classmethod

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

@@ -103,6 +103,7 @@ async def create_resource(
                 title=self.title,
                 description=self.description,
                 mime_type=self.mime_type,
+                icons=None,  # Resource templates don't support icons
                 fn=lambda: result,  # Capture result in closure
             )
         except Exception as e:

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

@@ -14,6 +14,7 @@
 from pydantic import AnyUrl, Field, ValidationInfo, validate_call
 
 from mcp.server.fastmcp.resources.base import Resource
+from mcp.types import Icon
 
 
 class TextResource(Resource):
@@ -80,6 +81,7 @@ def from_function(
         title: str | None = None,
         description: str | None = None,
         mime_type: str | None = None,
+        icons: list[Icon] | None = None,
     ) -> "FunctionResource":
         """Create a FunctionResource from a function."""
         func_name = name or fn.__name__
@@ -96,6 +98,7 @@ def from_function(
             description=description or fn.__doc__ or "",
             mime_type=mime_type or "text/plain",
             fn=fn,
+            icons=icons,
         )
 
 

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

@@ -43,7 +43,7 @@
 from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
 from mcp.server.transport_security import TransportSecuritySettings
 from mcp.shared.context import LifespanContextT, RequestContext, RequestT
-from mcp.types import AnyFunction, ContentBlock, GetPromptResult, ToolAnnotations
+from mcp.types import AnyFunction, ContentBlock, GetPromptResult, Icon, ToolAnnotations
 from mcp.types import Prompt as MCPPrompt
 from mcp.types import PromptArgument as MCPPromptArgument
 from mcp.types import Resource as MCPResource
@@ -120,10 +120,12 @@ async def wrap(_: MCPServer[LifespanResultT, Request]) -> AsyncIterator[Lifespan
 
 
 class FastMCP(Generic[LifespanResultT]):
-    def __init__(
+    def __init__(  # noqa: PLR0913
         self,
         name: str | None = None,
         instructions: str | None = None,
+        website_url: str | None = None,
+        icons: list[Icon] | None = None,
         auth_server_provider: OAuthAuthorizationServerProvider[Any, Any, Any] | None = None,
         token_verifier: TokenVerifier | None = None,
         event_store: EventStore | None = None,
@@ -170,6 +172,8 @@ def __init__(
         self._mcp_server = MCPServer(
             name=name or "FastMCP",
             instructions=instructions,
+            website_url=website_url,
+            icons=icons,
             # TODO(Marcelo): It seems there's a type mismatch between the lifespan type from an FastMCP and Server.
             # We need to create a Lifespan type that is a generic on the server type, like Starlette does.
             lifespan=(lifespan_wrapper(self, self.settings.lifespan) if self.settings.lifespan else default_lifespan),  # type: ignore
@@ -211,6 +215,14 @@ def name(self) -> str:
     def instructions(self) -> str | None:
         return self._mcp_server.instructions
 
+    @property
+    def website_url(self) -> str | None:
+        return self._mcp_server.website_url
+
+    @property
+    def icons(self) -> list[Icon] | None:
+        return self._mcp_server.icons
+
     @property
     def session_manager(self) -> StreamableHTTPSessionManager:
         """Get the StreamableHTTP session manager.
@@ -277,6 +289,7 @@ async def list_tools(self) -> list[MCPTool]:
                 inputSchema=info.parameters,
                 outputSchema=info.output_schema,
                 annotations=info.annotations,
+                icons=info.icons,
             )
             for info in tools
         ]
@@ -308,6 +321,7 @@ async def list_resources(self) -> list[MCPResource]:
                 title=resource.title,
                 description=resource.description,
                 mimeType=resource.mime_type,
+                icons=resource.icons,
             )
             for resource in resources
         ]
@@ -347,6 +361,7 @@ def add_tool(
         title: str | None = None,
         description: str | None = None,
         annotations: ToolAnnotations | None = None,
+        icons: list[Icon] | None = None,
         structured_output: bool | None = None,
     ) -> None:
         """Add a tool to the server.
@@ -371,6 +386,7 @@ def add_tool(
             title=title,
             description=description,
             annotations=annotations,
+            icons=icons,
             structured_output=structured_output,
         )
 
@@ -380,6 +396,7 @@ def tool(
         title: str | None = None,
         description: str | None = None,
         annotations: ToolAnnotations | None = None,
+        icons: list[Icon] | None = None,
         structured_output: bool | None = None,
     ) -> Callable[[AnyFunction], AnyFunction]:
         """Decorator to register a tool.
@@ -426,6 +443,7 @@ def decorator(fn: AnyFunction) -> AnyFunction:
                 title=title,
                 description=description,
                 annotations=annotations,
+                icons=icons,
                 structured_output=structured_output,
             )
             return fn
@@ -466,6 +484,7 @@ def resource(
         title: str | None = None,
         description: str | None = None,
         mime_type: str | None = None,
+        icons: list[Icon] | None = None,
     ) -> Callable[[AnyFunction], AnyFunction]:
         """Decorator to register a function as a resource.
 
@@ -540,6 +559,7 @@ def decorator(fn: AnyFunction) -> AnyFunction:
                     title=title,
                     description=description,
                     mime_type=mime_type,
+                    # Note: Resource templates don't support icons
                 )
             else:
                 # Register as regular resource
@@ -550,6 +570,7 @@ def decorator(fn: AnyFunction) -> AnyFunction:
                     title=title,
                     description=description,
                     mime_type=mime_type,
+                    icons=icons,
                 )
                 self.add_resource(resource)
             return fn
@@ -565,7 +586,11 @@ def add_prompt(self, prompt: Prompt) -> None:
         self._prompt_manager.add_prompt(prompt)
 
     def prompt(
-        self, name: str | None = None, title: str | None = None, description: str | None = None
+        self,
+        name: str | None = None,
+        title: str | None = None,
+        description: str | None = None,
+        icons: list[Icon] | None = None,
     ) -> Callable[[AnyFunction], AnyFunction]:
         """Decorator to register a prompt.
 
@@ -609,7 +634,7 @@ async def analyze_file(path: str) -> list[Message]:
             )
 
         def decorator(func: AnyFunction) -> AnyFunction:
-            prompt = Prompt.from_function(func, name=name, title=title, description=description)
+            prompt = Prompt.from_function(func, name=name, title=title, description=description, icons=icons)
             self.add_prompt(prompt)
             return func
 
@@ -980,6 +1005,7 @@ async def list_prompts(self) -> list[MCPPrompt]:
                     )
                     for arg in (prompt.arguments or [])
                 ],
+                icons=prompt.icons,
             )
             for prompt in prompts
         ]

src/mcp/server/fastmcp/server.py

@@ -11,7 +11,7 @@
 from mcp.server.fastmcp.exceptions import ToolError
 from mcp.server.fastmcp.utilities.context_injection import find_context_parameter
 from mcp.server.fastmcp.utilities.func_metadata import FuncMetadata, func_metadata
-from mcp.types import ToolAnnotations
+from mcp.types import Icon, ToolAnnotations
 
 if TYPE_CHECKING:
     from mcp.server.fastmcp.server import Context
@@ -33,6 +33,7 @@ class Tool(BaseModel):
     is_async: bool = Field(description="Whether the tool is async")
     context_kwarg: str | None = Field(None, description="Name of the kwarg that should receive context")
     annotations: ToolAnnotations | None = Field(None, description="Optional annotations for the tool")
+    icons: list[Icon] | None = Field(default=None, description="Optional list of icons for this tool")
 
     @cached_property
     def output_schema(self) -> dict[str, Any] | None:
@@ -47,6 +48,7 @@ def from_function(
         description: str | None = None,
         context_kwarg: str | None = None,
         annotations: ToolAnnotations | None = None,
+        icons: list[Icon] | None = None,
         structured_output: bool | None = None,
     ) -> Tool:
         """Create a Tool from a function."""
@@ -78,6 +80,7 @@ def from_function(
             is_async=is_async,
             context_kwarg=context_kwarg,
             annotations=annotations,
+            icons=icons,
         )
 
     async def run(