Skip to content

Check custom headers against the tool the tools_list_handler returns - #700

Open
koic wants to merge 1 commit into
modelcontextprotocol:mainfrom
koic:check_custom_headers_against_the_tool_the_tools_list_handler_returns
Open

koic wants to merge 1 commit into
modelcontextprotocol:mainfrom
koic:check_custom_headers_against_the_tool_the_tools_list_handler_returns

Conversation

@koic

@koic koic commented Nov 20, 2026

Copy link
Copy Markdown
Member

Motivation and Context

With a tools_list_handler (#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.

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

## 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.

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