modelcontextprotocol/java-sdk
Watch
1
0
Fork
You've already forked java-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Document resource subscription support in server and client guides (#843)

Browse source 
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
This commit is contained in:
Christian Tzolov 2026-03-03 10:45:04 +01:00 • committed by GitHub
commit 26304a7a39
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 82 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

43
docs/client.md
View file

@ -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.

42
docs/server.md
View file

@ -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: