What are resource subscriptions, and how do updates get pushed to clients?
Quick Answer
A client can call resources/subscribe with a specific URI to ask the server to notify it whenever that resource's content changes — useful for something like a log file being actively written to, or a config value another process might modify. When the underlying data changes, the server sends notifications/resources/updated with that URI, and the client typically responds by re-issuing resources/read to fetch the new content (the notification itself doesn't carry the new content, just the fact that it changed). This capability is optional — a server only supports it if it declared resources.subscribe: true during initialization — and a client can later call resources/unsubscribe to stop receiving updates for a URI it no longer cares about.
Detailed Answer
Without subscriptions, the only way to detect a resource has changed is to keep re-reading it on a timer. That wastes requests and still misses changes between polls.
The subscription flow
// Client subscribes to one resource
{"method": "resources/subscribe", "params": {"uri": "file:///var/log/app.log"}}
// ... time passes, the file changes on disk ...
// Server pushes a notification (no content included, just the fact of a change)
{"method": "notifications/resources/updated", "params": {"uri": "file:///var/log/app.log"}}
// Client reacts by re-reading
{"method": "resources/read", "params": {"uri": "file:///var/log/app.log"}}
Why the notification carries no content
Sending the full new content inline would force the server to guess whether the client actually still wants it. It would also bloat notifications for resources that update frequently but are only occasionally re-read. Instead, the notification is a cheap "this changed" signal. The client decides whether, and when, it's worth the cost of an actual resources/read.
Preconditions and cleanup
- Requires the server to have declared
"resources": {"subscribe": true}in its capabilities. A server without that capability doesn't supportresources/subscribeat all. - A client should call
resources/unsubscribeonce it no longer needs updates for a URI — say, the corresponding UI panel closed. That lets the server stop tracking and pushing updates for it. Leaving subscriptions open indefinitely wastes server-side bookkeeping, and can eventually leak memory in a long-running server process.
A realistic use case
A code-editing host might subscribe to the currently open file's resource URI. If an external process — a formatter, a build step, another editor instance — modifies it on disk, the host's in-memory view is invalidated and refreshed automatically. The user never ends up working against stale content without realizing it.