Skip to content

Add a tools_list_handler for context-dependent tool lists - #690

Merged
koic merged 1 commit into
modelcontextprotocol:mainfrom
mmcrockett:mcrockett/tools-list-handler
Nov 20, 2026
Merged

koic merged 1 commit into
modelcontextprotocol:mainfrom
mmcrockett:mcrockett/tools-list-handler

Conversation

@mmcrockett

@mmcrockett mmcrockett commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

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:

module AdminOnlyTool
  def call(**)
    return MCP::Tool::Response.new([{ type: "text", text: "admin only" }], error: true) unless Current.user&.admin?

    super
  end
end

class WeeklyStatsTool < MCP::Tool
  singleton_class.prepend(AdminOnlyTool)
  # ...
end

The guard can refuse the call, but it cannot stop the tool from being advertised: every user's tools/list still shows the admin tools, so the model sees them and tries them. The alternative is building a Server per request.

With this change the rule lives in one place and covers both the list and the call:

server.tools_list_handler do |_params|
  Current.user&.admin? ? admin_tools + shared_tools : shared_tools
end

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 declares server_context: receives an MCP::ServerContext.

One difference from #509: tools/call resolves against the same collection. A tool the block leaves out is refused as Tool not found, and a tool it returns is callable whether or not it is registered. Resources can pair the list handler with resources_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:

  • The block runs once per tools/list page and once per tools/call.
  • The SEP-2243 custom header check reads the registered tools in the transport, so it is skipped for a tool that only the handler returns.

How Has This Been Tested?

New tests in test/mcp/server_test.rb cover 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, and rake conformance:test pass.

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:

Request Before (per-tool guard) After (tools_list_handler)
tools/list all 8 tools, admin tools included 5 shared tools
tools/call on an admin tool tool result admin only, isError: true -32602 Tool not found
tools/call on a shared tool OK OK

An admin token lists and calls all 8 tools in both.

Breaking Changes

None. With no handler set, tools/list and tools/call behave as before.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Documentation
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling
  • I have added or updated documentation as needed

🤖 assisted by claude

@koic

koic commented Nov 20, 2026

Copy link
Copy Markdown
Member

Thanks for the PR. Two follow-ups build on it:

  • The custom header check looks the tool up among the registered ones, so a registered tool the block leaves out can be told apart from an unknown one, and a tool the block returns is checked against another schema or not at all. A follow-up will run the check on the tool the call resolved to.
  • Pass the access token to a handler the legacy input_required shim re-runs #696: the legacy input_required shim re-ran a handler without the access token of the request, so a block that decides by server_context.auth_info no longer found the tool on the re-run. That predates this PR.

@koic
koic merged commit c2ce3c1 into modelcontextprotocol:main Nov 20, 2026
13 checks passed
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants