Skip to content

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

Open
mmcrockett wants to merge 1 commit into
modelcontextprotocol:mainfrom
mmcrockett:mcrockett/tools-list-handler
Open

mmcrockett wants to merge 1 commit into
modelcontextprotocol:mainfrom
mmcrockett:mcrockett/tools-list-handler

Conversation

@mmcrockett

@mmcrockett mmcrockett commented Nov 17, 2026 •

Copy link
Copy Markdown

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

This branch has not been deployed

No deployments
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.

1 participant