Revamping of MCP Tools page by zyantw · Pull Request #2081 · google/adk-docs

zyantw · 2026-08-05T21:05:15Z

PR Summary & Consolidation Mapping

This PR consolidates and restructures MCP documentation across two focused pages:

Core Guide (mcp-tools.md): Basic setup, transports, resource discovery, UI widgets, and to_mcp_server.
Advanced Guide (mcp-tools-advanced.md): Dynamic auth, confirmations, progress tracking, lifecycle management, and cloud deployments.

PR Reference	Location in PR #2081	Description
#1232	`mcp-tools.md:L540-L585`	Added Accessing MCP Resources (`list_resources()`, `read_resource()`).
#1443	`mcp-tools.md:L630-L693`	Added Experimental UI Rendering (`meta.ui.resourceUri` schema & client flow).
#1188 & #1186	`mcp-tools-advanced.md:L42-L78`	Added `timeout` and `sse_read_timeout` to `StreamableHTTPConnectionParams`.

Technical Verification against `google/adk-python`

1. Core API & Usage (`mcp-tools.md`)

Feature / API	Status	Verified Code Link (`google/adk-python`)	Verification Notes
`McpToolset`	`PASS`	`src/google/adk/tools/mcp_tool/__init__.py:L27`	Exported in top-level `google.adk.tools.mcp_tool` namespace.
`StdioConnectionParams`	`PASS`	`src/.../mcp_session_manager.py:L221-L232`	Accepts `server_params: StdioServerParameters` and `timeout: float`.
`StreamableHTTPConnectionParams`	`PASS`	`src/.../mcp_session_manager.py:L422-L449`	Defines `url`, `headers`, `timeout`, and `sse_read_timeout`.
`to_mcp_server(agent)`	`PASS`	`src/.../_agent_to_mcp.py:L170-L207`	Compiles `BaseAgent` into a runnable `FastMCP` server with session isolation.
`adk_to_mcp_tool_type(tool)`	`PASS`	`src/.../conversion_utils.py:L27-L44`	Converts ADK `BaseTool` schemas into MCP `Tool` definitions.
`list_resources()` / `read_resource()`	`PASS`	`src/.../mcp_toolset.py:L552-L584`	Discovers available resource names and reads content blocks by URI.
`AgentTool` (Sub-Agent)	`PASS`	`src/google/adk/tools/agent_tool.py:L109`	Wraps sub-agents to isolate exploratory MCP tool execution.

2. Advanced Configuration (`mcp-tools-advanced.md`)

Feature / Parameter	Status	Verified Code Link (`google/adk-python`)	Verification Notes
`header_provider`	`PASS`	`src/.../mcp_toolset.py:L160-L166` `src/.../mcp_toolset.py:L353-L359`	Dynamic callback `(ReadonlyContext) -> dict[str, str]` evaluated per session turn.
`require_confirmation`	`PASS`	`src/.../mcp_toolset.py:L159` `src/.../function_tool.py:L291-L300`	Supports boolean flags or callable predicates receiving tool arguments.
`progress_callback`	`PASS`	`src/.../mcp_toolset.py:L167` `src/.../mcp_tool.py:L593-L627`	Supports both standard `ProgressFnT` and state-aware `ProgressCallbackFactory`.
`toolset.close()`	`PASS`	`src/.../mcp_toolset.py:L600-L613`	Safely terminates sessions, subprocesses, and streams in standalone runners.
`tool_name_prefix`	`PASS`	`src/.../mcp_toolset.py:L154`	Namespaces tools to prevent naming collisions when aggregating multiple servers.
`sampling_callback` & `elicitation_callback`	`PASS`	`src/.../mcp_toolset.py:L169-L172`	Forwards bi-directional server hooks (LLM sampling & interactive challenges).
`errlog` Redirection	`PASS`	`src/.../mcp_toolset.py:L156`	Redirects MCP subprocess STDERR streams to custom log files / `TextIO` streams.
CLI Deploy Commands	`PASS`	`src/.../cli_tools_click.py:L2387-L2435` `src/.../cli_tools_click.py:L2730-L2805`	`adk deploy cloud_run` and `adk deploy agent_engine` verified with current flags.

Key Improvements & Page Split Rationale

Reduced Cognitive Load: Basic workflows (local/remote connections, tool listing, server wrapping) remain in mcp-tools.md, keeping onboarding fast and uncluttered.
Separation of Advanced Internals: Low-level plumbing (dynamic headers, custom callbacks, standalone runner teardown, bi-directional sampling) is isolated in mcp-tools-advanced.md for enterprise maintainability.
Modernized APIs: Added native to_mcp_server, MCP resource handling, experimental UI widgets, and cleaned CLI flags.

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).

netlify · 2026-08-05T21:05:20Z

✅ Deploy Preview for adk-docs-preview ready!

Name	Link
🔨 Latest commit	`a0490ce`
🔍 Latest deploy log	https://app.netlify.com/projects/adk-docs-preview/deploys/6a7ba06eb7e2fe0009f3740a
😎 Deploy Preview	https://deploy-preview-2081--adk-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

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.

joefernandez · 2026-08-31T15:19:22Z

remember to modify mkdocs.yaml to add this to the navigation

joefernandez · 2026-08-31T15:25:49Z


 <div class="language-support-tag">
-  <span class="lst-supported">Supported in ADK</span><span class="lst-python">Python v0.1.0</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>
+  <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>


revert:
python v0.3.10 -- > v0.1.0

mcp_tool.py added in v0.1.0 :
google/adk-python@9827820#diff-405e85c475912c1b8df589d426b6d7ffa38bea22ec696101fe92bda2c6c64c61

joefernandez · 2026-08-31T15:33:38Z

-  print("Closing MCP server connection...")
-  await toolset.close()
-  print("Cleanup complete.")
+  ```python


tabbed interface isn't rendering properly here, because this line isn't indented 4 spaces

joefernandez · 2026-08-31T15:33:44Z

-```python
-async def my_progress_callback(progress: float, total: float, message: str):
-    print(f"Progress: {progress}/{total} - {message}")
+  ```typescript


tabbed interface isn't rendering properly here, because this line isn't indented 4 spaces

joefernandez · 2026-08-31T15:43:37Z

-            String userId = "user123";
-            String sessionId = "1234";
-            String promptText = "Which files are in this directory - " + yourFolderPath + "?";
+There are three main integration patterns:


reuse this content by making it a second paragraph of the introduction. Explain that the direct integration is covered in this page and other implementations are covered in the advanced guide

joefernandez · 2026-08-31T15:47:56Z

 ```

-### Step 3: Test your Custom MCP Server with an ADK Agent
+### Test your custom MCP server with an ADK Agent


this looks like it's at the wrong heading level (should be H4)

joefernandez · 2026-08-31T15:56:27Z

+
+---
+
+## Choose your mechanism


What am I chosing, here? rework the header to indicate the choice and/or development goal

joefernandez · 2026-08-31T15:58:05Z

+
+---
+
+## Dynamic authentication and per-user headers (`header_provider`)


rework this heading to indicate the development problem being solved by this implementation

joefernandez · 2026-08-31T16:37:01Z

-```dockerfile
-# Example for npm-based MCP servers
-FROM python:3.13-slim
+Standard MCP tools return plain text or JSON output. **Experimental UI Rendering** enables MCP tools to return rich, interactive visual widgets, such as maps, charts, or forms, directly inside the chat interface.


is this still experimental? we should check the code and/or with engineering

joefernandez · 2026-08-31T16:37:27Z

-#### Pattern 1: Self-Contained Stdio MCP Servers
-
-For MCP servers that can be packaged as npm packages or Python modules (like `@modelcontextprotocol/server-filesystem`), you can include them directly in your agent container:
+## UI Rendering 


this seems like an advanced topic (move to advanced page?)

zyantw self-assigned this Aug 5, 2026

Update mcp-tools-draft.md

aae235f

zyantw marked this pull request as draft August 6, 2026 22:10

zyantw changed the title ~~Revamping of MCP Tools page [Still a draft]~~ Revamping of MCP Tools page Aug 6, 2026

zyantw added 2 commits August 7, 2026 14:05

Update mcp-tools-draft.md

7d28ea2

Update mcp-tools-draft.md

aaf6455

zyantw requested a review from joefernandez August 7, 2026 22:34

zyantw added 6 commits August 10, 2026 15:42

Update mcp-tools-draft.md

b7201b8

Update mcp-tools-draft.md

8decf2d

Update mcp-tools-draft.md

10a3090

Update and rename mcp-tools-draft.md to mcp-tools-2.md

787f3ee

Update mcp-tools-2.md

a1f40bb

Update mcp-tools-2.md

a0490ce

zyantw marked this pull request as ready for review August 11, 2026 22:37

zyantw mentioned this pull request Aug 11, 2026

Create advanced-mcp-tools page to split content #2122

Closed

4 tasks

zyantw commented Aug 11, 2026

View reviewed changes

Comment thread docs/tools-custom/mcp-tools-2.md Outdated

joefernandez mentioned this pull request Aug 19, 2026

Update ADK doc according to issue #1227 - 3 - MCP Resources #1232

Closed

joefernandez reviewed Aug 24, 2026

View reviewed changes

Update mcp-tools-2.md

dc0d2ec

zyantw marked this pull request as draft August 26, 2026 22:19

Update mcp-tools-2.md

809e7fc

zyantw added 3 commits August 27, 2026 15:14

Update mcp-tools.md

154b05e

Delete docs/tools-custom/mcp-tools-2.md

8129ecf

Create mcp-tools-advanced.md

fef00f3

zyantw marked this pull request as ready for review August 27, 2026 21:39

zyantw requested a review from joefernandez August 27, 2026 21:39

Update mcp-tools.md

0ddfa03

joefernandez reviewed Aug 31, 2026

View reviewed changes


		---

		## Dynamic authentication and per-user headers (`header_provider`)

Uh oh!

Conversation

zyantw commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary & Consolidation Mapping

Technical Verification against google/adk-python

1. Core API & Usage (mcp-tools.md)

2. Advanced Configuration (mcp-tools-advanced.md)

Key Improvements & Page Split Rationale

Uh oh!

netlify Bot commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for adk-docs-preview ready!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

zyantw commented Aug 5, 2026 •

edited

Loading

Technical Verification against `google/adk-python`

1. Core API & Usage (`mcp-tools.md`)

2. Advanced Configuration (`mcp-tools-advanced.md`)

netlify Bot commented Aug 5, 2026 •

edited

Loading