subscriptions/listen replaces resources/subscribe and the old GET stream, and it is modern-era only: a legacy client gets -32601.
Opening a subscription
params.notifications is required and must be an object. Send Mcp-Method: subscriptions/listen like any other request.
The request id is the subscription id, so it must not be null. Every notification on this stream carries it in _meta.io.modelcontextprotocol/subscriptionId, which is how a client with several subscriptions open tells them apart.
The acknowledgment
Before anything else, the server answers with what it will actually send:What TablePro honors
Every URI in
resourceSubscriptions is checked twice. It has to parse as a connection schema URI, and its connection has to be inside the token’s allowlist. Anything else is dropped silently, so the acknowledgment is the only place you find out. A token without resources:read gets an empty filter back, whatever it asked for.
The URI you get back is canonical, so one that differs only in case or percent-encoding comes back normalized.
Reading the stream
The response switches totext/event-stream at the acknowledgment and stays open. Frames carry no event name, so each one is data: plus a JSON line, terminated by a blank line. A line starting with : is the keepalive TablePro sends every 15 seconds to stop an intermediary timing the connection out; skip it.
Tell the two kinds of frame apart by the envelope. A frame with an id equal to your request id is the final JSON-RPC response and the stream is over. A frame with a method and no id is a notification.
The notifications
notifications/resources/list_changed
Sent when the set of connections visible to this token changes: one connects, one disconnects, one is blocked for external clients, or its AI policy changes to Never.
TablePro compares the visible set against the last one it sent you, so a change that does not move your set produces no notification. A connection you cannot see connecting is not your event.
notifications/resources/updated
Sent when a subscribed connection’s schema changes, carrying the URI:
tablepro://connections/{id}/schema when it arrives.
Closing
The subscription ends when the client closes the connection, cancels the request withnotifications/cancelled, or the server stops. The final JSON-RPC response is an empty result carrying the subscription id in _meta.
There is no deadline on subscriptions/listen. It is the one method exempt from the 330-second handler timeout and from the per-caller concurrency limit. The server checks every open subscription for a dropped connection every 15 seconds and closes the ones that went away, so a client that dies without closing does not leak.