Create advanced-mcp-tools page to split content - #2122
Open
zyantw wants to merge 3 commits into
Open
Conversation
✅ Deploy Preview for adk-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
zyantw
marked this pull request as draft
August 11, 2026 21:38
zyantw
changed the title
zyantw
changed the title
This PR introduces the new **Advanced MCP Configuration Guide** (`docs/tools-custom/advanced-mcp-tools.md`), extracting advanced integration patterns, low-level lifecycle hooks, and production deployment architectures into a dedicated reference. This complements the core MCP guide ([#2081](#2081)) by keeping the quickstart focused while providing enterprise patterns for advanced developers. --- ## Key Improvements & Information Architecture ### 1. Developer Decision Matrix - Added a lookup table at the top that maps common engineering requirements (multi-tenant auth, destructive tool safety, progress bars, containerization) to specific ADK APIs. ### 2. Prioritization by Real-World Frequency The guide is structured progressively from high-demand configurations to specialized edge cases: 1. **Dynamic Authentication & Per-User Headers (`header_provider`)** — Multi-tenant token injection using `ReadonlyContext`. 2. **Human-in-the-Loop & Tool Confirmations (`require_confirmation`)** — Guardrails for destructive database/file operations. 3. **Real-Time Progress Tracking (`progress_callback`)** — Both global functions and context-aware session factories (`ProgressCallbackFactory`). 4. **Standalone Runner Execution (Outside `adk web`)** — Embedding agents into FastAPI/CLI backends with graceful `await toolset.close()` teardown. 5. **Enterprise Cloud Deployment Architectures** — Cloud Run stateless services (`StreamableHTTPConnectionParams`), GKE Pod Sidecars, and Vertex AI Agent Runtime. 6. **Tool Namespacing & Disambiguation (`tool_name_prefix`)** — Resolving naming collisions when combining multiple MCP servers. 7. **Bi-directional Protocol Hooks** — Handlers for server-initiated sampling (`sampling_callback`) and authentication challenges (`elicitation_callback`). 8. **Diagnostic Logging (`errlog`)** — Subprocess STDERR redirection for troubleshooting. --- ## Technical Verification Report against `google/adk-python` All code examples, class imports, and parameter signatures in this PR were verified against the latest `google/adk-python` codebase: | Feature / Snippet | Verification in `google/adk-python` | Verification Status | | :--- | :--- | :--- | | **`header_provider`** | [`mcp_toolset.py:L113-L119`](file:///usr/local/google/home/zyanya/.gemini/jetski/scratch/adk_review/adk-python/src/google/adk/tools/mcp_tool/mcp_toolset.py#L113-L119) & [`L346-L352`](file:///usr/local/google/home/zyanya/.gemini/jetski/scratch/adk_review/adk-python/src/google/adk/tools/mcp_tool/mcp_toolset.py#L346-L352) | Verified: Accepts `Callable[[ReadonlyContext], dict[str, str] \| Awaitable[dict[str, str]]]` and injects headers dynamically on each session call. | | **`require_confirmation`** | [`mcp_toolset.py:L112`](file:///usr/local/google/home/zyanya/.gemini/jetski/scratch/adk_review/adk-python/src/google/adk/tools/mcp_tool/mcp_toolset.py#L112) & [`function_tool.py:L278-L340`](file:///usr/local/google/home/zyanya/.gemini/jetski/scratch/adk_review/adk-python/src/google/adk/tools/function_tool.py#L278-L340) | Verified: Supports both boolean flags and callable predicates receiving tool arguments. | | **`progress_callback` & Factory** | [`mcp_toolset.py:L120`](file:///usr/local/google/home/zyanya/.gemini/jetski/scratch/adk_review/adk-python/src/google/adk/tools/mcp_tool/mcp_toolset.py#L120) & [`mcp_tool.py:L496-L515`](file:///usr/local/google/home/zyanya/.gemini/jetski/scratch/adk_review/adk-python/src/google/adk/tools/mcp_tool/mcp_tool.py#L496-L515) | Verified: Supports standard `ProgressFnT` as well as `ProgressCallbackFactory` for modifying `ToolContext.state`. | | **`Runner` Lifecycle Teardown** | [`mcp_toolset.py:L487-L499`](file:///usr/local/google/home/zyanya/.gemini/jetski/scratch/adk_review/adk-python/src/google/adk/tools/mcp_tool/mcp_toolset.py#L487-L499) | Verified: `await toolset.close()` safely terminates the underlying `MCPSessionManager` and closes open subprocesses/streams. | | **`StreamableHTTPConnectionParams`** | [`mcp_session_manager.py:L312-L339`](file:///usr/local/google/home/zyanya/.gemini/jetski/scratch/adk_review/adk-python/src/google/adk/tools/mcp_tool/mcp_session_manager.py#L312-L339) | Verified: Matches Pydantic model definition with `url`, `headers`, `timeout`, and `sse_read_timeout`. | | **`tool_name_prefix`** | [`mcp_toolset.py:L108`](file:///usr/local/google/home/zyanya/.gemini/jetski/scratch/adk_review/adk-python/src/google/adk/tools/mcp_tool/mcp_toolset.py#L108) | Verified: Passed through to `BaseToolset` to prefix all tool declarations and prevent namespace collisions. | | **`sampling_callback` & `elicitation_callback`** | [`mcp_toolset.py:L122-L125`](file:///usr/local/google/home/zyanya/.gemini/jetski/scratch/adk_review/adk-python/src/google/adk/tools/mcp_tool/mcp_toolset.py#L122-L125) | Verified: Forwarded to `MCPSessionManager` for bi-directional protocol handling. | | **CLI Deployment Commands** | [`cli_tools_click.py:L2229-L2770`](file:///usr/local/google/home/zyanya/.gemini/jetski/scratch/adk_review/adk-python/src/google/adk/cli/cli_tools_click.py#L2229-L2770) | Verified: Commands use active flags and omit deprecated arguments (such as `--staging_bucket`). | --- ## Verification Checklist - [x] Code snippets follow canonical `from google.adk.agents import LlmAgent` imports. - [x] Code blocks include multi-language tabs (Python, TypeScript, Java) where applicable. - [x] All parameters match current Pydantic models in `google-adk` v2.x. - [x] Tested markdown rendering, tables, and code block formatting.
zyantw
marked this pull request as ready for review
August 12, 2026 03:19
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Rendered page: https://deploy-preview-2122--adk-docs-preview.netlify.app/tools-custom/advanced-mcp-tools/
PR of revamped Mcp Tools page: #2081
Rationale for Splitting Advanced Configuration into a Dedicated Page
In the previous production documentation, over 50% of the page was consumed by advanced, niche configurations:
AsyncExitStack)ProgressCallbackFactory)adk webWhy Moving These to a Separate Page (
/advanced-mcp-tools) is Best Practice:mcp-tools.md): Focuses on usage patterns (McpToolset,to_mcp_server, Resources, and UI Rendering).advanced-mcp-tools.md): Focuses on framework internals (Custom async session managers, bi-directional sampling, progress factory callbacks, and manual runner exit stacks).Key Improvements & Information Architecture
1. Developer Decision Matrix
2. Case by case scenarios and troubleshooting.
Jetski report
Technical Verification Report against
google/adk-pythonAll code examples, class imports, and parameter signatures in this PR were verified against the latest
google/adk-pythoncodebase:google/adk-pythonheader_providermcp_toolset.py:L113-L119&L346-L352Callable[[ReadonlyContext], dict[str, str] | Awaitable[dict[str, str]]]and injects headers dynamically on each session call.require_confirmationmcp_toolset.py:L112&function_tool.py:L278-L340progress_callback& Factorymcp_toolset.py:L120&mcp_tool.py:L496-L515ProgressFnTas well asProgressCallbackFactoryfor modifyingToolContext.state.RunnerLifecycle Teardownmcp_toolset.py:L487-L499await toolset.close()safely terminates the underlyingMCPSessionManagerand closes open subprocesses/streams.StreamableHTTPConnectionParamsmcp_session_manager.py:L312-L339url,headers,timeout, andsse_read_timeout.tool_name_prefixmcp_toolset.py:L108BaseToolsetto prefix all tool declarations and prevent namespace collisions.sampling_callback&elicitation_callbackmcp_toolset.py:L122-L125MCPSessionManagerfor bi-directional protocol handling.cli_tools_click.py:L2229-L2770--staging_bucket).Verification Checklist
from google.adk.agents import LlmAgentimports.google-adkv2.x.