Merge pull request #792 from jlowin/tags

docs/servers/openapi.mdx

@@ -51,6 +51,7 @@ Each `RouteMap` specifies a combination of methods, patterns, and tags, as well
 - **Pattern**: Regex pattern to match the route path (e.g. `r"^/users/.*"` or `r".*"` for all)
 - **Tags**: A set of OpenAPI tags that must all be present. An empty set (`{}`) means no tag filtering, so the route matches regardless of its tags.
 - **MCP type**: What MCP component type to create (`TOOL`, `RESOURCE`, `RESOURCE_TEMPLATE`, or `EXCLUDE`)
+- **MCP tags** A set of custom tags to add to components created from matching routes
 
 Here is FastMCP's default rule:
 
@@ -206,9 +207,76 @@ mcp = FastMCP.from_openapi(
 
 ## Customizing MCP Components
 
+### Tags
 
+<VersionBadge version="2.8.0" />
 
-### Component Names
+FastMCP provides several ways to add tags to your MCP components, allowing you to categorize and organize them for better discoverability and filtering. Tags are combined from multiple sources to create the final set of tags on each component.
+
+#### RouteMap Tags
+
+You can add custom tags to components created from specific routes using the `mcp_tags` parameter in `RouteMap`. These tags will be applied to all components created from routes that match that particular route map.
+
+```python {12, 20, 28}
+from fastmcp import FastMCP
+from fastmcp.server.openapi import RouteMap, MCPType
+
+mcp = FastMCP.from_openapi(
+    ...,
+    route_maps=[
+        # Add custom tags to all POST endpoints
+        RouteMap(
+            methods=["POST"],
+            pattern=r".*",
+            mcp_type=MCPType.TOOL,
+            mcp_tags={"write-operation", "api-mutation"}
+        ),
+        
+        # Add different tags to detail view endpoints
+        RouteMap(
+            methods=["GET"],
+            pattern=r".*\{.*\}.*",
+            mcp_type=MCPType.RESOURCE_TEMPLATE,
+            mcp_tags={"detail-view", "parameterized"}
+        ),
+        
+        # Add tags to list endpoints
+        RouteMap(
+            methods=["GET"],
+            pattern=r".*",
+            mcp_type=MCPType.RESOURCE,
+            mcp_tags={"list-data", "collection"}
+        ),
+    ],
+)
+```
+
+#### Global Tags
+
+You can add tags to **all** components by providing a `tags` parameter when creating your FastMCP server with `from_openapi` or `from_fastapi`. These global tags will be applied to every component created from your OpenAPI specification.
+
+<CodeGroup>
+```python {6} from_openapi()
+from fastmcp import FastMCP
+
+mcp = FastMCP.from_openapi(
+    openapi_spec=spec,
+    client=client,
+    tags={"api-v2", "production", "external"}
+)
+```
+```python {5} from_fastapi()
+from fastmcp import FastMCP
+
+mcp = FastMCP.from_fastapi(
+    app=app,
+    tags={"internal-api", "microservice"}
+)
+```
+</CodeGroup>
+
+
+### Names
 
 <VersionBadge version="2.5.0" />
 
@@ -421,10 +489,16 @@ mcp = FastMCP.from_fastapi(
     app=app,
     name="My Custom Server",
     timeout=5.0,
+    tags={"api-v1", "fastapi"},  # Global tags for all components
     mcp_names={"operationId": "friendly_name"},  # Custom component names
     route_maps=[
-        # Admin endpoints become tools
-        RouteMap(methods="*", pattern=r"^/admin/.*", mcp_type=MCPType.TOOL),
+        # Admin endpoints become tools with custom tags
+        RouteMap(
+            methods="*", 
+            pattern=r"^/admin/.*", 
+            mcp_type=MCPType.TOOL,
+            mcp_tags={"admin", "privileged"}
+        ),
         # Internal endpoints are excluded
         RouteMap(methods="*", pattern=r".*", mcp_type=MCPType.EXCLUDE, tags={"internal"}),
     ],

src/fastmcp/server/server.py

@@ -121,7 +121,6 @@ class FastMCP(Generic[LifespanResultT]):
             ]
             | None
         ) = None,
-        tags: set[str] | None = None,
         tool_serializer: Callable[[Any], str] | None = None,
         cache_expiration_seconds: float | None = None,
         on_duplicate_tools: DuplicateBehavior | None = None,
@@ -152,8 +151,6 @@ class FastMCP(Generic[LifespanResultT]):
             resource_prefix_format or fastmcp.settings.resource_prefix_format
         )
 
-        self.tags: set[str] = tags or set()
-
         self._cache = TimedCache(
             expiration=datetime.timedelta(seconds=cache_expiration_seconds or 0)
         )
@@ -1561,6 +1558,7 @@ class FastMCP(Generic[LifespanResultT]):
         route_map_fn: OpenAPIRouteMapFn | None = None,
         mcp_component_fn: OpenAPIComponentFn | None = None,
         mcp_names: dict[str, str] | None = None,
+        tags: set[str] | None = None,
         **settings: Any,
     ) -> FastMCPOpenAPI:
         """
@@ -1575,6 +1573,7 @@ class FastMCP(Generic[LifespanResultT]):
             route_map_fn=route_map_fn,
             mcp_component_fn=mcp_component_fn,
             mcp_names=mcp_names,
+            tags=tags,
             **settings,
         )
 
@@ -1588,6 +1587,7 @@ class FastMCP(Generic[LifespanResultT]):
         mcp_component_fn: OpenAPIComponentFn | None = None,
         mcp_names: dict[str, str] | None = None,
         httpx_client_kwargs: dict[str, Any] | None = None,
+        tags: set[str] | None = None,
         **settings: Any,
     ) -> FastMCPOpenAPI:
         """
@@ -1615,6 +1615,7 @@ class FastMCP(Generic[LifespanResultT]):
             route_map_fn=route_map_fn,
             mcp_component_fn=mcp_component_fn,
             mcp_names=mcp_names,
+            tags=tags,
             **settings,
         )
 

tests/deprecated/test_settings.py

@@ -175,7 +175,6 @@ class TestDeprecatedServerInitKwargs:
             server = FastMCP(
                 name="TestServer",
                 instructions="Test instructions",
-                tags={"test", "server"},
                 cache_expiration_seconds=60.0,
                 on_duplicate_tools="warn",
                 on_duplicate_resources="error",
@@ -193,7 +192,6 @@ class TestDeprecatedServerInitKwargs:
         # Verify server was created successfully
         assert server.name == "TestServer"
         assert server.instructions == "Test instructions"
-        assert server.tags == {"test", "server"}
 
     def test_none_values_no_warnings(self):
         """Test that None values for deprecated kwargs don't raise warnings."""

tests/server/openapi/test_openapi.py

@@ -2709,25 +2709,22 @@ class TestGlobalTagsParameter:
         )
 
         # Check tool has both original and global tags
-        tools = server._tool_manager.list_tools()
-        create_item_tool = next((t for t in tools if "create_item" in t.name), None)
-        assert create_item_tool is not None
+        tools = await server.get_tools()
+        create_item_tool = tools["create_item_items_post"]
         assert "items" in create_item_tool.tags  # Original OpenAPI tag
         assert "global" in create_item_tool.tags  # Global tag
         assert "api-v1" in create_item_tool.tags  # Global tag
 
         # Check resource has both original and global tags
-        resources = list(server._resource_manager.get_resources().values())
-        get_items_resource = next((r for r in resources if "get_items" in r.name), None)
-        assert get_items_resource is not None
+        resources = await server.get_resources()
+        get_items_resource = resources["resource://get_items_items_get"]
         assert "items" in get_items_resource.tags  # Original OpenAPI tag
         assert "global" in get_items_resource.tags  # Global tag
         assert "api-v1" in get_items_resource.tags  # Global tag
 
         # Check resource template has both original and global tags
-        templates = list(server._resource_manager.get_templates().values())
-        get_item_template = next((t for t in templates if "get_item" in t.name), None)
-        assert get_item_template is not None
+        templates = await server.get_resource_templates()
+        get_item_template = templates["resource://get_item_items/{item_id}"]
         assert "items" in get_item_template.tags  # Original OpenAPI tag
         assert "global" in get_item_template.tags  # Global tag
         assert "api-v1" in get_item_template.tags  # Global tag
@@ -2754,25 +2751,22 @@ class TestGlobalTagsParameter:
         )
 
         # Check tool has both original and global tags
-        tools = server._tool_manager.list_tools()
-        create_item_tool = next((t for t in tools if "create_item" in t.name), None)
-        assert create_item_tool is not None
+        tools = await server.get_tools()
+        create_item_tool = tools["create_item_items_post"]
         assert "items" in create_item_tool.tags  # Original OpenAPI tag
         assert "openapi-global" in create_item_tool.tags  # Global tag
         assert "service" in create_item_tool.tags  # Global tag
 
         # Check resource has both original and global tags
-        resources = list(server._resource_manager.get_resources().values())
-        get_items_resource = next((r for r in resources if "get_items" in r.name), None)
-        assert get_items_resource is not None
+        resources = await server.get_resources()
+        get_items_resource = resources["resource://get_items_items_get"]
         assert "items" in get_items_resource.tags  # Original OpenAPI tag
         assert "openapi-global" in get_items_resource.tags  # Global tag
         assert "service" in get_items_resource.tags  # Global tag
 
         # Check resource template has both original and global tags
-        templates = list(server._resource_manager.get_templates().values())
-        get_item_template = next((t for t in templates if "get_item" in t.name), None)
-        assert get_item_template is not None
+        templates = await server.get_resource_templates()
+        get_item_template = templates["resource://get_item_items/{item_id}"]
         assert "items" in get_item_template.tags  # Original OpenAPI tag
         assert "openapi-global" in get_item_template.tags  # Global tag
         assert "service" in get_item_template.tags  # Global tag
@@ -2800,17 +2794,15 @@ class TestGlobalTagsParameter:
         )
 
         # Check that all three types of tags are present on the tool
-        tools = server._tool_manager.list_tools()
-        create_item_tool = next((t for t in tools if "create_item" in t.name), None)
-        assert create_item_tool is not None
+        tools = await server.get_tools()
+        create_item_tool = tools["create_item_items_post"]
         assert "items" in create_item_tool.tags  # Original OpenAPI tag
         assert "global" in create_item_tool.tags  # Global tag
         assert "route-specific" in create_item_tool.tags  # RouteMap mcp_tag
 
         # Check that resource only has OpenAPI and global tags (no route-specific since different RouteMap)
-        resources = list(server._resource_manager.get_resources().values())
-        get_items_resource = next((r for r in resources if "get_items" in r.name), None)
-        assert get_items_resource is not None
+        resources = await server.get_resources()
+        get_items_resource = resources["resource://get_items_items_get"]
         assert "items" in get_items_resource.tags  # Original OpenAPI tag
         assert "global" in get_items_resource.tags  # Global tag
         assert "route-specific" not in get_items_resource.tags  # Not from this RouteMap