Revamping of MCP Tools page - #2081
Open
zyantw wants to merge 10 commits into
Open
Conversation
This PR consolidates several pending documentation updates into a unified, restructured `mcp-tools.md` guide. It improves the Information Architecture (IA) by grouping deployment, authentication, and transport types. Grounds abstract concepts with concrete, production-ready code examples. - Key Improvements * **Feature Completeness:** Integrated documentation for MCP Resources, Experimental UI Widgets, and Connection Timeouts. * **Technical Accuracy:** Standardized authentication examples to use native ADK parameters (`AuthScheme`, `AuthCredential`) instead of manual headers. Corrected Cloud Run transport examples to utilize `StreamableHTTPConnectionParams`. * **Better UX & IA:** Replaced text-heavy descriptions with Mermaid sequence diagrams (e.g., UI rendering flow). Elevated critical deployment requirements (like absolute paths and environment-aware connections) for better scannability. --- ## PR Consolidation Mapping The following table maps the specific lines from the previous disparate PRs to their new homes in the revamped draft: | PR Reference | Original Lines (PR) | New Lines (Draft) | Change Description | | :--- | :--- | :--- | :--- | | **#1234** | 49-74 | 343-436 | Added **Accessing MCP Resources** section, detailing how to use `list_resources()` and `read_resource(name)`. | | **#1443** | 51 | 472-509 | Added **Experimental UI Rendering** section, including the Mermaid sequence diagram and code examples for `meta.ui.resourceUri`. | | **#1188 & #1186** | 43 | 93-100 | Integrated connection timeouts (`timeout`, `sse_read_timeout`) into `StreamableHTTPConnectionParams` for production stability. | ## Review Notes All code snippets have been verified for consistency with Jetski. The environment-aware transport selector now correctly branches between `StdioConnectionParams` (local) and `StreamableHTTPConnectionParams` (production).
✅ 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 6, 2026 22:10
zyantw
changed the title
zyantw
marked this pull request as ready for review
August 11, 2026 22:37
4 tasks
zyantw
commented
Aug 11, 2026
|
|
||
| ## Further resources | ||
|
|
||
| Once you understand the basics, explore [Advanced use cases](/advanced-mcp-tools) for complex implementations and custom integrations. |
Collaborator
Author
There was a problem hiding this comment.
I can update this section once the page for PR #2122 is approved. @joefernandez
Collaborator
There was a problem hiding this comment.
@zyantw - to publish this properly, you should combine the changes of this PR and PR 2122 so that we don't have a temporary loss of content when publishing this cut-down version
zyantw
added a commit
that referenced
this pull request
Aug 11, 2026
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.
This was referenced Aug 20, 2026
| <span class="lst-supported">Supported in ADK</span><span class="lst-python">Python v0.3.10</span><span class="lst-typescript">Typescript v0.2.0</span><span class="lst-go">Go v0.1.0</span><span class="lst-java">Java v0.1.0</span> | ||
| </div> | ||
|
|
||
| ## What is Model Context Protocol (MCP)? |
Collaborator
There was a problem hiding this comment.
remove. don't stack headers. The paragraph below is the intro
|
|
||
| ## What is Model Context Protocol (MCP)? | ||
|
|
||
| The **Model Context Protocol (MCP)** is an open standard for connecting Large Language Models (LLMs) to external data sources, tools, and systems. Think of it as a universal connection mechanism that simplifies how LLMs obtain context, execute actions, and interact with various systems. |
Collaborator
There was a problem hiding this comment.
LLMs --> generative AI models
|
|
||
| ## Core architecture and concepts | ||
|
|
||
| MCP follows a client-server architecture, defining how data or resources, interactive templates or prompts, and actionable functions or tools are exposed by an MCP server and consumed by an MCP client, which could be an LLM host application or an AI agent. |
Collaborator
There was a problem hiding this comment.
Add a sentence explaining that you use the McpToolset class as an interface between MCP Servers and ADK agents. Also mention that it's possible to configure an ADK server as an MCP server for use by other client systems.
|
|
||
| Before you begin, ensure you have the following set up: | ||
|
|
||
| ### Checklist |
Collaborator
There was a problem hiding this comment.
remove. you don't need this header
|
|
||
| When you start building with the Model Context Protocol (MCP) and ADK, these key architectural differences will help you design more stable and efficient agents. | ||
|
|
||
| ### Compare tools |
Collaborator
There was a problem hiding this comment.
remove; use the prior header to introduce this topic; you don't need a second one
|
|
||
| ### Compare tools | ||
|
|
||
| | Dimension | **Direct MCP Tool Integration** (`McpToolset`) | **Specialized Sub-Agent Delegation** (`AgentTool`) | **Agent-Exposed MCP Server** (`to_mcp_server`) | |
Collaborator
There was a problem hiding this comment.
- The names of these implementation options need to be carried through to the headings of later sections. Right now, it's hard to figure our what implementation guides match to these options.
- Recommend linking these implementation options to sections of the guide.
| ## Universal Setup Rules | ||
|
|
||
| 1. **Absolute Paths**: File system MCP servers require absolute path arguments: `os.path.abspath(...)`. Relative paths cause runtime resolution errors in subprocesses. | ||
| 2. **Package Discovery**: When running `adk web`, ensure an `__init__.py` file exists inside your agent folder so ADK can import the package. |
Collaborator
There was a problem hiding this comment.
not clear what this has to do with MCP implementations
|
|
||
| While your agent preserves its session state during lifecycle events, it **does not** automatically re-establish active MCP connections upon restoration. It will re-initialize the connection as needed. | ||
|
|
||
| ## Universal Setup Rules |
Collaborator
There was a problem hiding this comment.
this section seems out of place. Is this actually applicable to all MCP implementations?
|
|
||
| ## Further resources | ||
|
|
||
| Once you understand the basics, explore [Advanced use cases](/advanced-mcp-tools) for complex implementations and custom integrations. |
Collaborator
There was a problem hiding this comment.
@zyantw - to publish this properly, you should combine the changes of this PR and PR 2122 so that we don't have a temporary loss of content when publishing this cut-down version
Collaborator
There was a problem hiding this comment.
after addressing the comments provided, and getting the right structure, let's overwrite the existing mcp-tools.md page with this updated content instead of having a separate page
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
2 participants
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.
This PR consolidates several pending documentation updates into a unified, restructured
mcp-tools.mdguide. It improves the Information Architecture (IA) by grouping deployment, authentication, and transport types. Grounds abstract concepts with concrete code examples separated by language.It also applies some UX principles to improve readability and searchability.
Rendered view: https://deploy-preview-2081--adk-docs-preview.netlify.app/tools-custom/mcp-tools-2/
PR Consolidation Mapping
The following table maps the specific lines from the previous disparate PRs to their new homes in the revamped draft:
list_resources()andread_resource(name).meta.ui.resourceUri.timeout,sse_read_timeout) intoStreamableHTTPConnectionParamsfor production stability.--
Jetski report
High-Level Agent Export (to_mcp_server)
Lines 300–316 correctly implement the ADK agent-to-MCP pattern verified against
google.adk.tools.mcp_tool._agent_to_mcp.py and google.adk.tools.mcp_tool.init.py
Streamable HTTP & SSE Remote Authentication
Lines 473–504 and 574–584 properly configure headers across both Python and TypeScript, matching
MCPSessionManager
UI Rendering Tool Registration
Lines 624–662 declare UI widgets inside list_tools() using meta={"ui": {"resourceUri": "..."}}. This accurately reflects how MCPTool inspects tool schema definitions to emit UiWidget actions to the client.
1. Key Improvements Made in the Revamp
A. Information Architecture & Readability
LlmAgentMcpToolsetMCP Server).McpToolset)AgentTool)to_mcp_server)B. New Features & Modernized APIs
adk.dev)mcp.server.lowlevel.Server.to_mcp_server(agent): Demonstrates one-line compilation of anLlmAgentinto a standard FastMCP server.use_mcp_resources=True.list_resources()andread_resource(name)across Python and TypeScript.meta.ui.resourceUrideclaration in tool registration schemas and how the ADK Web UI renders interactive widgets.SseConnectionParamswithout connection timeouts.StreamableHTTPConnectionParams: Includes explicittimeoutandsse_read_timeoutsettings.StreamableHTTPConnectionParams(Cloud RunK_SERVICE) andStdioConnectionParams(local dev).--staging_bucket).adk deploycommands for Agent Engine and Cloud Run.