feat(agents): support remote MCP servers for ManagedAgent with runtime header callbacks

Add `RemoteMcpServer`, a server-side remote MCP tool for `ManagedAgent`. The
Managed Agents / Interactions API runs the MCP server itself, so ADK only
forwards the server URL and headers as an `MCPServerParam` and never opens an
MCP session. A `header_provider` callback (the same contract as the `LlmAgent`
`McpToolset.header_provider`) mints auth headers at request time, driven by the
runner, and is merged over any static headers so a fresh token can be generated
per turn.

Only remote (HTTP/streamable) MCP servers are supported; raw
`types.Tool.mcp_servers` remains rejected. Includes a live integration test
against Maps Grounding Lite, scoped to the Gemini Developer API backend; the
Vertex Interactions endpoint does not yet accept the `mcp_server` tool param
(consistent with google-genai documenting `types.Tool.mcp_servers` as
unsupported on Vertex AI).

Co-authored-by: Haran Rajkumar <haranrk@google.com>
PiperOrigin-RevId: 945306712

Author: haranrk

scripts/compliance_checks.py

@@ -63,6 +63,7 @@
     'src/google/adk/tools/openapi_tool/auth/credential_exchangers/service_account_exchanger.py',
     'src/google/adk/tools/pubsub/pubsub_credentials.py',
     'src/google/adk/tools/spanner/spanner_credentials.py',
+    'tests/integration/test_managed_agent.py',
     'tests/unittests/auth/test_credential_manager.py',
     'tests/unittests/cli/utils/test_gcp_utils.py',
     'tests/unittests/flows/llm_flows/test_functions_request_euc.py',

src/google/adk/agents/_managed_agent.py

@@ -14,6 +14,7 @@
 
 from __future__ import annotations
 
+import inspect
 import logging
 from typing import Any
 from typing import AsyncGenerator
@@ -32,19 +33,22 @@
 
 from ..events.event import Event
 from ..flows.llm_flows.interactions_processor import _find_previous_interaction_state
+from ..models.interactions_utils import _build_mcp_server_param
 from ..models.interactions_utils import _convert_content_to_step
 from ..models.interactions_utils import _create_interactions
 from ..models.interactions_utils import build_interactions_request_log
 from ..models.interactions_utils import convert_tools_config_to_interactions_format
 from ..models.llm_request import LlmRequest
 from ..models.llm_response import LlmResponse
 from ..telemetry import tracer
+from ..tools._remote_mcp_server import RemoteMcpServer
 from ..tools.base_tool import BaseTool
 from ..tools.tool_context import ToolContext
 from ..utils.context_utils import Aclosing
 from ..utils.env_utils import is_enterprise_mode_enabled
 from .base_agent import BaseAgent
 from .invocation_context import InvocationContext
+from .readonly_context import ReadonlyContext
 from .run_config import StreamingMode
 
 if TYPE_CHECKING:
@@ -109,10 +113,12 @@ class ManagedAgent(BaseAgent):
   """An agent backed by the Managed Agents API (interactions.create).
 
   This agent calls the Managed Agents API directly from its execution loop.
-  In this version only server-side tools are supported: ADK built-in tools and
-  raw ``google.genai.types.Tool`` configs (the kinds the interactions converter
-  understands). Client-executed tools (FunctionTool/callables) and MCP are not
-  yet supported.
+  Only server-side tools are supported: ADK built-in tools, raw
+  ``google.genai.types.Tool`` configs (the kinds the interactions converter
+  understands), and server-side remote MCP servers declared as
+  ``RemoteMcpServer`` specs (forwarded to the backend as an ``MCPServerParam``).
+  Client-executed tools (FunctionTool/callables) and raw
+  ``types.Tool.mcp_servers`` configs are not supported and are rejected.
 
   ManagedAgent supports streaming interactions only. Interactions are always
   created with ``background=True`` (required by the Managed Agents workflow) and
@@ -132,10 +138,11 @@ class ManagedAgent(BaseAgent):
   agent_config: Optional[CreateAgentInteractionAgentConfigParam] = None
   """Runtime configuration passed to interactions.create."""
 
-  tools: list[Union[types.Tool, BaseTool, Callable[..., Any]]] = Field(
-      default_factory=list
-  )
-  """Server-side tools: ADK built-in tools or raw types.Tool configs."""
+  tools: list[
+      Union[types.Tool, BaseTool, Callable[..., Any], RemoteMcpServer]
+  ] = Field(default_factory=list)
+  """Server-side tools: ADK built-in tools, raw types.Tool configs, or
+  RemoteMcpServer specs for server-side remote MCP."""
 
   _api_client: Optional[Client] = PrivateAttr(default=None)
 
@@ -176,8 +183,10 @@ async def _resolve_backend_tools(
     """Resolve self.tools into interaction ToolParams (server-side only).
 
     Raw types.Tool configs are passed through; ADK built-in tools are processed
-    into native tool configs. Client-executed tools (FunctionTool/callables) and
-    MCP tools are rejected.
+    into native tool configs. ``RemoteMcpServer`` specs are resolved to an
+    ``MCPServerParam`` (headers minted at request time via ``header_provider``).
+    Client-executed tools (FunctionTool/callables) and raw
+    ``types.Tool.mcp_servers`` configs are rejected.
     """
     # Built-in tools are resolved in "managed agent" mode: the request carries
     # the internal _is_managed_agent flag (and no model), so tools that normally
@@ -186,8 +195,20 @@ async def _resolve_backend_tools(
     llm_request = LlmRequest(config=types.GenerateContentConfig())
     llm_request._is_managed_agent = True
     tool_context = ToolContext(ctx)
+    mcp_params: list[ToolParam] = []
 
     for tool in self.tools:
+      if isinstance(tool, RemoteMcpServer):
+        resolved_headers = dict(tool.headers or {})
+        if tool.header_provider is not None:
+          dynamic = tool.header_provider(ReadonlyContext(ctx))
+          if inspect.isawaitable(dynamic):
+            dynamic = await dynamic
+          if dynamic:
+            resolved_headers.update(dynamic)  # dynamic wins on key conflict
+        mcp_params.append(_build_mcp_server_param(tool, resolved_headers))
+        continue
+
       if isinstance(tool, types.Tool):
         if tool.mcp_servers:
           raise NotImplementedError(
@@ -233,7 +254,10 @@ async def _resolve_backend_tools(
             f'{tool.name}'
         )
 
-    return convert_tools_config_to_interactions_format(llm_request.config)
+    return (
+        convert_tools_config_to_interactions_format(llm_request.config)
+        + mcp_params
+    )
 
   def _response_to_event(
       self, ctx: InvocationContext, llm_response: LlmResponse

src/google/adk/models/interactions_utils.py

@@ -60,6 +60,7 @@
 from google.genai.interactions import InteractionCreatedEvent
 from google.genai.interactions import InteractionSSEEvent
 from google.genai.interactions import InteractionStatusUpdate
+from google.genai.interactions import MCPServerParam
 from google.genai.interactions import ModelOutputStep
 from google.genai.interactions import ModelOutputStepParam
 from google.genai.interactions import Step
@@ -81,6 +82,8 @@
 if TYPE_CHECKING:
   from google.genai import Client
 
+  from ..tools._remote_mcp_server import RemoteMcpServer
+
 from .llm_request import LlmRequest
 from .llm_response import LlmResponse
 
@@ -251,12 +254,12 @@ def convert_part_to_interaction_content(part: types.Part) -> dict | None:
   elif part.thought:
     # part.thought is a boolean indicating this is a thought part
     # ThoughtContentParam expects 'signature' (base64 encoded bytes)
-    result: dict[str, Any] = {'type': 'thought'}
+    thought_result: dict[str, Any] = {'type': 'thought'}
     if part.thought_signature is not None:
-      result['signature'] = base64.b64encode(part.thought_signature).decode(
-          'utf-8'
-      )
-    return result
+      thought_result['signature'] = base64.b64encode(
+          part.thought_signature
+      ).decode('utf-8')
+    return thought_result
   elif part.code_execution_result is not None:
     is_error = part.code_execution_result.outcome in (
         types.Outcome.OUTCOME_FAILED,
@@ -521,6 +524,27 @@ def convert_tools_config_to_interactions_format(
   return interaction_tools
 
 
+def _build_mcp_server_param(
+    server: RemoteMcpServer,
+    resolved_headers: dict[str, str],
+) -> MCPServerParam:
+  """Map a RemoteMcpServer + resolved headers to an interactions MCPServerParam.
+
+  Built directly (not via ``types.McpServer``) so ``allowed_tools`` can be
+  carried and the "not supported in Vertex AI" restriction on
+  ``types.Tool.mcp_servers`` is avoided. ``resolved_headers`` is the static
+  headers already merged with any ``header_provider`` output by the caller.
+  """
+  param: MCPServerParam = {'type': 'mcp_server', 'url': server.url}
+  if server.name is not None:
+    param['name'] = server.name
+  if resolved_headers:
+    param['headers'] = resolved_headers
+  if server.allowed_tools is not None:
+    param['allowed_tools'] = [{'tools': list(server.allowed_tools)}]
+  return param
+
+
 def _function_result_to_response(
     result: BaseModel | dict[str, Any] | list[Any] | str,
 ) -> dict[str, Any]:

src/google/adk/tools/__init__.py

@@ -20,6 +20,7 @@
 # The TYPE_CHECKING block is needed for autocomplete to work.
 if TYPE_CHECKING:
   from ..auth.auth_tool import AuthToolArguments
+  from ._remote_mcp_server import RemoteMcpServer
   from ._request_input_tool import request_input
   from .agent_tool import AgentTool
   from .api_registry import ApiRegistry
@@ -83,6 +84,7 @@
     ),
     'preload_memory': ('.preload_memory_tool', 'preload_memory_tool'),
     'request_input': ('._request_input_tool', 'request_input'),
+    'RemoteMcpServer': ('._remote_mcp_server', 'RemoteMcpServer'),
     'ToolContext': ('.tool_context', 'ToolContext'),
     'transfer_to_agent': ('.transfer_to_agent_tool', 'transfer_to_agent'),
     'TransferToAgentTool': (

src/google/adk/tools/_remote_mcp_server.py

@@ -0,0 +1,68 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from typing import Awaitable
+from typing import Callable
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+
+if TYPE_CHECKING:
+  from ..agents.readonly_context import ReadonlyContext
+
+  HeaderProvider = Callable[
+      [ReadonlyContext], dict[str, str] | Awaitable[dict[str, str]]
+  ]
+else:
+  HeaderProvider = Callable[..., dict[str, str] | Awaitable[dict[str, str]]]
+
+
+class RemoteMcpServer(BaseModel):
+  """A remote MCP server executed server-side by the Managed Agents API.
+
+  ``ManagedAgent`` forwards the server's URL and headers to
+  ``interactions.create``; the Interactions backend opens the MCP session and
+  runs the tools. Only remote (HTTP/streamable) MCP servers are supported.
+
+  This is server-side MCP: unlike ``LlmAgent``'s ``McpToolset`` (which opens the
+  session and executes tools client-side), ADK never connects to the MCP server
+  here. The reused concept is the ``header_provider`` callback contract.
+  """
+
+  model_config = ConfigDict(arbitrary_types_allowed=True, extra='forbid')
+
+  url: str
+  """Full URL of the remote MCP server endpoint (e.g.
+  'https://api.example.com/mcp'). Maps to ``MCPServerParam.url``."""
+
+  name: str | None = None
+  """Optional server label. Maps to ``MCPServerParam.name``."""
+
+  headers: dict[str, str] | None = None
+  """Static headers sent on every turn (e.g. a fixed API key). Merged with
+  ``header_provider`` output; ``header_provider`` wins on key conflict."""
+
+  allowed_tools: list[str] | None = None
+  """Restrict which of the server's tools are exposed. Maps to
+  ``MCPServerParam.allowed_tools``."""
+
+  header_provider: HeaderProvider | None = None
+  """Runtime callback that mints headers (e.g. a fresh bearer token) at request
+  time. Invoked by ``ManagedAgent`` during resolution (runner-driven), once per
+  turn. Receives a ``ReadonlyContext`` and returns a headers dict (or an
+  awaitable of one). Same contract as ``LlmAgent``'s
+  ``McpToolset.header_provider``."""

tests/integration/test_managed_agent.py

@@ -22,10 +22,13 @@
 
 from __future__ import annotations
 
+import os
+
 from google.adk.agents import ManagedAgent
 from google.adk.runners import Runner
 from google.adk.sessions.in_memory_session_service import InMemorySessionService
 from google.adk.tools import google_search
+from google.adk.tools import RemoteMcpServer
 from google.adk.utils.context_utils import Aclosing
 from google.genai import types
 import pytest
@@ -121,3 +124,49 @@ async def test_code_execution_prime_sum():
   assert (
       '5117' in normalized
   ), f'expected the code-executed sum 5117; got: {answer!r}'
+
+
+@pytest.mark.asyncio
+# Server-side remote MCP (mcp_server tool param) is currently only accepted by
+# the Gemini Developer API Interactions endpoint. The Vertex Interactions
+# endpoint returns 400 invalid_request for it (google-genai likewise documents
+# types.Tool.mcp_servers as unsupported on Vertex AI), so this live test is
+# scoped to GOOGLE_AI.
+@pytest.mark.parametrize('llm_backend', ['GOOGLE_AI'], indirect=True)
+@pytest.mark.skipif(
+    not os.environ.get('GOOGLE_MAPS_API_KEY'),
+    reason='GOOGLE_MAPS_API_KEY not set',
+)
+async def test_remote_mcp_maps_grounding_lite():
+  agent = ManagedAgent(
+      name='managed_maps_agent',
+      agent_id=_AGENT_ID,
+      environment={'type': 'remote'},
+      tools=[
+          RemoteMcpServer(
+              name='maps_grounding_lite',
+              url='https://mapstools.googleapis.com/mcp',
+              header_provider=lambda ctx: {
+                  'X-Goog-Api-Key': os.environ['GOOGLE_MAPS_API_KEY']
+              },
+          )
+      ],
+  )
+  session_service = InMemorySessionService()
+  runner = Runner(
+      app_name='managed_agent_it',
+      agent=agent,
+      session_service=session_service,
+  )
+  session = await session_service.create_session(
+      app_name='managed_agent_it', user_id='test_user'
+  )
+
+  events = await _run_turn(
+      runner, session, 'Find a few coffee shops near Golden Gate Park.'
+  )
+
+  # Non-deterministic content; assert a non-empty grounded answer came back and
+  # no terminal error event was emitted.
+  assert _joined_text(events).strip()
+  assert not any(e.error_code for e in events)