Note: To ensure a consistent and high-performance experience, this lab may provide cached responses for some model requests.

GENAI124

Overview

In this lab, you explore Model Context Protocol (MCP), an open standard that enables seamless integration between external services, data sources, tools, and applications. You learn how to integrate MCP into your Agent Development Kit (ADK) agents, using tools provided by existing MCP servers to enhance your ADK workflows. Additionally, you discover 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 perform the following tasks:

• 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 MCP.

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 are made available to you.

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

To complete this lab, you need:

• Access to a standard internet browser (Chrome browser recommended).

Note: Use an Incognito (recommended) or private browser window to run this lab. This prevents conflicts between your personal account and the student account, which may cause extra charges incurred to your personal account.

• Time to complete the lab—remember, once you start, you cannot pause a lab.

Note: Use only the student account for this lab. If you use a different Google Cloud account, you may incur charges to that account.

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 the ADK and set up your environment

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

Prepare a Cloud Shell Editor tab

1. From the Google Cloud console, 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. Click the Open Editor icon () at the top of the pane to view files.
6. At the top of the left-hand navigation menu, click the Explorer icon () to open your file explorer.
7. Click the Open Folder button.
8. In the Open Folder dialog that opens, click OK to select your student account's home folder.
9. 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.
10. Throughout the rest of this lab, you work in this window as your IDE with the Cloud Shell Editor and Cloud Shell terminal.

Download and install the ADK and code samples for this lab

In this section, you run the commands that follow in the Cloud Shell terminal.

1. Run the following command in the Cloud Shell terminal to copy the project directory from Cloud Storage:

   gcloud storage cp -r gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/* .

2. Run the following commands to install the Agent Development Kit (ADK) and other dependencies required to run the sample applications:

   export PATH=$PATH:"/home/${USER}/.local/bin" python3 -m pip install google-adk==1.22.1 -r adk_mcp_tools/requirements.txt

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

Task 2. Use the Google Maps MCP server with ADK agents (ADK as an MCP client) in the ADK Dev UI

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 an API key and enable the APIs

The Google Maps MCP server requires an API key to communicate with Google Maps services. In this step, you generate a new API key named GOOGLE_MAPS_API_KEY and restrict it to the Directions and Routes APIs for security.

1. Go to the Google Cloud console browser tab (not your Cloud Shell Editor).

2. You can close the Cloud Shell terminal pane in 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.

5. For Name, type GOOGLE_MAPS_API_KEY

6. For APIs that can be accessed using this key, select the following APIs:

   • Directions API
   • Routes API

7. Click Create.

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

8. Click Close on the dialog box.

   

Define your Agent with an MCPToolset for Google Maps

Now you will configure your agent to use the Google Maps tools. By adding the MCPToolset, you enable the agent to dynamically discover and call the Maps APIs when needed.

1. Paste the following command into a plain text document on your computer, 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=global GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_API_KEY" MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} EOF

2. Copy and paste the updated command into the Cloud Shell terminal and run it to write a .env file, which provides authentication details for this agent directory.

3. Copy the .env file to the other agent directory for later use in this lab by running the following command:

   cp google_maps_mcp_agent/.env adk_mcp_server/.env

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

5. Navigate to the directory adk_mcp_tools/google_maps_mcp_agent.

6. Open agent.py and add the following code after the comment ## Add the MCPToolset (on a new line after line 53) to configure the agent's connection to the Google Maps MCP server:

   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. Save the file.

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

   adk web --allow_origins "regex:https://.*.cloudshell.dev" --otel_to_cloud --reload_agents

   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)

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

10. A new browser tab opens with the ADK Dev UI. From the Select an agent drop-down on the left, select the google_maps_mcp_agent.

11. 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:

    

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

    

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

    

    On the Event 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.

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

14. 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 the API key and deploy the ADK agent

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

In this section, you 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 and select the adk_mcp_tools/adk_mcp_server directory.

2. Open the Python file named adk_server.py. This file contains the logic for your custom MCP server. Review the code to understand how it wraps the ADK tool and serves it.

   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

1. Open agent.py in the adk_mcp_server directory.

2. In line 31, update the value of PATH_TO_YOUR_MCP_SERVER_SCRIPT to the following path so the agent can connect to your custom server script:

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

3. Next, add the following code in line 55, i.e. after where it says ## Add the MCPToolset below: 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 uses 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 ) ],

4. Save the file.

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

   python3 ~/adk_mcp_tools/adk_mcp_server/adk_server.py

   Output:

   

6. Open a new Cloud Shell terminal tab by clicking the button at the top of the Cloud Shell terminal window.

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

   export PATH=$PATH:"/home/${USER}/.local/bin" cd ~/adk_mcp_tools adk web --allow_origins "regex:https://.*.cloudshell.dev" --otel_to_cloud --reload_agents Note: `PATH` has been added to this command to reset it, as the new Cloud Shell terminal may give you an error if you ran the rest of the command without it. Typically this would be an `adk web` not found error.

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

9. From the Select an agent drop-down on the left, select the adk_mcp_server.

10. Prompt the agent with the following:

    Load the content from http://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 receives the call_tool request, executes the ADK load_web_page tool, and returns the result.
    • The ADK agent then relays 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!

In this lab, you learned how to integrate external Model Context Protocol (MCP) tools into your Agent Development Kit (ADK) agents using the MCPToolset class. You 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 April 21, 2026

Lab Last Tested April 21, 2026

Copyright 2026 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.