ceos/fastmcp
1
0
Fork 0
mirror of https://github.com/PrefectHQ/fastmcp.git synced 2026-08-22 13:34:17 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs: clarify server-level list notifications

Browse source
This commit is contained in:
nightcityblade 2026-08-09 11:12:34 +08:00
commit 41a511724d
3 changed files with 19 additions and 19 deletions
Download patch file Download diff file Expand all files Collapse all files

5
docs/servers/context.mdx
View file

@ -291,7 +291,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:
Per-session visibility changes made with `ctx.enable_components()`, `ctx.disable_components()`, or `ctx.reset_visibility()` automatically send list change notifications to the current client. Server-level component changes do not send notifications automatically because they are not associated with a client session. When making a server-level change inside an active request, use the context's notification method explicitly:
```python
import mcp.types
@ -305,7 +305,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.
Operations performed outside an active request, such as during server initialization, have no client session to notify.
### FastMCP Server
@ -440,4 +440,3 @@ def send_email(to: str, subject: str, body: str, ctx: Context) -> str:
<Warning>
The MCP request is part of the low-level MCP SDK and intended for advanced use cases. Most users will not need to use it directly.
</Warning>

18
docs/servers/tools.mdx
View file

@ -964,21 +964,19 @@ 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.
Per-session visibility changes made with `ctx.enable_components()` or `ctx.disable_components()` automatically send `notifications/tools/list_changed` to the current client. Server-level changes made with `mcp.add_tool()`, `mcp.enable()`, `mcp.disable()`, or `mcp.local_provider.remove_tool()` do not send notifications automatically because they are not associated with a client session.
```python
@mcp.tool
def example_tool() -> str:
return "Hello!"
import mcp.types
# These operations trigger notifications:
mcp.add_tool(example_tool) # Sends tools/list_changed notification
mcp.disable(keys={"tool:example_tool"}) # Sends tools/list_changed notification
mcp.enable(keys={"tool:example_tool"}) # Sends tools/list_changed notification
mcp.local_provider.remove_tool("example_tool") # Sends tools/list_changed notification
@mcp.tool
async def disable_example(ctx: Context) -> str:
mcp.disable(keys={"tool:example_tool"})
await ctx.send_notification(mcp.types.ToolListChangedNotification())
return "Disabled example_tool"
```
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.
Explicit notifications require an active MCP request context and notify that request's client. Operations performed during server initialization have no client session to notify.
Clients can handle these notifications using a [message handler](/clients/notifications) to automatically refresh their tool lists or update their interfaces.

15
docs/servers/visibility.mdx
View file

@ -409,17 +409,20 @@ Sessions start seeing only the activation tools. Calling `activate_finance` reve
## Client Notifications
When visibility state changes, FastMCP automatically notifies connected clients. Clients supporting the MCP notification protocol receive `list_changed` events and can refresh their component lists.
This happens automatically. You don't need to trigger notifications manually.
Per-session visibility changes made with `ctx.enable_components()`, `ctx.disable_components()`, or `ctx.reset_visibility()` automatically notify the current client. Server-level changes made with `mcp.enable()` or `mcp.disable()` do not automatically broadcast notifications because they are not associated with a client session.
```python
# This automatically notifies clients
mcp.disable(tags={"maintenance"})
import mcp.types
# Clients receive: tools/list_changed, resources/list_changed, etc.
@mcp.tool
async def start_maintenance(ctx: Context) -> str:
mcp.disable(tags={"maintenance"})
await ctx.send_notification(mcp.types.ToolListChangedNotification())
return "Maintenance tools disabled"
```
Explicit notifications require an active MCP request context and notify that request's client. Operations performed during server initialization have no client session to notify.
## Filtering Logic
Understanding the filtering logic helps when debugging visibility state issues.