π The fast, Pythonic way to build MCP servers and clients.
docs: server-level component changes don't notify clients (#6423)
nate nowack2e2d5772bb81
diff --git a/docs/servers/context.mdx b/docs/servers/context.mdxindex ce53dfb37..593c749e8 100644--- a/docs/servers/context.mdx+++ b/docs/servers/context.mdx@@ -284,7 +284,7 @@ Tools can customize which components are visible to their current session using<VersionBadge version="3.0.0" />-FastMCP automatically sends list change notifications when components (such as tools, resources, or prompts) are added, removed, enabled, or disabled. In rare cases where you need to manually trigger these notifications, you can use the context's notification methods:+Session visibility changes made with `ctx.enable_components()`, `ctx.disable_components()`, and `ctx.reset_visibility()` notify the calling session automatically. Server-level and provider-level changes (adding, removing, enabling, or disabling components) send no notifications. To tell the calling session about such a change, send the notifications yourself:```pythonfrom mcp.types import (@@ -302,7 +302,7 @@ async def custom_tool_management(ctx: Context) -> str:return "Notifications sent"```-These methods are primarily used internally by FastMCP's automatic notification system and most users will not need to invoke them directly.+These notifications reach only the session that made the request. See [Client Notifications](/servers/visibility#client-notifications).### FastMCP Serverdiff --git a/docs/servers/prompts.mdx b/docs/servers/prompts.mdxindex 87b447cef..1cbd2ca41 100644--- a/docs/servers/prompts.mdx+++ b/docs/servers/prompts.mdx@@ -450,22 +450,28 @@ For full documentation on the Context object and all its capabilities, see the [<VersionBadge version="2.9.1" />-FastMCP automatically sends `notifications/prompts/list_changed` notifications to connected clients when prompts are added, enabled, or disabled. This allows clients to stay up-to-date with the current prompt set without manually polling for changes.+Adding, removing, enabling, or disabling prompts at the server or provider level does not notify connected clients. Clients see the change the next time they list prompts.++When a request changes the prompt set, the tool handling it can tell the calling session by sending `notifications/prompts/list_changed` itself. The notification reaches only that session.```python-from fastmcp.prompts import prompt+from fastmcp import FastMCP+from fastmcp.server.context import Context+from mcp_types import PromptListChangedNotification++mcp = FastMCP("Server")-@prompt-def example_prompt() -> str:- return "Hello!"+async def unlock_extras(ctx: Context) -> str:+ def summarize(text: str) -> str:+ return f"Summarize: {text}"-# These operations trigger notifications:-mcp.add_prompt(example_prompt) # Sends prompts/list_changed notification-mcp.disable(names={"example_prompt"}) # Sends prompts/list_changed notification-mcp.enable(names={"example_prompt"}) # Sends prompts/list_changed notification+ mcp.prompt(summarize)+ await ctx.send_notification(PromptListChangedNotification())+ return "Extras unlocked"```-Notifications are only sent when these operations occur within an active MCP request context (e.g., when called from within a tool or other MCP operation). Operations performed during server initialization do not trigger notifications.+Session visibility changes made with `ctx.enable_components()` and `ctx.disable_components()` send these notifications automatically. See [Client Notifications](/servers/visibility#client-notifications).Clients can handle these notifications using a [message handler](/clients/notifications) to automatically refresh their prompt lists or update their interfaces.diff --git a/docs/servers/resources.mdx b/docs/servers/resources.mdxindex 538b0ff71..f46a0eb4c 100644--- a/docs/servers/resources.mdx+++ b/docs/servers/resources.mdx@@ -387,22 +387,28 @@ Use these when the content is static or sourced directly from a file/URL, bypass<VersionBadge version="2.9.1" />-FastMCP automatically sends `notifications/resources/list_changed` notifications to connected clients when resources or templates are added, enabled, or disabled. This allows clients to stay up-to-date with the current resource set without manually polling for changes.+Adding, removing, enabling, or disabling resources at the server or provider level does not notify connected clients. Clients see the change the next time they list resources.++When a request changes the resource set, the tool handling it can tell the calling session by sending `notifications/resources/list_changed` itself. The notification reaches only that session.```python-from fastmcp.resources import resource+from fastmcp import FastMCP+from fastmcp.server.context import Context+from mcp_types import ResourceListChangedNotification++mcp = FastMCP("Server")-@resource("data://example")-def example_resource() -> str:- return "Hello!"+async def unlock_extras(ctx: Context) -> str:+ def stats() -> str:+ return "42"-# These operations trigger notifications:-mcp.add_resource(example_resource) # Sends resources/list_changed notification-mcp.disable(names={"data://example"}) # Sends resources/list_changed notification-mcp.enable(names={"data://example"}) # Sends resources/list_changed notification+ mcp.resource("data://stats")(stats)+ await ctx.send_notification(ResourceListChangedNotification())+ return "Extras unlocked"```-Notifications are only sent when these operations occur within an active MCP request context (e.g., when called from within a tool or other MCP operation). Operations performed during server initialization do not trigger notifications.+Session visibility changes made with `ctx.enable_components()` and `ctx.disable_components()` send these notifications automatically. See [Client Notifications](/servers/visibility#client-notifications).Clients can handle these notifications using a [message handler](/clients/notifications) to automatically refresh their resource lists or update their interfaces.diff --git a/docs/servers/tools.mdx b/docs/servers/tools.mdxindex 809e57cbc..7d79f792e 100644--- a/docs/servers/tools.mdx+++ b/docs/servers/tools.mdx@@ -1059,20 +1059,28 @@ Client-specific behavior:<VersionBadge version="2.9.1" />-FastMCP automatically sends `notifications/tools/list_changed` notifications to connected clients when tools are added, removed, enabled, or disabled. This allows clients to stay up-to-date with the current tool set without manually polling for changes.+Adding, removing, enabling, or disabling tools at the server or provider level does not notify connected clients. Clients see the change the next time they list tools.++When a request changes the tool set, the tool handling it can tell the calling session by sending `notifications/tools/list_changed` itself. The notification reaches only that session.```python-def example_tool() -> str:- return "Hello!"--# These operations trigger notifications:-mcp.add_tool(example_tool) # Sends tools/list_changed notification-mcp.disable(names={"example_tool"}) # Sends tools/list_changed notification-mcp.enable(names={"example_tool"}) # Sends tools/list_changed notification-mcp.local_provider.remove_tool("example_tool") # Sends tools/list_changed notification+from fastmcp import FastMCP+from fastmcp.server.context import Context+from mcp_types import ToolListChangedNotification++mcp = FastMCP("Server")++async def unlock_extras(ctx: Context) -> str:+ def report() -> str:+ return "Monthly report"++ mcp.tool(report)+ await ctx.send_notification(ToolListChangedNotification())+ return "Extras unlocked"```-Notifications are only sent when these operations occur within an active MCP request context (e.g., when called from within a tool or other MCP operation). Operations performed during server initialization do not trigger notifications.+Session visibility changes made with `ctx.enable_components()` and `ctx.disable_components()` send these notifications automatically. See [Client Notifications](/servers/visibility#client-notifications).Clients can handle these notifications using a [message handler](/clients/notifications) to automatically refresh their tool lists or update their interfaces.diff --git a/tests/server/test_session_visibility.py b/tests/server/test_session_visibility.pyindex 2e0d5ddc7..dbee2ccd2 100644--- a/tests/server/test_session_visibility.py+++ b/tests/server/test_session_visibility.py@@ -517,6 +517,40 @@ class TestSessionVisibilityNotifications:== 0)+ async def test_server_level_disable_sends_no_notification(self):+ """Server-level disable changes the list silently; a tool can notify itself."""+ from fastmcp import Client++ mcp = FastMCP("test")++ @mcp.tool+ def target() -> str:+ return "target"++ @mcp.tool+ def hide_silently() -> str:+ mcp.disable(names={"target"})+ return "hidden"++ @mcp.tool+ async def show_and_notify(ctx: Context) -> str:+ mcp.enable(names={"target"})+ await ctx.send_notification(mcp_types.ToolListChangedNotification())+ return "shown"++ handler = RecordingMessageHandler()+ async with Client(mcp, message_handler=handler) as client:+ handler.reset()+ await client.call_tool("hide_silently", {})+ assert handler.get_notifications("notifications/tools/list_changed") == []+ assert "target" not in {t.name for t in await client.list_tools()}++ await client.call_tool("show_and_notify", {})+ assert (+ len(handler.get_notifications("notifications/tools/list_changed")) == 1+ )+ assert "target" in {t.name for t in await client.list_tools()}+class TestConcurrentSessionIsolation:"""Test that concurrent sessions don't leak visibility transforms."""