From 1504e8aae20c325921b922f33911238e87ead837 Mon Sep 17 00:00:00 2001
From: Jeremiah Lowin <153965+jlowin@users.noreply.github.com>
Date: Tue, 10 Jun 2025 20:58:07 -0400
Subject: [PATCH 1/4] Pass through tags from server
---
src/fastmcp/server/server.py | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/src/fastmcp/server/server.py b/src/fastmcp/server/server.py
index 7e245b4ec..5088c2c17 100644
--- a/src/fastmcp/server/server.py
+++ b/src/fastmcp/server/server.py
@@ -1561,6 +1561,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 +1576,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 +1590,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 +1618,7 @@ class FastMCP(Generic[LifespanResultT]):
route_map_fn=route_map_fn,
mcp_component_fn=mcp_component_fn,
mcp_names=mcp_names,
+ tags=tags,
**settings,
)
From b88c7c5a0cec16ae7f2f5fc6ac4a2124b98dc999 Mon Sep 17 00:00:00 2001
From: Jeremiah Lowin <153965+jlowin@users.noreply.github.com>
Date: Tue, 10 Jun 2025 21:01:12 -0400
Subject: [PATCH 2/4] Remove FastMCP server tags
---
src/fastmcp/server/server.py | 3 ---
tests/deprecated/test_settings.py | 2 --
2 files changed, 5 deletions(-)
diff --git a/src/fastmcp/server/server.py b/src/fastmcp/server/server.py
index 5088c2c17..7522942a7 100644
--- a/src/fastmcp/server/server.py
+++ b/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)
)
diff --git a/tests/deprecated/test_settings.py b/tests/deprecated/test_settings.py
index c58ce183e..490b88c1a 100644
--- a/tests/deprecated/test_settings.py
+++ b/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."""
From 20f4117b47085e875f073d15796be3e6bfdc7e81 Mon Sep 17 00:00:00 2001
From: Jeremiah Lowin <153965+jlowin@users.noreply.github.com>
Date: Tue, 10 Jun 2025 21:06:20 -0400
Subject: [PATCH 3/4] Update tests
---
tests/server/openapi/test_openapi.py | 40 +++++++++++-----------------
1 file changed, 16 insertions(+), 24 deletions(-)
diff --git a/tests/server/openapi/test_openapi.py b/tests/server/openapi/test_openapi.py
index d0c66a593..366416975 100644
--- a/tests/server/openapi/test_openapi.py
+++ b/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
From 55c65c932bb63726308c9bd3e6568d9745e5c8a0 Mon Sep 17 00:00:00 2001
From: Jeremiah Lowin <153965+jlowin@users.noreply.github.com>
Date: Tue, 10 Jun 2025 21:13:27 -0400
Subject: [PATCH 4/4] Add docs
---
docs/servers/openapi.mdx | 80 ++++++++++++++++++++++++++++++++++++++--
1 file changed, 77 insertions(+), 3 deletions(-)
diff --git a/docs/servers/openapi.mdx b/docs/servers/openapi.mdx
index ff7d6460c..1359ff51b 100644
--- a/docs/servers/openapi.mdx
+++ b/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
+
+
+
+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.
+
+
+```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"}
+)
+```
+
-### Component Names
+### Names
@@ -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"}),
],