Repository navigation
Add a tools_list_handler for context-dependent tool lists - #690
Merged
koic merged 1 commit intoNov 20, 2026
Merged
Conversation
Member
|
Thanks for the PR. Two follow-ups build on it:
|
koic
added a commit
to koic/ruby-sdk
that referenced
this pull request
Nov 20, 2026
## Motivation and Context With a `tools_list_handler` (modelcontextprotocol#690), `tools/list` and `tools/call` resolve a tool through the block, but the custom header check of the streamable HTTP transport still looked the tool up among the registered ones, before dispatch. On a 2026-07-28 `tools/call` that gave three results: - A registered tool the block leaves out answered `-32020` naming its header parameter where an unknown tool answers `Tool not found`, so the two could be told apart by a caller the tool was not listed for. - A tool the block returns under the name of a registered one was checked against the registered schema, so a call made the way `tools/list` described it could be refused. - A tool only the block returns was not checked at all. The check now runs in the dispatcher, on the tool the call resolved to: the transport hands `Server#handle` a `tool_call_check`, and `call_tool` calls it once the tool is found and before its arguments are examined. A second lookup from the transport would have invoked the block in another context (no envelope, so no client capabilities) and could disagree with the dispatch. A tool that is not found answers the same whatever the request carries, and a tool the block returns is checked on the schema it was listed with. The block is still invoked once per `tools/call`. The refusal keeps its shape, a JSON 400 with `-32020`. It now comes after the errors the dispatcher raises before it looks the tool up (an invalid envelope, an unknown tool), and like those it reaches instrumentation and the exception reporter. ## How Has This Been Tested? `test/mcp/server/transports/streamable_http_mcp_param_test.rb`; seven of the eight new tests fail on the previous library, and the eighth holds that `Server#handle` without a transport checks no headers. ## Breaking Changes None for a request that was served. A `tools/call` that has both a header mismatch and an invalid envelope is now answered for the envelope.
7 of 9 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation and Context
Motivation
We run an MCP server inside a Rails app, mounted through
StreamableHTTPTransport. Every signed-in developer and QA user can use it, but three reporting tools are for admins only.Today the only way to express that is a guard on each restricted tool:
The guard can refuse the call, but it cannot stop the tool from being advertised: every user's
tools/liststill shows the admin tools, so the model sees them and tries them. The alternative is building aServerper request.With this change the rule lives in one place and covers both the list and the call:
Context
This is the tools equivalent of
resources_list_handler(#509, #507). The Python SDK (on_list_tools) and the TypeScript SDK (setRequestHandler('tools/list', ...)) both let the tool list vary per request.tools_list_handler(&block)returns the tool collection for the request. As in #509, the framework paginates the array and stamps the cache hints, and a block that declaresserver_context:receives anMCP::ServerContext.One difference from #509:
tools/callresolves against the same collection. A tool the block leaves out is refused asTool not found, and a tool it returns is callable whether or not it is registered. Resources can pair the list handler withresources_read_handler; tools have no call-side hook since #270, so a list-only handler would leave hidden tools callable by name.Unlike the handler removed in #270, this one is documented and receives
server_context:.Limits, both documented:
tools/listpage and once pertools/call.How Has This Been Tested?
New tests in
test/mcp/server_test.rbcover the list path (replacement,server_context:, pagination and cache hints) and the call path (hidden tool refused, unregistered tool callable,server_context:).rake test,rake rubocop, andrake conformance:testpass.I also ran a local build in the Rails app described above, over
StreamableHTTPTransport, replacing the per-tool guard with the handler. For a non-admin token:tools_list_handler)tools/listtools/callon an admin tooladmin only,isError: true-32602 Tool not foundtools/callon a shared toolAn admin token lists and calls all 8 tools in both.
Breaking Changes
None. With no handler set,
tools/listandtools/callbehave as before.Types of changes
Checklist
🤖 assisted by claude