How shdhumale/fastmcp-adk-server-client works
Project type and purpose
• This is a minimal full-stack Python client-server demo.
• Purpose: Expose “tools” (ADK agents) via a FastMCP server (server.py) and interact with them via a FastMCP client (client.py).
File structure
• Top-level files:
• server.py – MCP server wrapping ADK agents
• client.py – MCP client to consume server tools
• requirements.txt – Python dependencies (FastMCP, ADK, etc.)
• .env – optional environment configuration (API keys, endpoints)
• No separate “src,” tests, or frontend; it’s a single-service architecture with a client script.
README for additional insights
• FastMCP provides a decorator-based interface to declare tools (endpoints).
• ADK agents supply the intelligent tool logic.
• Interaction flow: client connects → lists tools → invokes tool → server dispatches to ADK agent → returns result.
Main components and interactions
a. Components
1. FastMCP Server (server.py)
– Decorator-defined endpoints/tools
– ADK Agent module/plugin
– HTTP/MCP transport layer (uvicorn or builtin FastMCP server)
– Configuration loader (.env)
2. ADK Agent
– Implements tool logic, session state, event handling
– May call external APIs (e.g., Google services)
3. FastMCP Client (client.py)
– Connects to server over TCP/HTTP
– Discovers available tools
– Sends MCP requests and receives responses
4. Dependency Management
– requirements.txt (FastMCP, ADK, python-dotenv)
– .env for secret/config injection
b. Relationships & Data Flow
1. Client → Server: MCP request (e.g., “invoke tool X”)
2. Server → ADK Agent: Dispatch event to agent
3. ADK Agent → External Services (optional): API calls, data fetch
4. ADK Agent → Server: Return processed result
5. Server → Client: Send MCP response
c. Architectural patterns & design principles
• Separation of concerns: transport (FastMCP) vs. business logic (ADK agent) vs. client interface
• Decorator-based routing for tool registration
• Environment-based configuration for secrets/endpoints
• Single-process minimal footprint
d. Key technologies
• Python 3.10+
• FastMCP (MCP framework)
• Google ADK (agent toolkit)
• python-dotenv (optional)
• uv (optional package manager)
Elements
• Clear labels: “FastMCP Client,” “FastMCP Server,” “ADK Agent,” “External APIs”
• Client → Server (MCP requests)
• Server → Agent (tool invocation)
• Agent → External (optional API calls)
• Agent → Server → Client (response)
• Blue rectangles for code components (client.py, server.py)
• Green for agent logic
• Grey for infrastructure (requirements.txt, .env)
Step-by-step creation
1. Sketch the client on the left: label “FastMCP Client (client.py).”
– Transport Layer (FastMCP HTTP/TCP)
– Tool Registry (decorators in server.py)
– Config (.env loader)