resources/subscribe custom handler return value is discarded (always responds {})

[seunghan91]

Problem

Server#resources_subscribe_handler / resources_unsubscribe_handler accept a block, but the dispatch path invokes the handler and then unconditionally responds with an empty object — the handler's return value is discarded (lib/mcp/server.rb:622-625 at ref f0c9665):

when Methods::RESOURCES_SUBSCRIBE, Methods::RESOURCES_UNSUBSCRIBE
  validate_resource_subscription_params!(params)
  dispatch_optional_context_handler(@handlers[method], params, ...)
  {}

So a server cannot include anything in the subscribe response (e.g. a subscription identifier for later correlation, or advisory metadata). The handler is effectively side-effect-only, which is surprising given other handlers' return values shape the response.

If this is intentional (the spec's resources/subscribe result is an empty object), a doc note on resources_subscribe_handler saying the return value is ignored would prevent the surprise — we hit this while migrating from a hand-rolled server whose subscribe response carried a subscriptionId, and pinned the difference in our compatibility specs after discovering the discard empirically.

Context

Production MCP surface on Rails, recently cut over to this gem. Related prior contribution: #493.

[koic]

Thanks! This turned up a real gap, though not quite the one the report describes.

The doc note is already there: both handlers have said "The return value is ignored; the response is always an empty result {} per the MCP specification" since they were introduced, including in f0c9665.

That wording is wrong, though, and that's the actual defect. resources/subscribe returns an EmptyResult, and every Result may carry _meta. By hardcoding {}, the implementation dropped _meta as well, so a server could not return even the one field the specification allows. This change fixes that by passing through a handler-returned _meta:

server.resources_subscribe_handler do |params|
  {
    _meta: {
      "myapp.example/subscriptionId" => subscriptions.create(params[:uri].to_s),
    },
  }
end

A top-level subscriptionId, however, cannot be supported. The TypeScript SDK validates both results against EmptyResultSchema, which is ResultSchema.strict(), and rejects every member except _meta, so a TypeScript client would refuse it outright. The Python SDK also passes _meta through, making it the only behavior all three SDKs agree on. Any other field still has to be dropped.

For a migration like yours, nesting the identifier under a namespaced _meta key is the interoperable equivalent.

One scoping note: resources/subscribe and resources/unsubscribe were removed from the 2026-07-28 lifecycle, so this change affects only protocol versions through 2025-11-25.

I've opened #510 to address it.