Add example on external MCPTool usage and proper auth management

[blindosbarra]

When an agent need to initialize a connection to a custom MCP tool, it is required to manipulate the MCP tool calls on agent side for adding/checking headers (i.e. auth info could come from the application wrapping the agent). I think it would be nice to have a working ADK sample with the best practices for working with external MCP server (i.e. implemented as streamable http protocol via fast MCP) with proper handling of auth tokens highlithing the proper callbacks functions and context variables to use. This example should clearly illustrate the use of the aforementioned ADK callbacks/extension points and context variables.
The current documentation does not fully clarify the lifecycle of a MCPTool in terms of initialization, agent internal MCPTool instance retrivial and how to properly use callback to customize the interactions between agent and tool.

[ypenn21]

I was looking for something similar in order to add auth headers on the mcp client to server api call:

https://google.github.io/adk-docs/tools/mcp-tools/#step-4-run-adk-web-and-interact

something like:

MCP_URL = os.getenv("MCP_TOOLBOX_URL", "http://127.0.0.1:8000")
toolbox = ToolboxSyncClient(MCP_URL)
toolbox.addAuthHeaders(""Authorization", "bearToken")

[blindosbarra]

I think an example or a suggested direction on how to manage authentication specifically for MCP is going to be required. If you consider also the case of ADK deployed to Agent Engine that need to invoke MCP hosted on cloud run you have to manage the autorization of the user calling the MCP server and the authorization of the Agent Engine instance to call the cloud run instance using bearer tokens.

[lavinigam-gcp]

Hi @blindosbarra, thank you so much for this incredibly detailed and thoughtful issue report! We really appreciate you taking the time to outline the gaps in our documentation.

Just to make sure we're on the same page, it sounds like you're looking for a comprehensive guide and a practical code sample for using the ADK with external MCP servers. The key areas you need covered are best practices for authentication management (like handling headers and tokens), a clearer explanation of the MCPTool lifecycle and its context, and specific deployment examples for platforms like Agent Engine and Cloud Run.

To address this, I have raised the PR #523, please review and provide your feedback.

Thanks again for helping us improve!