ADK Agent MCP服务器连接器

ADK Agent with MCP Servers

Two examples of connecting a Google Agent Development Kit (ADK) agent to Model Context Protocol (MCP) servers:

Both agents use gemini-3.8-flash.

Prerequisites

• Python 3.12 (the version this project was tested with). Python 3.14 failed to install on an Intel Mac, because cryptography has no prebuilt package for it there.
• A Gemini API key
• For the Notion example: Node.js (for npx) and a Notion integration token with access to the pages you want the agent to use

Setup

1. Create and activate a virtual environment, then install the dependencies.

   复制

   python3.12 -m venv .venv
   source .venv/bin/activate
   pip install --only-binary cryptography google-adk "mcp<2" python-dotenv
   

   Two details in the install command matter:

   • "mcp<2": local_mcp/server.py uses the @app.list_tools() and @app.call_tool() decorators from the MCP Python SDK 1.x. They were removed in 2.x, and with 2.x the server crashes at startup ('Server' object has no attribute 'list_tools').
   • --only-binary cryptography: makes pip use a prebuilt cryptography package. Without it, pip may try to compile cryptography from source and fail if your Rust compiler is too old.

2. Copy the example environment file and fill in your keys.

   复制

   cp .env.example .env
   

   Variable	Used by
   GOOGLE_API_KEY	Both agents (Gemini)
   NOTION_API_KEY	The Notion agent

Quick start: run the server, pick an agent, ask questions

1. Activate the virtual environment from the project root. The agents start their MCP server with the python3 on your path, so the environment must be active.

   复制

   source .venv/bin/activate
   

2. Start the ADK web server from the project root, not from inside an agent folder.

   复制

   adk web
   

   It prints http://127.0.0.1:8000. Leave this terminal open, because agent errors are printed here.

3. Open the URL in your browser and choose an agent from the dropdown at the top left:

   • local_mcp: questions about the sample SQLite database
   • remote_mcp: questions about your Notion workspace

4. Ask questions in the chat box. For local_mcp, start with "What tables are in the database?". The chat shows each tool call the agent makes and then its answer.

5. Stop the server with Ctrl+C in the terminal. Restart it after any change to the agent files, because they are loaded at startup.

If something goes wrong, see Troubleshooting.

Example 1: Notion MCP server

How it works

The ADK agent never calls the Notion API itself. It talks to Notion's MCP server, which turns tool calls into Notion API requests:

1. remote_mcp/agent.py reads NOTION_API_KEY from the environment and fails with NOTION_API_KEY is not set if it is missing.
2. The agent's MCPToolset starts the Notion MCP server as a subprocess with npx -y @notionhq/notion-mcp-server and passes it the key as NOTION_TOKEN. The first run downloads the package, so it can be slow.
3. The agent asks the server which tools it has. The server exposes the Notion API as tools, such as querying a database, inserting a block, writing a comment and creating a page.
4. When you ask a question, Gemini decides which Notion tools to call. The server runs them against the Notion API and returns the results, and Gemini writes the answer from them.
5. The agent's instructions in remote_mcp/prompt.py tell it to act without asking for confirmation when it already has what it needs, such as a page ID from an earlier step.

With the Notion tools, the agent can create documentation, search the workspace and answer questions from its content, manage tasks, generate code snippets from a task description, and build reports, release notes and project updates from several pages.

Give the agent access to your Notion content

A Notion integration can only see the pages and databases that have been shared with it.

1. Create an integration at notion.so/profile/integrations and copy its token into .env as NOTION_API_KEY.
2. Share the content you want the agent to use. Open the page or database, click ··· → Connections, and add your integration.

In the tested setup, the content is a To-Do list database in Notion, connected to an integration named ellieMCP.

Run it

From the project root, with the virtual environment active:

adk web

Open the URL that adk web prints, select remote_mcp as the agent, and ask questions about the shared content. Restart adk web after you change .env, because the file is read at startup.

Prompts to try with a To-Do list database:

• "Search my Notion workspace for my To-Do list."
• "What tasks are left to do on my To-Do list?"
• "Add a to-do called 'Test MCP agent' to my To-Do list."

Start with read-only questions. The agent can change your real Notion content, so test changes on a copy of the database.

Tested

Asking the agent which to-do items are left worked. It found the To-Do list database and returned the open items, which confirms that the agent, the Notion MCP server and the integration are connected.

Asking it to add an item failed with a quota-exceeded error. A request that adds an item takes several model calls (find the database, then insert), and the Gemini free tier limits how many requests you can send. The error is a model quota limit, not a Notion problem. It should go away with a paid tier, or after waiting for the quota to reset. Adding items hasn't been confirmed to work.

Example 2: Local SQLite MCP server

The agent in local_mcp/agent.py talks to a custom MCP server that wraps a SQLite database.

Files

Tools exposed by the server

Run it

1. Create the database. This is only needed once. The script does nothing if database.db already exists.

   复制

   python3 local_mcp/create_db.py
   

2. From the project root, with the virtual environment active, start the ADK web UI.

   复制

   adk web
   

3. Open the URL that adk web prints and select local_mcp as the agent. Try prompts such as:

   • "What tables are in the database?"
   • "Show me all of Elliot's unfinished todos."
   • "Add a todo for Mike: book flights."
   • "Delete the todo about running."

You don't start the MCP server yourself. When the agent initializes its MCPToolset, it runs python3 local_mcp/server.py. The server then listens for tool calls from the agent over stdio. To run the server by hand, for example to debug it, use python3 local_mcp/server.py from the project root.

Logs

The server writes its activity to local_mcp/mcp_server_activity.log, and the file is overwritten on each start. Nothing is printed to the console. To see the log output there, add a logging.StreamHandler() to the handlers in server.py.

Troubleshooting

To see which models your key can use:

python3 -c "
from dotenv import load_dotenv; load_dotenv()
from google import genai
client = genai.Client()
for m in client.models.list():
    if 'generateContent' in (m.supported_actions or []): print(m.name)
"

Keep the client in a variable as shown. A temporary genai.Client() is closed before the loop finishes.

Project structure

mcp-adk/
├── local_mcp/
│   ├── agent.py          # ADK agent for the SQLite example
│   ├── create_db.py      # builds database.db with sample data
│   ├── database.db       # SQLite database
│   ├── prompt.py         # agent instructions
│   └── server.py         # custom MCP server (stdio)
├── remote_mcp/
│   ├── agent.py          # ADK agent for the Notion example
│   └── prompt.py         # agent instructions
├── .env.example          # template for API keys
└── requirements.txt

Notes

• The database tools build SQL from the values the model passes in, such as table names and WHERE conditions. Use them on a local sample database only, not on data you care about.
• requirements.txt is currently empty. Install the packages with the command in Setup.
• Both agents have been run. local_mcp works against the sample database. remote_mcp can read a Notion To-Do list database. Adding items hasn't been tested, because the Gemini free tier ran out of quota.