From 8f58e8fc9d99b2ad34229a426c021d8aa8c6f681 Mon Sep 17 00:00:00 2001 From: Christian Tzolov Date: Tue, 3 Mar 2026 08:55:02 +0100 Subject: [PATCH] Document resource subscription support in server and client guides Signed-off-by: Christian Tzolov --- docs/client.md | 43 +++++++++++++++++++++++++++++++++++++++++++ docs/server.md | 42 +++++++++++++++++++++++++++++++++++++++--- 2 files changed, 82 insertions(+), 3 deletions(-) diff --git a/docs/client.md b/docs/client.md index 6a99928c5..1702936f0 100644 --- a/docs/client.md +++ b/docs/client.md @@ -408,6 +408,49 @@ Resources represent server-side data sources that clients can access using URI t .subscribe(); ``` +### Resource Subscriptions + +When the server advertises `resources.subscribe` support, clients can subscribe to individual resources and receive a callback whenever the server pushes a `notifications/resources/updated` notification for that URI. The SDK automatically re-reads the resource on notification and delivers the updated contents to the registered consumer. + +Register a consumer on the client builder, then subscribe/unsubscribe at any time: + +=== "Sync API" + + ```java + McpSyncClient client = McpClient.sync(transport) + .resourcesUpdateConsumer(contents -> { + // called with the updated resource contents after each notification + System.out.println("Resource updated: " + contents); + }) + .build(); + + client.initialize(); + + // Subscribe to a specific resource URI + client.subscribeResource(new McpSchema.SubscribeRequest("custom://resource")); + + // ... later, stop receiving updates + client.unsubscribeResource(new McpSchema.UnsubscribeRequest("custom://resource")); + ``` + +=== "Async API" + + ```java + McpAsyncClient client = McpClient.async(transport) + .resourcesUpdateConsumer(contents -> Mono.fromRunnable(() -> { + System.out.println("Resource updated: " + contents); + })) + .build(); + + client.initialize() + .then(client.subscribeResource(new McpSchema.SubscribeRequest("custom://resource"))) + .subscribe(); + + // ... later, stop receiving updates + client.unsubscribeResource(new McpSchema.UnsubscribeRequest("custom://resource")) + .subscribe(); + ``` + ### Prompt System The prompt system enables interaction with server-side prompt templates. These templates can be discovered and executed with custom parameters, allowing for dynamic text generation based on predefined patterns. diff --git a/docs/server.md b/docs/server.md index 0753726e2..f9f3aa683 100644 --- a/docs/server.md +++ b/docs/server.md @@ -33,7 +33,7 @@ The server supports both synchronous and asynchronous APIs, allowing for flexibl McpSyncServer syncServer = McpServer.sync(transportProvider) .serverInfo("my-server", "1.0.0") .capabilities(ServerCapabilities.builder() - .resources(false, true) // Enable resource support with list changes + .resources(false, true) // Resource support: subscribe=false, listChanged=true .tools(true) // Enable tool support with list changes .prompts(true) // Enable prompt support with list changes .completions() // Enable completions support @@ -57,7 +57,7 @@ The server supports both synchronous and asynchronous APIs, allowing for flexibl McpAsyncServer asyncServer = McpServer.async(transportProvider) .serverInfo("my-server", "1.0.0") .capabilities(ServerCapabilities.builder() - .resources(false, true) // Enable resource support with list changes + .resources(false, true) // Resource support: subscribe=false, listChanged=true .tools(true) // Enable tool support with list changes .prompts(true) // Enable prompt support with list changes .completions() // Enable completions support @@ -319,7 +319,7 @@ The server can be configured with various capabilities: ```java var capabilities = ServerCapabilities.builder() - .resources(false, true) // Resource support (subscribe, listChanged) + .resources(true, true) // Resource support: subscribe=true, listChanged=true .tools(true) // Tool support with list changes notifications .prompts(true) // Prompt support with list changes notifications .completions() // Enable completions support @@ -438,6 +438,42 @@ Resources provide context to AI models by exposing data such as: File contents, ); ``` +### Resource Subscriptions + +When the `subscribe` capability is enabled, clients can subscribe to specific resources and receive targeted `notifications/resources/updated` notifications when those resources change. Only sessions that have explicitly subscribed to a given URI receive the notification — not every connected client. + +Enable subscription support in the server capabilities: + +```java +McpSyncServer server = McpServer.sync(transportProvider) + .serverInfo("my-server", "1.0.0") + .capabilities(ServerCapabilities.builder() + .resources(true, false) // subscribe=true, listChanged=false + .build()) + .resources(myResourceSpec) + .build(); +``` + +When a subscribed resource changes, notify only the interested sessions: + +=== "Sync" + + ```java + server.notifyResourcesUpdated( + new McpSchema.ResourcesUpdatedNotification("custom://resource") + ); + ``` + +=== "Async" + + ```java + server.notifyResourcesUpdated( + new McpSchema.ResourcesUpdatedNotification("custom://resource") + ).subscribe(); + ``` + +If no sessions are subscribed to the given URI the call completes immediately without sending any messages. Subscription state is automatically cleaned up when a client session closes. + ### Resource Template Specification Resource templates allow servers to expose parameterized resources using URI templates: