MCP AI Agent with Google ADK, Google Maps, and Opik

This project demonstrates the creation of an AI Agent using the Google Agent Development Kit (ADK), OpenAI's GPT-4o model, the Google Maps MCP Server, and Opik for observability with Comet.ml.

The primary goal of this project is to deepen my understanding of Agent Development principles, the application of the Model Context Protocol in practice, and how to integrate its tools and services into an AI Agent for enhanced abilities beyond the training data.

This project is largely inspired by Santiago Valdarrama's tutorial on YouTube:

• Video: Building AI Agents with Google's Agent Development Kit (ADK)
• Repo: svpino/google-adk-sample

Table of Contents

• Key Technologies
  • Google Agent Development Kit (ADK)
  • Opik & CometML
  • Model Context Protocol (MCP)
  • Google Maps MCP Server
• Project Structure
• Project Setup and Installation
  • Prerequisites
  • Installation Steps
  • Environment Variables
  • Running the Agent
• Screenshots & Usage
  • ADK Web UI
  • Agent Using Tools (Directions)
  • Conversation Events & Tool Graph
  • Opik (CometML) Tracing
• Code Deep Dive (agent.py)
  • Imports and Setup
  • Agent Definition
  • MCP Toolset Configuration
  • Opik Tracing Callbacks
• Video Demonstration
• Author
• License

Key Technologies

Google Agent Development Kit (ADK)

The Google Agent Development Kit (ADK) is a Python framework designed to simplify the development of AI Agents powered by LLMs. It provides access to tools, memory, agent orchestration and LLMs from providers like OpenAI, Anthropic, Cohere and many others through integration with the LiteLlm library. The ADK also includes a web UI for interacting with and debugging agents.

Opik & CometML

Opik is an open-source observability solution for LLM applications, built by Comet. It allows you to trace, visualize, and debug the interactions within your AI Agents, including LLM calls, tool usage, and other operations. In this project, Opik is configured to send traces to CometML, providing a rich UI to inspect agent behavior.

Model Context Protocol (MCP)

The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to LLMs and connect them to different data sources and tools. It defines a schema for tool descriptions, invocations, and responses. This allows for interoperability between different LLM systems and tool providers.

Google Maps MCP Server

The Google Maps MCP Server is a Node.js application that exposes Google Maps Platform APIs as MCP tools. This allows an ADK Agent to easily leverage Google Maps features to deliver more relevant, context-aware responses.

• How it runs: The ADK's MCPToolset can automatically start this server using npx if it's not already running, as configured in this project.
• Main Tools Exposed:
  • maps_directions: Get driving, walking, or cycling directions.
  • maps_geocode: Convert addresses to geographic coordinates.
  • maps_reverse_geocode: Convert geographic coordinates to addresses.
  • maps_elevation: Get elevation for a given coordinate.
  • maps_search_places: Search for places (e.g., restaurants, landmarks).
  • maps_place_details: Get detailed information about a specific place.
  • maps_distance_matrix: Calculate travel time and distance between multiple origins and destinations.

Project Structure

.
├── assets
│   └── screenshots
│       ├── interface.png
│       ├── maps_direction_tool_input_output.png
│       ├── maps_direction_tool_opik.png
│       ├── maps_direction_tool.png
│       ├── maps_directions_tool_events.png
│       ├── maps_elevation_tool.png
│       ├── maps_place_details_event.png
│       ├── maps_reverse_geocode_event.png
│       ├── opik_overall_input_output.png
|       ├── adk.png
|       ├── mcp.png
│       └── opik_traces.png
├── examples
│   └── agent_conversation.yaml
├── LICENSE
├── mcp_agent
│   ├── __init__.py
│   └── agent.py
├── pyproject.toml
├── README.md
└── uv.lock

Project Setup and Installation

Prerequisites

• Python 3.11
• uv (Python package and virtual environment manager)
• Node.js and npm / npx (required to run the Google Maps MCP Server, which the ADK will start via npx)
• A Google Maps Platform API Key?
• An OpenAI API Key.
• CometML API Key, Project ID, and Workspace.

Installation Steps

1. Clone the repository:

   git clone https://github.com/luuisotorres/mcp-ai-agent.git
   cd mcp-ai-agent
   

2. Create and sync the virtual environment using UV:

   uv venv  # Create a virtual environment (e.g., .venv)
   uv sync  # Install dependencies from pyproject.toml
   source .venv/bin/activate # Or `.\.venv\Scripts\activate` on Windows
   

3. Set up environment variables: Copy the example environment file and fill in your credentials:

   cp .env.example .env
   

   Then, edit .env with your actual API keys.

Environment Variables

GOOGLE_MAPS_PLATFORM_API_KEY="your-google-maps-api-key"
OPENAI_API_KEY="your-openai-api-key"
COMET_API_KEY="your-comet-api-key"
COMET_WORKSPACE="your-comet-workspace"
COMET_PROJECT_NAME="your-comet-project-name"

The .env file should contain:

• GOOGLE_MAPS_PLATFORM_API_KEY: Your Google Maps Platform API key.
  • Purpose: Allows the Google Maps MCP Server to make requests to Google Maps APIs.
• OPENAI_API_KEY: Your OpenAI API key.
  • Purpose: Allows the LiteLlm model to use OpenAI's GPT models.
• COMET_API_KEY: Your CometML API Key.
  • Purpose: For Opik to send traces to your CometML project.
• COMET_WORKSPACE: Your CometML workspace.
• COMET_PROJECT_NAME: The CometML project name where traces will be stored.

Running the Agent

Once the setup is complete, run the ADK web UI:

uv run adk web

This command will:

1. Start a FastAPI server.
2. Provide a web interface at http://127.0.0.1:8000 to interact with your agent.
3. The MCPToolset in agent.py is configured to start the Google Maps MCP server via npx automatically when the agent needs to use its tools.

Screenshots & Usage

ADK Web UI

Upon running uv run adk web and navigating to http://127.0.0.1:8000 (or the port shown in your terminal), you'll see the ADK Web UI. You can select your Agent, in this case mcp_agent, and start a conversation.

(Screenshot 1: The initial ADK Web UI screen with the chat input.) Caption: The main interface of the ADK Web UI where you can type messages to your agent.

Agent Using Tools

The agent can understand requests for directions, place details, elevation, and more, using the tools from the Google Maps MCP Server.

Example: Getting Directions The agent responds to "How do I drive from São Paulo to Campinas?" with turn-by-turn directions.

(Screenshot 2: Agent using the maps_directions tool.) Caption: The agent successfully uses the maps_directions tool to provide driving directions in the chat interface.

Example: Getting Place Details The agent can fetch reviews and other information for landmarks.

(Screenshot 3: Agent using maps_place_details for Eiffel Tower reviews.) Caption: Agent fetching and displaying reviews for the Eiffel Tower, showcasing the maps_place_details tool usage and output.

Example: Getting Elevation The agent can provide elevation for given coordinates.

(Screenshot 4: Agent using maps_elevation tool.) Caption: Agent providing the elevation for specified coordinates using the maps_elevation tool.

Conversation Events & Tool Invocation

The ADK Web UI provides an "Events" (or "Trace") tab where you can inspect the flow of the conversation. This includes the function calls made by the agent and the responses received from tools.

Example: maps_reverse_geocode Event Shows the agent invoking the maps_reverse_geocode tool.

(Screenshot 5: Event view for maps_reverse_geocode.) Caption: Event view detailing a functionCall for maps_reverse_geocode with args and Metadata.

Example: maps_directions Event Flow Illustrates the sequence of events when the maps_directions tool is called.

(Screenshot 6: Event view for maps_directions tool.) Caption: The "Events" tab in the ADK UI, showing the invocation details for the maps_directions tool.

Opik (CometML) Tracing

Opik integrates with CometML to provide detailed traces of your agent's execution, offering insights into LLM calls, tool usage, and overall performance.

Overall Traces in Opik A list of all captured interactions for the project.

(Screenshot 7: Overview of traces in CometML for the mcp-ai-agent project.) Caption: The CometML UI showing a list of traces captured by Opik for different agent interactions.

Detailed Opik Trace for maps_direction_tool A specific trace showing the LLM call and the maps_direction_tool invocation.

(Screenshot 8: Detailed view of a single trace involving the maps_directions tool.) Caption: A detailed view of an Opik trace in CometML, showing the sequence of operations for a maps_directions request, including the LLM call and tool interaction.

Input/Output YAML in Opik Detailed request and response data for LLM calls and tool interactions, presented in YAML.

(Screenshot 9: Input/Output details for the maps_direction tool call in Opik.) Caption: The Input/Output tab within an Opik trace in CometML, displaying the request and response of the entire conversation in YAML format.

These traces are invaluable for debugging, understanding agent behavior, and optimizing performance.

Note: You can find the entire YAML file for this conversation at examples/agent_conversation.yaml

Code Deep Dive (agent.py)

Imports and Setup

We begin by importing the required packages for ADK, environment configuration, and observability:

from google.adk.agents import LlmAgent
from google.adk.models.lite_llm import LiteLlm
from google.adk.tools.mcp_tool.mcp_toolset import (
    MCPToolset,
    StdioServerParameters
)
import os
from dotenv import load_dotenv
import opik
from opik.integrations.adk import OpikTracer

This sets the foundation for the agent logic.

Environment Configuration

Here we load API keys and configure observability:

load_dotenv()
opik.configure(use_local=False)
tracer = OpikTracer()
GOOGLE_MAPS_API_KEY = os.getenv("GOOGLE_MAPS_PLATFORM_API_KEY")

Agent Definition

We initialize an ADK Agent with LlmAgent using OpenAI's GPT-4o model and the LiteLlm library for ADK <> OpenAI integration:

root_agent = LlmAgent(
    model=LiteLlm(model="openai/gpt-4o"),
    name="openai_agent",
    description="An intelligent mapping assistant that provides driving, walking, and public transportation directions...",
    instruction="When the user asks for routes, travel times, or directions between locations..."

Tool Configuration

This is where we define the integration with the Google Maps MCP Server:

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

This tells the agent to launch the MCP server using npx, making all Google Maps tools available for our Agent.

Observability Callbacks

Finally, we attach Opik tracing callbacks to capture the full agent lifecycle:

before_agent_callback=tracer.before_agent_callback,
after_agent_callback=tracer.after_agent_callback,
before_model_callback=tracer.before_model_callback,
after_model_callback=tracer.after_model_callback,
before_tool_callback=tracer.before_tool_callback,
after_tool_callback=tracer.after_tool_callback,
)

This enables deep visibility into every interaction handled by the agent.

Video Demonstration

Check out the video on YouTube where I walk through the project:

Author

Luis Fernando Torres

License

This project is licensed under the MIT License. See the LICENSE file for details.