GENAI124

Overview

In this lab, you will explore Model Context Protocol (MCP), an open standard that enables seamless integration between external services, data sources, tools, and applications. You will learn how to integrate MCP into your ADK agents, using tools provided by existing MCP servers to enhance your ADK workflows. Additionally, you will see how to expose ADK tools like load_web_page through a custom-built MCP server, enabling broader integration with MCP clients.

What is Model Context Protocol (MCP)?

Model Context Protocol (MCP) is an open standard designed to standardize how Large Language Models (LLMs) like Gemini and Claude communicate with external applications, data sources, and tools. Think of it as a universal connection mechanism that simplifies how LLMs obtain context, execute actions, and interact with various systems.

MCP follows a client-server architecture, defining how data (resources), interactive templates (prompts), and actionable functions (tools) are exposed by an MCP server and consumed by an MCP client (which could be an LLM host application or an AI agent).

This lab covers two primary integration patterns:

• Using existing MCP Servers within ADK: An ADK agent acts as an MCP client, leveraging tools provided by external MCP servers.
• Exposing ADK Tools via an MCP Server: Building an MCP server that wraps ADK tools, making them accessible to any MCP client.

Objectives

In this lab, you learn how to:

• Use an ADK agent as an MCP client to interact with tools from existing MCP servers.
• Configure and deploy your own MCP server to expose ADK tools to other clients.
• Connect ADK agents with external tools through standardized MCP communication.
• Enable seamless interaction between LLMs and tools using Model Context Protocol.

Setup and requirements

Before you click the Start Lab button

Read these instructions. Labs are timed and you cannot pause them. The timer, which starts when you click Start Lab, shows how long Google Cloud resources will be made available to you.

This Qwiklabs hands-on lab lets you do the lab activities yourself in a real cloud environment, not in a simulation or demo environment. It does so by giving you new, temporary credentials that you use to sign in and access Google Cloud for the duration of the lab.

What you need

To complete this lab, you need:

• Access to a standard internet browser (Chrome browser recommended).
• Time to complete the lab.

Note: If you already have your own personal Google Cloud account or project, do not use it for this lab.

Note: If you are using a Pixelbook, open an Incognito window to run this lab.

How to start your lab and sign in to the Google Cloud console

1. Click the Start Lab button. If you need to pay for the lab, a dialog opens for you to select your payment method. On the left is the Lab Details pane with the following:

   • The Open Google Cloud console button
   • Time remaining
   • The temporary credentials that you must use for this lab
   • Other information, if needed, to step through this lab

2. Click Open Google Cloud console (or right-click and select Open Link in Incognito Window if you are running the Chrome browser).

   The lab spins up resources, and then opens another tab that shows the Sign in page.

   Tip: Arrange the tabs in separate windows, side-by-side.

   Note: If you see the Choose an account dialog, click Use Another Account.

3. If necessary, copy the Username below and paste it into the Sign in dialog.

   {{{user_0.username | "Username"}}}

   You can also find the Username in the Lab Details pane.

4. Click Next.

5. Copy the Password below and paste it into the Welcome dialog.

   {{{user_0.password | "Password"}}}

   You can also find the Password in the Lab Details pane.

6. Click Next.

   Important: You must use the credentials the lab provides you. Do not use your Google Cloud account credentials. Note: Using your own Google Cloud account for this lab may incur extra charges.

7. Click through the subsequent pages:

   • Accept the terms and conditions.
   • Do not add recovery options or two-factor authentication (because this is a temporary account).
   • Do not sign up for free trials.

After a few moments, the Google Cloud console opens in this tab.

Note: To access Google Cloud products and services, click the Navigation menu or type the service or product name in the Search field.

Task 1. Install ADK and set up your environment

In this lab environment, the Vertex AI API, Routes API and Directions API have been enabled for you.

Prepare a Cloud Shell Editor tab

1. With your Google Cloud console window selected, open Cloud Shell by pressing the G key and then the S key on your keyboard. Alternatively, you can click the Activate Cloud Shell button () in the upper right of the Cloud console.

2. Click Continue.

3. When prompted to authorize Cloud Shell, click Authorize.

4. In the upper right corner of the Cloud Shell Terminal panel, click the Open in new window button .

5. In the Cloud Shell Terminal, enter the following to open the Cloud Shell Editor to your home directory:

   cloudshell workspace ~

6. Close any additional tutorial or Gemini panels that appear on the right side of the screen to save more of your window for your code editor.

7. Throughout the rest of this lab, you can work in this window as your IDE with the Cloud Shell Editor and Cloud Shell Terminal.

Download and install ADK and code samples for this lab

1. Install ADK by running the following command in the Cloud Shell Terminal.

   Note: You will specify the version to ensure that the version of ADK that you install corresponds to the version used in this lab. You can view the latest version number and release notes at the adk-python repo. sudo python3 -m pip install google-adk==1.5.0

2. Paste the following commands into the Cloud Shell Terminal to copy a file from a Cloud Storage bucket, and unzip it, creating a project directory with code for this lab:

   gcloud storage cp gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/adk_mcp_tools.zip . unzip adk_mcp_tools.zip

3. Install additional lab requirements with:

   python3 -m pip install -r adk_mcp_tools/requirements.txt

Click Check my progress to verify the objective. Install ADK and set up your environment

Task 2. Using Google Maps MCP server with ADK agents (ADK as an MCP client) in adk web

This section demonstrates how to integrate tools from an external Google Maps MCP server into your ADK agents. This is the most common integration pattern when your ADK agent needs to use capabilities provided by an existing service that exposes an MCP interface. You will see how the MCPToolset class can be directly added to your agent's tools list, enabling seamless connection to an MCP server, discovery of its tools, and making them available for your agent to use. These examples primarily focus on interactions within the adk web development environment.

MCPToolset

The MCPToolset class is ADK's primary mechanism for integrating tools from an MCP server. When you include an MCPToolset instance in your agent's tools list, it automatically handles the interaction with the specified MCP server. Here's how it works:

• Connection Management: On initialization, MCPToolset establishes and manages the connection to the MCP server. This can be a local server process (using StdioServerParameters for communication over standard input/output) or a remote server (using SseServerParams for Server-Sent Events). The toolset also handles the graceful shutdown of this connection when the agent or application terminates.
• Tool Discovery & Adaptation: Once connected, MCPToolset queries the MCP server for its available tools (via the list_tools MCP method). It then converts the schemas of these discovered MCP tools into ADK-compatible BaseTool instances.
• Exposure to Agent: These adapted tools are then made available to your LlmAgent as if they were native ADK tools.
• Proxying Tool Calls: When your LlmAgent decides to use one of these tools, MCPToolset transparently proxies the call (using the call_tool MCP method) to the MCP server, sends the necessary arguments, and returns the server's response back to the agent.
• Filtering (Optional): You can use the tool_filter parameter when creating an MCPToolset to select a specific subset of tools from the MCP server, rather than exposing all of them to your agent.

Get API key and Enable APIs

In this sub-section, you will generate a new API key named GOOGLE_MAPS_API_KEY.

1. Open the browser tab displaying the Google Cloud Console (not your Cloud Shell Editor).

2. You can close the Cloud Shell Terminal pane on this browser tab for more console area.

3. Search for Credentials in the search bar at the top of the page. Select it from the results.

4. On the Credentials page, click + Create Credentials at the top of the page, then select API key.

   The API key created dialog will display your newly created API key. Be sure to save this key locally for later use in the lab.

5. Click Close on the dialog box.

   Your newly created key will be named API Key 1 by default. Select the key, rename it to GOOGLE_MAPS_API_KEY, and click Save.

   

Define your Agent with an MCPToolset for Google Maps

In this sub-section, you will configure your agent to use the MCPToolset for Google Maps, enabling it to seamlessly provide directions and location-based information.

1. In the Cloud Shell Editor's file explorer pane, find the adk_mcp_tools folder. Click it to toggle it open.

2. Navigate to the directory adk_mcp_tools/google_maps_mcp_agent.

3. Paste the following command in a plain text file, then update the YOUR_ACTUAL_API_KEY value with the Google Maps API key you generated and saved in a previous step:

   cd ~/adk_mcp_tools cat << EOF > google_maps_mcp_agent/.env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id | Project }}} GOOGLE_CLOUD_LOCATION={{{ project_0.default_region | Region}}} GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_API_KEY" MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} EOF

4. Copy and paste the updated command to Cloud Shell Terminal to run it and write a .env file which will provide authentication details for this agent directory.

5. Copy the .env file to the other agent directory you will use in this lab by running the following command:

   cp google_maps_mcp_agent/.env adk_mcp_server/.env

6. Next, add the following code where indicated in the agent.py file to add the Google maps tool to your agent. This will allow your agent to use the MCPToolset for Google Maps to provide directions or location-based information.

   tools=[ MCPToolset( connection_params=StdioConnectionParams( server_params=StdioServerParameters( command='npx', args=[ "-y", "@modelcontextprotocol/server-google-maps", ], env={ "GOOGLE_MAPS_API_KEY": google_maps_api_key } ), timeout=15, ), ) ],

7. From the adk_mcp_tools project directory, launch the Agent Development Kit Dev UI with the following command:

   adk web

   Output:

   INFO: Started server process [2434] INFO: Waiting for application startup. +----------------------------------------------------+ | ADK Web Server started | | | | For local testing, access at http://localhost:8000.| +----------------------------------------------------+ INFO: Application startup complete. INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

8. To view the web interface in a new tab, click the http://127.0.0.1:8000 link in the Terminal output.

9. A new browser tab will open with the ADK Dev UI. From the Select an agent dropdown on the left, select the google_maps_mcp_agent from the dropdown.

10. Start a conversation with the agent and run the following prompts:

    Get directions from GooglePlex to SFO. Note: If your API call times out the first time you use it, click + New Session in the upper right of the ADK Dev UI and try again. What's the route from Paris, France to Berlin, Germany?

    Output:

    

11. Click the agent icon next to the agent's chat bubble with a lightning bolt, which indicates a function call. This will open up the Event inspector for this event:

    

12. Notice that agent graph indicates several different tools, identified by the wrench emoji (🔧). Even though you only imported one MCPToolset, that tool set came with the different tools you see listed here, such as maps_place_details and maps_directions.

    

13. On the Request tab, you can see the structure of the request. You can use the arrows at the top of the Event inspector to browse the agent's thoughts, function calls, and responses.

14. When you are finished asking questions of this agent, close the dev UI browser tab.

15. Go back to the Cloud Shell Terminal panel and press CTRL + C to stop the server.

Click Check my progress to verify the objective. Create API key and deploy ADK agent

Task 3. Building an MCP server with ADK tools (MCP server exposing ADK)

In this section, you'll learn how to expose the ADK load_web_page tool through a custom-built MCP server. This pattern allows you to wrap existing ADK tools and make them accessible to any standard MCP client application.

Create the MCP Server Script and Implement Server Logic

1. Return to your Cloud Shell Editor tab and select the adk_mcp_tools/adk_mcp_server directory.

2. A Python file named adk_server.py has been prepared and commented for you. Take some time to review that file, reading the comments to understand how the code wraps a tool and serves it as an MCP server. Notice how it allows MCP clients to list available tools as well as invoke the ADK tool asynchronously, handling requests and responses in an MCP-compliant format.

Test the Custom MCP Server with an ADK Agent

3. Click on the agent.py file in the adk_mcp_server directory.

4. Update the path to your adk_server.py file.

   /home/{{{project_0.startup_script.updated_lab_username | Username}}}/adk_mcp_tools/adk_mcp_server/adk_server.py

5. Next, add the following code where indicated in the agent.py file to add the MCPToolset to your agent. An ADK agent acts as a client to the MCP server. This ADK agent will use MCPToolset to connect to your adk_server.py script.

   tools=[ MCPToolset( connection_params=StdioConnectionParams( server_params=StdioServerParameters( command="python3", # Command to run your MCP server script args=[PATH_TO_YOUR_MCP_SERVER_SCRIPT], # Argument is the path to the script ), timeout=15, ), tool_filter=['load_web_page'] # Optional: ensure only specific tools are loaded ) ],

6. To run the MCP server, start the adk_server.py script by running the following command in Cloud Shell Terminal:

   python3 ~/adk_mcp_tools/adk_mcp_server/adk_server.py

   Output:

   

7. Open a new Cloud Shell Terminal tab by clicking the button at the top of the Cloud Shell Terminal window.

8. In the Cloud Shell Terminal, from the adk_mcp_tools project directory, launch the Agent Development Kit Dev UI with the following command:

   cd ~/adk_mcp_tools adk web

9. To view the web interface in a new tab, click the http://127.0.0.1:8000 link in the Terminal output.

10. From the Select an agent dropdown on the left, select the adk_mcp_server from the dropdown.

11. Query the agent with:

    Load the content from https://example.com.

    Output:

    

    What happens here:

    • The ADK agent (web_reader_mcp_client_agent) uses the MCPToolset to connect to your adk_server.py.
    • The MCP server will receive the call_tool request, execute the ADK load_web_page tool, and return the result.
    • The ADK agent will then relay this information. You should see logs from both the ADK Web UI (and its terminal) and from your adk_server.py terminal in the Cloud Shell Terminal tab where it is running.

    This demonstrates that ADK tools can be encapsulated within an MCP server, making them accessible to a broad range of MCP-compliant clients including ADK agents.

Congratulations!

At the end of this lab, you have learned how to integrate external Model Context Protocol (MCP) tools into your ADK agents using the MCPToolset class. You’ve discovered how to connect to an MCP server, use its tools within your agent, and expose ADK tools like load_web_page through a custom MCP server. These skills enable you to extend your ADK agents with powerful, external services, enhancing your web development workflows.

Manual Last Updated October 6, 2025

Lab Last Tested October 6, 2025

Copyright 2023 Google LLC All rights reserved. Google and the Google logo are trademarks of Google LLC. All other company and product names may be trademarks of the respective companies with which they are associated.