How to handle OAuth 3LO for MCP toolsets when using Google ADK (401 on get_tools)

[busbaby]

I am trying to understand the correct pattern for using an MCP toolset with Google ADK when OAuth authorization has not yet been granted.

When I create an agent backed by an MCP server URL and attach the MCP toolset, the agent fails immediately when it attempts to call get_tools, returning a 401 Unauthorized error. This is expected, because at that point no OAuth access token exists yet. However, this makes it unclear how an agent is supposed to bootstrap the authorization flow.

Concretely, my scenario looks like this:

• I have an MCP server that requires OAuth 2.0 3LO (for example, the Atlassian MCP server).
• I create an agent with the MCP toolset pointing at that server.
• A human user asks the agent a question like: "Show me all my open Jira tickets."
• As soon as the agent tries to resolve available tools via get_tools, the MCP server returns 401 Unauthorized because no access token has been issued yet.

What I would like to achieve is:

• Allow the agent to exist and accept user input even before authorization.
• When a 401 occurs while fetching tools (or invoking a tool), trigger the OAuth 3LO flow.
• Guide the end user through the OAuth authorization process.
• Once authorization completes, retry get_tools and proceed with tool invocation.

My questions are:

1. What is the recommended pattern for creating an agent with an MCP toolset when authorization has not yet occurred?
2. Is the expectation that get_tools should be deferred or wrapped so that a 401 can initiate OAuth instead of being treated as a hard failure?
3. Are there any reference implementations, examples, or tutorials showing how to integrate OAuth 3LO flows with MCP toolsets using Google ADK?
4. Should this logic live inside the agent, the MCP client, or an external authorization coordinator?

Any guidance, documentation pointers, or example code would be greatly appreciated. I want to make sure I am following the intended design rather than working around the system incorrectly.

[surajksharma07]

@busbaby This is a known limitation tracked in #3331 - OAuth 3LO with MCP toolsets isn't fully supported because get_tools() happens during preprocessing where authentication flows can't be triggered.

The current workaround is to use the header_provider parameter in McpToolset to inject pre-obtained OAuth tokens (see contributing/samples/mcp_dynamic_header_agent for reference).

You'll need to handle the OAuth flow outside ADK and pass valid tokens through the header provider - it's not ideal since you'll need to manage token refresh yourself, but it unblocks the use case until the architectural fix in #3331 is merged.

Thanks!