# bhancockio/adk-mcp-tutorial architecture

> Architecture diagram of the GitHub repository bhancockio/adk-mcp-tutorial, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bhancockio/adk-mcp-tutorial
- Repository: https://github.com/bhancockio/adk-mcp-tutorial

## Overview

This repository demonstrates ADK agents using MCP tools to answer requests: the main workflow connects a user to a Gemini-backed agent, which starts a local stdio MCP server to inspect or modify SQLite data. Separate examples show a Notion-focused remote MCP agent and a comparison between MCP-connected and traditional agents. The README documents local database tools and broader integrations; the supplied excerpts show local server dispatch and agent configuration, but not the remote server implementations or full ADK runtime behavior.

Main entry points: [`local_mcp/agent.py`](https://github.com/bhancockio/adk-mcp-tutorial/blob/main/local_mcp/agent.py) (Database agent), [`remote_mcp_agent/agent.py`](https://github.com/bhancockio/adk-mcp-tutorial/blob/main/remote_mcp_agent/agent.py) (Notion agent), [`demo_comparison/mcp_agent.py`](https://github.com/bhancockio/adk-mcp-tutorial/blob/main/demo_comparison/mcp_agent.py) (Multi-server MCP agent), [`demo_comparison/traditional_agent.py`](https://github.com/bhancockio/adk-mcp-tutorial/blob/main/demo_comparison/traditional_agent.py) (Traditional agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_local["Local database workflow"]
  node_local_agent["Database agent<br/>[agent.py]"]
  node_local_prompt["Database instructions<br/>[prompt.py]"]
  node_local_mcp_server["Local MCP server<br/>[server.py]"]
  node_database_tools["Database tools<br/>[server.py]"]
  node_sqlite[("SQLite database<br/>[database.db]")]
end

subgraph group_remote["Remote MCP example"]
  node_remote_agent["Notion agent<br/>[agent.py]"]
  node_notion_prompt["Notion instructions<br/>[prompt.py]"]
  node_notion_server{{"Notion MCP server"}}
end

subgraph group_demos["Agent comparisons"]
  node_mcp_demo["Multi-server MCP agent<br/>[mcp_agent.py]"]
  node_traditional_demo["Traditional agent"]
  node_other_mcp_servers{{"External MCP servers"}}
  node_traditional_tools["Sample tools"]
end

node_user(("User"))
node_gemini{{"Gemini model"}}
node_notion_service{{"Notion service"}}

node_user -->|"requests"| node_local_agent
node_local_agent -->|"uses instructions"| node_local_prompt
node_local_agent -->|"prompts"| node_gemini
node_local_agent -->|"connects over stdio"| node_local_mcp_server
node_local_mcp_server -->|"dispatches tools"| node_database_tools
node_database_tools -->|"reads and writes"| node_sqlite
node_user -->|"requests"| node_remote_agent
node_remote_agent -->|"uses instructions"| node_notion_prompt
node_remote_agent -->|"prompts"| node_gemini
node_remote_agent -->|"connects via MCP"| node_notion_server
node_notion_server -.->|"accesses"| node_notion_service
node_user -->|"requests"| node_mcp_demo
node_mcp_demo -->|"prompts"| node_gemini
node_mcp_demo -.->|"connects via stdio"| node_other_mcp_servers
node_user -->|"requests"| node_traditional_demo
node_traditional_demo -->|"prompts"| node_gemini
node_traditional_demo -->|"invokes tools"| node_traditional_tools

click node_local_agent "https://github.com/bhancockio/adk-mcp-tutorial/blob/main/local_mcp/agent.py"
click node_local_prompt "https://github.com/bhancockio/adk-mcp-tutorial/blob/main/local_mcp/prompt.py"
click node_local_mcp_server "https://github.com/bhancockio/adk-mcp-tutorial/blob/main/local_mcp/server.py"
click node_database_tools "https://github.com/bhancockio/adk-mcp-tutorial/blob/main/local_mcp/server.py"
click node_sqlite "https://github.com/bhancockio/adk-mcp-tutorial/blob/main/local_mcp/database.db"
click node_remote_agent "https://github.com/bhancockio/adk-mcp-tutorial/blob/main/remote_mcp_agent/agent.py"
click node_notion_prompt "https://github.com/bhancockio/adk-mcp-tutorial/blob/main/remote_mcp_agent/prompt.py"
click node_mcp_demo "https://github.com/bhancockio/adk-mcp-tutorial/blob/main/demo_comparison/mcp_agent.py"
click node_traditional_demo "https://github.com/bhancockio/adk-mcp-tutorial/blob/main/demo_comparison/traditional_agent.py"
click node_traditional_tools "https://github.com/bhancockio/adk-mcp-tutorial/blob/main/demo_comparison/traditional_agent.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_local_agent,node_local_prompt,node_local_mcp_server,node_database_tools,node_sqlite,node_user toneBlue
class node_remote_agent,node_notion_prompt,node_notion_server toneAmber
class node_mcp_demo,node_traditional_demo,node_other_mcp_servers,node_traditional_tools toneMint
class node_gemini,node_notion_service toneIndigo
```

## Components

### Local database workflow

- [Database agent](https://github.com/bhancockio/adk-mcp-tutorial/blob/main/local_mcp/agent.py): `local_mcp/agent.py`
- [Database instructions](https://github.com/bhancockio/adk-mcp-tutorial/blob/main/local_mcp/prompt.py): `local_mcp/prompt.py`
- [Local MCP server](https://github.com/bhancockio/adk-mcp-tutorial/blob/main/local_mcp/server.py): `local_mcp/server.py`
- [Database tools](https://github.com/bhancockio/adk-mcp-tutorial/blob/main/local_mcp/server.py): `local_mcp/server.py`
- [SQLite database](https://github.com/bhancockio/adk-mcp-tutorial/blob/main/local_mcp/database.db): `local_mcp/database.db`

### Remote MCP example

- [Notion agent](https://github.com/bhancockio/adk-mcp-tutorial/blob/main/remote_mcp_agent/agent.py): `remote_mcp_agent/agent.py`
- [Notion instructions](https://github.com/bhancockio/adk-mcp-tutorial/blob/main/remote_mcp_agent/prompt.py): `remote_mcp_agent/prompt.py`
- **Notion MCP server**

### Agent comparisons

- [Multi-server MCP agent](https://github.com/bhancockio/adk-mcp-tutorial/blob/main/demo_comparison/mcp_agent.py): `demo_comparison/mcp_agent.py`
- [Traditional agent](https://github.com/bhancockio/adk-mcp-tutorial/blob/main/demo_comparison/traditional_agent.py): `demo_comparison/traditional_agent.py`
- **External MCP servers**
- [Sample tools](https://github.com/bhancockio/adk-mcp-tutorial/blob/main/demo_comparison/traditional_agent.py): `demo_comparison/traditional_agent.py`

### Other components

- **User**
- **Gemini model**
- **Notion service**

## Connections

- User → Database agent: requests
- Database agent → Database instructions: uses instructions
- Database agent → Gemini model: prompts
- Database agent → Local MCP server: connects over stdio
- Local MCP server → Database tools: dispatches tools
- Database tools → SQLite database: reads and writes
- User → Notion agent: requests
- Notion agent → Notion instructions: uses instructions
- Notion agent → Gemini model: prompts
- Notion agent → Notion MCP server: connects via MCP
- Notion MCP server → Notion service: accesses
- User → Multi-server MCP agent: requests
- Multi-server MCP agent → Gemini model: prompts
- Multi-server MCP agent → External MCP servers: connects via stdio
- User → Traditional agent: requests
- Traditional agent → Gemini model: prompts
- Traditional agent → Sample tools: invokes tools