Streamable HTTP: support per-request tools/list filtering hooks for large tool catalogs

[sivakothuri]

Summary

When servers expose a large number of tools, clients often need a filtered tools/list response based on request-scoped security and policy context (for example tenant, user permissions, and metadata headers).

In streamable HTTP mode, we need a supported way to customize tools/list results per request while still using the SDK-managed transport/session pipeline.

Current limitation

Built-in tools/list handling does not provide a clear per-request customization hook for filtering the returned tool set.

As a result, applications may need to bypass SDK handling and implement manual interception/response logic.

Why this matters

• Security: hide tools the caller is not authorized to see.
• Scalability/UX: reduce very large tool catalogs to relevant subsets.
• Multi-tenant correctness: tenant/user-specific visibility.
• Consistency: keep all methods on the same streamable transport path.

Requested capability

Please add one of the following supported extension points:

1. A pluggable handler override for built-in tools/list.
2. Middleware/interceptor API that can transform tools/list results per request.
3. A dedicated tools/list filter callback with access to request/exchange context and full tool list.

Expected outcome

Applications can apply per-request security/policy filtering for tools/list without bypassing streamable transport behavior.

Compatibility

No breaking change required. Default behavior should remain unchanged if no custom filter/handler is registered.

Related issues

• Add a way to customize default request handlers for Stateless server #525
• Support for accessing and customizing request handlers in McpServerSession #593
• Add ability to intercept tool call executions. #720
• Streamable Http clinet fails for fetching tool list #412

[Kehrlann]

Thanks for reporting. The main ask seems to be around filtering by tenant-and-or authentication, correct?

Additional questions:

1. Pagination exists in the spec. Is it required for your use-case?
2. Is the goal to alleviate server-side computations, to reduce the number of tools visible by the client, or both?

[arcadmlafon]

Hi, I have similar concern, I do not answer for @sivakothuri. But in my use case, my MCP Server may be acceded by different users and some of them may, or may not, have access to all the tools provided by the server depending on their role and other security reasons. We can manage this when the tool is called, or use one MCP server by user profile. But this is better to have one unique end-point and do not show the tools to the users which do not have the right to use them.

[Kehrlann]

Thanks.
We have a centralized discussion point in #578