How to Connect Google ADK to Heurist MCP in Minutes
What is Google ADK?
Google’s Agent Development Kit (ADK) is an open-source Python framework that helps developers build task-oriented agents on top of Gemini models without wrestling with prompt orchestration, tool registration, or conversation state.
It ships with a declarative @agent.command syntax, built-in session and artifact stores, streaming event handling, and pluggable toolsets, so an agent can move from chat UI to scheduled batch job with only a few lines of code. ADK focuses on agent logic, letting you swap in different LLM back-ends or deployment targets while keeping the application layer unchanged, perfectly aligning with the moludar design of Heurist Agent Framework
Why MCP (Model Context Protocol)
Developers love ADK because it abstracts tools and state management. Agent developers want real‑world data and plugins that allow agents to interact with the world, but you often hit a swamp of bespoke APIs and auth flows. The industry’s first attempt to fix that was Function Calling, useful yet not scalable. MCP provides a standardized, scalable alternative.
Function Calling simply doesn’t scale, and here’s why:
Imagine integrating just 2 agents (like Google ADK Agent and LangChain Agent) with 3 tools (such as Zapier, Notion, and Slack). You’re quickly buried under the complexity of unique integration code for each combination — it’s exponential glue, endless rewrites, and inevitable headaches.
That’s precisely the “M×N problem”: every new agent-tool pair demands a fresh integration. MCP fixes this by standardizing the communication between agents and tools. Build once per side — agents or tools — and plug them into each other effortlessly. This reduces your complexity from M×N to just M+N.
Less glue. More scale. Ship faster.
That’s why MCP is building momentum!
Meet Heurist MCP
Heurist MCP is a high-performance implementation of the Model Context Protocol server designed for agent–tool integration. It powers communication between large language model agents (like those built with Google ADK) and external services like CoinGecko, Bitquery, Firecrawl, Exa Search, Twitter, Truth Social to standardize how agents exchange data in both web2 and web3 domains.
Heurist Mesh, the agents-as-a-service cloud platform behind Heurist MCP lets you use MCP service easily. No need to wrap APIs or set up a local server manually. We provide fully-managed, on-demand servers for a growing swarm of 25+ specialized agents and 50+ tools are ready to use.
For a full list of available agents and to create your own MCP server, visit Heurist MCP Portal.
By default, Heurist MCP communicates over Server-Sent Events (SSE), which allows for real-time streaming responses from tools. You can connect your own agent by simply pointing ADK to an SSE endpoint with a few lines of code.
Quick-Start (10 Minutes)
Prerequisites
You’ll need:
- Python 3.8+
- UV package manager
- A Heurist MCP endpoint from mcp.heurist.ai
- Google Sheets service account (for writing data to Google Sheets)
- Gemini API key from AI Studio
Installation
Start by forking the this repository, then:
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -r requirements.txtCreate an .env file with your credentials:
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=PASTE_YOUR_ACTUAL_API_KEY_HERE
HEURIST_MESH_MCP_URL=your_mesh_mcp_url_here
UVX_PATH=path_to_uvx_executable
# Google Sheets API Authentication
SERVICE_ACCOUNT_PATH=path_to_your_service_account_json_file
DRIVE_FOLDER_ID=your_google_drive_folder_idConnect to MCP
Let’s connect Google ADK to both Heurist Mesh tools and Google Sheets to demonstrate the cross-platform features of MCP.
First, let’s establish the MCP connections. The code follows a simple pattern:
For Heurist MCP, use SseServerParams
For Google Sheet MCP, use StdioServerParameters.
# Connecting to the Heurist Mesh Agent Tool (via MCP - SSE)
tools_mesh, stack_mesh = await MCPToolset.from_server(
connection_params=SseServerParams(url=os.environ["HEURIST_MESH_MCP_URL"])
)
# Connecting to Sheets Tool (via MCP - stdio)
tools_sheets, stack_sheets = await MCPToolset.from_server(
connection_params=StdioServerParameters(
command=os.environ["UVX_PATH"],
args=["run", os.environ["SHEETS_TOOL_PATH"]],
env={
"SERVICE_ACCOUNT_PATH": os.environ["SERVICE_ACCOUNT_PATH"],
"DRIVE_FOLDER_ID": os.environ["DRIVE_FOLDER_ID"],
},
)
)Instantiate an agent with ADK
Once connected, creating your agent with a declarative pattern:
agent = LlmAgent(
model=os.environ["GEMINI_MODEL"],
name="adk_agent_heurist_mcp_data_pipeline",
instruction="""
You are an expert in data analysis. Use provided MCP tools to fetch external data and write it to Google Sheets.
""",
tools=[*tools_mesh, *tools_sheets],
session_service=InMemorySessionService(),
generate_content_config=types.GenerateContentConfig(maxOutputTokens=500_000),
)It’s recommended to include phrases like “Use MCP tools” in the instruction so that the agent always uses provided tools and avoids hallucination.
Execute the user query via ADK Runner
session_service = InMemorySessionService()
runner = Runner(
app_name="adk_agent_heurist_mcp_data_pipeline",
agent=agent,
session_service=session_service
)
async def process_query(query):
content = types.Content(role='user', parts=[types.Part(text=query)])
return await runner.run_async(
session_id="session_123",
user_id="user_123",
new_message=content
)Putting Everything Together
The complete code sample brings everything together:
import os, asyncio
from dotenv import load_dotenv
from google.adk.agents import LlmAgent
from google.adk.sessions import InMemorySessionService
from google.adk.runners import Runner
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset, SseServerParams, StdioServerParameters
from google.genai import types
load_dotenv(override=True)
async def main():
tools_mesh, stack_mesh = await MCPToolset.from_server(
connection_params=SseServerParams(url=os.environ["HEURIST_MESH_MCP_URL"])
)
tools_sheets, stack_sheets = await MCPToolset.from_server(
connection_params=StdioServerParameters(
command=os.environ["UVX_PATH"],
args=["run", os.environ["SHEETS_TOOL_PATH"]],
env={
"SERVICE_ACCOUNT_PATH": os.environ["SERVICE_ACCOUNT_PATH"],
"DRIVE_FOLDER_ID": os.environ["DRIVE_FOLDER_ID"]
},
)
)
agent = LlmAgent(
model=os.environ["GEMINI_MODEL"],
name="adk_agent_heurist_mcp_data_pipeline",
instruction="You are an expert in data analysis. Use provided MCP tools to fetch external data and write it to Google Sheets.",
tools=[*tools_mesh, *tools_sheets],
session_service=InMemorySessionService(),
generate_content_config=types.GenerateContentConfig(maxOutputTokens=500_000)
)
runner = Runner(app_name="adk_agent_heurist_mcp_data_pipeline", agent=agent, session_service=InMemorySessionService())
async with stack_mesh, stack_sheets:
query = input("Enter your data request: ")
result = await runner.run_async("session_123", "user_123", types.Content(role='user', parts=[types.Part(text=query)]))
print(result)
if __name__ == "__main__":
asyncio.run(main())Run the agent
Launch your agent with:
python workflow_agent.pyExample 1: Social Media Data Collection
Let’s track Elon Musk’s Twitter activity. Type this query:
Get @elonmusk’s latest 10 tweets and store timestamp + text in a new spreadsheet “elonmusk‑tweets‑2025‑04‑21”, sheet “elonmusk”.
The agent springs into action, making several MCP calls like create_spreadsheet, create_sheet , twitterprofileagent_get_user_tweets, and update_cellsin sequence:
Assistant: Processing your request…
create_spreadsheet(title="elonmusk-tweets-2025-04-21") ✓
create_sheet(title="elonmusk") ✓
update_cells(range="A1:B1", values=["timestamp","text"]) ✓
twitterprofileagent_get_user_tweets(username="elonmusk", limit=10) ✓
update_cells(range="A2:B11", values=[10 rows]) ✓
✅ 10 tweets saved to elonmusk-tweets-2025-04-21 › elonmuskThe agent session-log is saved after run completes.
Within seconds, you’ve got a structured Google Sheet with the latest tweets, ready for analysis.
Example 2: Crypto Market Intelligence
Want to query funding rates on tokens and save to Google Sheet? Ask:
Start by searching for top 10 tokens that have the highest positive funding rates across major exchanges. For each token, collect the following: Token symbol, Current price (USD), highest positive funding rate, and exchange name with the highest positive funding rate. Display the rates in percentage. Get the token info and price related data from tools like Dexscreener. Save the results to a Google Spreadsheet named “Funding Rate Dashboard”, under the sheet titled “Trending Funding Rates”. You don’t need to ask for confirmation. Complete the task using available tools.
The agent handles the entire workflow:
Assistant: Processing your request...
# Tool calls (abridged)
list_spreadsheets() ✓
list_sheets() ✓
create_sheet(title="Trending Funding Rates") ✓
fundingrateagent_get_all_funding_rates() ✓
dexscreenertokeninfoagent_search_pairs() ✓ # Called multiple times for different tokens
get_sheet_data(range="1:1") ✓
update_cells(range="A1:D1", data=[…]) ✓ # Write header
update_cells(range="A2:D11", data=[…]) ✓ # Write data
✅ Data written to Fundingr Rate Dashboard › Trending Funding RatesJust like that, you the top-10 tokens with highest funding rates saved to Google Sheet and updatable with a simgle command!
From Prompt to Production
With the standard protocol, you’ve connected Google ADK to the real world. Your agent now uses Heurist MCP and fetches live crypto data, scans social platforms, and writes structured outputs to Google Sheets all from a simple user prompt.
Ready to scale your next AI agent beyond chatbots? You already have the blueprint.
