Google ADK MCP Tutorial: Connect MCP Servers to an ADK Agent With McpToolset

Google's Agent Development Kit (ADK) connects to MCP servers through one class, McpToolset. You add it to an agent's tools list, point it at a server, and ADK discovers the tools, calls them and shuts the connection down when the agent stops.

This tutorial builds a small ADK agent with a local stdio server, switches it to a remote Streamable HTTP server, filters the tools, and covers the deployment rule that trips people up. Code was checked against the ADK MCP tools page on 2 November 2026, with google-adk 2.13.0 current on PyPI.

Three ways ADK and MCP fit together

The ADK docs describe three patterns:

The docs warn that direct McpToolset use has "high context bloat": every tool definition and raw output enters the main agent's history. If one agent needs dozens of MCP tools, consider moving them into a sub-agent wrapped with AgentTool. Our page on too many MCP tools explains the cost.

Prerequisites

• Python. The ADK page says "Python 3.10+," but google-adk 2.13.0 on PyPI declares >=3.11. Use 3.11 or newer.
• pip install "google-adk[mcp]"
• Node.js and npx, to run npm-packaged MCP servers.
• A Gemini API key (or Vertex AI setup) for the model.

Check that both commands are on your path inside the activated environment:

which adk
which npx

Minimal working example (stdio)

ADK expects a package folder with an __init__.py and an agent.py that defines root_agent. This is the docs' filesystem example. StdioServerParameters comes from the official MCP Python SDK:

# my_agent/agent.py
import os

from google.adk.agents import LlmAgent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams
from mcp import StdioServerParameters

TARGET_FOLDER = os.path.abspath("./accessible_files")

root_agent = LlmAgent(
    model="gemini-flash-latest",
    name="filesystem_assistant",
    instruction="Help users manage local files.",
    tools=[
        McpToolset(
            connection_params=StdioConnectionParams(
                server_params=StdioServerParameters(
                    command="npx",
                    args=["-y", "@modelcontextprotocol/server-filesystem", TARGET_FOLDER],
                ),
            ),
            tool_filter=["list_directory", "read_file"],
        )
    ],
)

Then:

1. Create an empty my_agent/__init__.py. The docs say this step "is required for ADK to recognize your agent."
2. From the parent folder, run adk web.
3. Pick filesystem_assistant in the dropdown and ask "List files in the current directory."

tool_filter limits the agent to two read-only tools, even though the filesystem server also offers write tools. Our filesystem server profile lists them all.

Switch to a remote server (Streamable HTTP)

For a hosted server, change the connection params. The docs use Google's Maps MCP endpoint:

import os

from google.adk.agents import LlmAgent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

API_KEY = os.getenv("GOOGLE_MAPS_API_KEY")

root_agent = LlmAgent(
    model="gemini-flash-latest",
    name="travel_planner",
    instruction="Plan travel routes and search locations using Google Maps.",
    tools=[
        McpToolset(
            connection_params=StreamableHTTPConnectionParams(
                url="https://mapstools.googleapis.com/mcp",
                headers={
                    "X-Goog-Api-Key": API_KEY,
                    "Content-Type": "application/json",
                    "Accept": "application/json, text/event-stream",
                },
                timeout=5,
                sse_read_timeout=300,
            )
        )
    ],
)

Set GOOGLE_MAPS_API_KEY in your shell, then run adk web again.

Use your own server

To try a server you wrote, run any Streamable HTTP server on http://localhost:8000/mcp. The FastMCP notes server from our langchain-mcp-adapters tutorial is enough. Point StreamableHTTPConnectionParams(url="http://localhost:8000/mcp") at it.

Add a tool

Add a new function to the server and restart it. ADK lists tools when the toolset connects, so restart adk web as well. If you use tool_filter, add the new tool's name to the list, or the agent will never see it. That is a common "my tool is missing" cause.

Authentication

The docs recommend ADK's auth_scheme and auth_credential parameters "rather than manually injecting HTTP headers." With them, ADK "automatically constructs the required Authorization HTTP headers and manages OAuth 2.0 token refreshes." Static headers, as in the Maps example, still work for API keys. Keep keys in environment variables, never in agent.py.

Resources, not just tools

MCP servers can also expose resources such as files or records. Set use_mcp_resources=True on McpToolset and ADK gives the agent a LoadMcpResourceTool to find and read them on its own.

Test with the MCP Inspector

Before blaming the agent, check the server directly:

npx @modelcontextprotocol/inspector --cli http://localhost:8000/mcp --transport http --method tools/list

Then try the same request in adk web to see whether the agent picks the tool. Our MCP Inspector lesson covers scripted checks.

McpToolset or AgentTool?

Once an agent works, the next question is usually scale. The ADK docs compare the patterns on cost and speed:

• Direct McpToolset gives "lower cost and predictable latency": one model turn, one tool call, one response turn. The trade-off is that every tool schema and every raw result sits in the main agent's context.
• AgentTool delegation has "higher cost and variable latency," because the sub-agent reasons over several turns before it answers. In return, intermediate steps, failed calls and large outputs stay inside the sub-agent.

A practical rule from that comparison:

1. Keep deterministic lookups, such as a Maps query, a database read or a file read, on direct McpToolset with a tight tool_filter.
2. Move trial-and-error work, such as debugging or research across several tools, into a sub-agent with its own instructions and its own MCP toolset.
3. Revisit the split when an agent's tool list grows past about 20 tools, the point at which the docs say schema overload starts to hurt accuracy.

The docs also note model tiering: the orchestrator and the sub-agent can use different models, so a cheaper model can handle the tool calls. For Google's own MCP servers, such as Maps and Cloud services, see our Google MCP overview.

Deploy notes

• Define toolsets synchronously. The docs' deployment rule: "Agents deployed to production must define McpToolset synchronously in agent.py." Older samples that create the toolset in an async factory only work locally.
• Pick the connection by environment. The docs show checking K_SERVICE (set on Cloud Run) to use Streamable HTTP with a bearer token in production and stdio locally.
• Clean up outside adk web. In custom runners, call await toolset.close() or use an async context manager so stdio subprocesses exit.
• Reconnects. ADK does not automatically re-establish MCP connections when a session is restored; agents "re-initialize connections as needed."

Pitfalls

• Missing __init__.py. ADK will not find the agent.
• No timeouts. The docs suggest StdioConnectionParams(timeout=5) "to prevent hanging subprocesses."
• SSE examples. Some ADK examples still use SseConnectionParams. SSE is the deprecated MCP transport; prefer StreamableHTTPConnectionParams. See SSE vs Streamable HTTP.
• Python version. Follow PyPI (3.11+) rather than the docs page (3.10+).

Next step

The free MCP course explains tools, resources and transports if any of this was new. If you want a production MCP server for your ADK agents on Google Cloud, our MCP development team can help.

Frequently asked questions