Support dynamic per-request headers in MCPToolset for multi-tenant applications

[gishamer]

Problem Statement:

1. Multi-tenant applications need to pass different headers (e.g., company-id, tenant identifiers) per request to MCP servers. Current ADK implementation only supports static headers set during initialization, which doesn't work for our use case.
2. In addition: Multi-tenant applications need to pass different auth headers per request to MCP servers.

Key Difference from Existing Issues:

Unlike #805, #2221, #2482, and Discussion #459, we need custom headers as well as auth headers during the initial get_tools() / discovery phase, not just tool execution. This is critical for MCP servers that enforce tenant isolation and auth at the discovery level.

Current Blockers:

1. MCPToolset.get_tools() doesn't accept headers from runtime context
2. MCPTool._get_headers() is initialized with static auth but doesn't use it (TODO comment in code)
3. No mechanism to pass tool_context.state or readonly_context.state to the MCP session

Our Solution:

We've implemented custom subclasses of MCPTool and MCPToolset that:

• Extract headers from context.state.get("user:custom_headers", {})
• Override _get_headers() to merge custom headers with auth headers
• Pass headers to create_session() in get_tools() for discovery phase
• Support httpx.Auth for dynamic bearer token authentication
• Maintain full backward compatibility

This approach works but requires overwriting internal code of ADK, which is brittle.

A more sustainable solution should allow passing custom headers directly to the runner on a per-call basis, and provide a similar mechanism for the auth header.

Question:

Is native support for per-request custom headers on the roadmap? If not, would you accept a PR that adds this functionality? We're happy to contribute and work with maintainers on the design approach.

Related Issues: #805 (auth TODO), #2221 (token refresh), #2482 (user tokens), Discussion #459 (custom headers)

[DinoChiesa]

I'm glad there is now a header_provider, but . . . what about supporting auth_scheme and auth_credential in McpToolset?
I believe those are supported on OpenAPIToolset but not on McpToolset. They should be.