What it does
The `resources/unsubscribe` method is a client-to-server JSON-RPC call that cancels an active resource subscription established by a prior `resources/subscribe` call. The client sends a request containing the `uri` field identifying the resource to unsubscribe from. The server locates the matching subscription for that client session, tears it down, and responds with an empty result object (`{}`). After the server processes the request, it must not emit any further `notifications/resources/updated` events for that URI to that client. Both `resources/subscribe` and `resources/unsubscribe` are gated behind the `resources` capability with the `subscribe` sub-capability. The server must advertise `{"resources": {"subscribe": true}}` during the `initialize` handshake; if it does not, clients must not call this method. Calling `resources/unsubscribe` without the capability being declared will typically result in a `-32601 Method not found` error. Timing is important: a `notifications/resources/updated` notification may arrive in-flight after the client sends `resources/unsubscribe` but before the server has processed it. Clients must be prepared to receive and silently discard one or more stale notifications following an unsubscribe. To avoid resource leaks, always call `resources/unsubscribe` when a component unmounts or a session ends — servers are not required to auto-expire subscriptions on their own.
When to use
When the host closes the watcher.
When NOT to use
If you haven't subscribed in the first place.
Notes
Capability gate is mandatory
This method is only valid when the server has advertised `resources.subscribe: true` in its `initialize` response capabilities. If the client calls `resources/unsubscribe` against a server that did not declare this capability, expect a `-32601 Method not found` JSON-RPC error. Always check capabilities before calling subscribe or unsubscribe.
Race condition: in-flight notifications
Because JSON-RPC over stdio or SSE is asynchronous, the server may have already dispatched a `notifications/resources/updated` message before it processes your unsubscribe request. Clients should treat any notifications received after sending `resources/unsubscribe` as benign and discard them without side effects rather than treating them as errors.
Error codes to handle
Beyond `-32601` for missing capability, expect `-32602 Invalid params` if the `uri` field is absent or malformed, and a server-defined error (typically in the `-32000` to `-32099` range) if the URI was never subscribed in the first session. Treat an unsubscribe for an unknown URI as idempotent in your client logic rather than surfacing it as a fatal error.
Always unsubscribe on session teardown
Servers are not required to garbage-collect subscriptions when a transport connection drops unexpectedly. In long-running server processes, orphaned subscriptions accumulate and can cause memory leaks or spurious change-detection overhead. Explicitly call `resources/unsubscribe` for every active URI before closing a session or destroying a component that owns the subscription.
No confirmation payload — treat empty result as success
The response is always `{}` on success. SDKs that deserialize results into typed objects will surface this as an empty or void return; do not attempt to inspect the result for confirmation state. The absence of an error response is the definitive signal that the subscription has been removed.
Request parameters
| Name | Type | Purpose |
|---|---|---|
| uri | string | URI to stop watching. |
Examples
Unsubscribe
{ "method": "resources/unsubscribe", "params": { "uri": "file:///log.txt" } }