How tsadoq/a2a-mcp-tutorial works
Project type and purpose
• This is not a traditional web app but a distributed, microservice-style agent pipeline.
• It uses two complementary open protocols:
– Agent2Agent (A2A) for peer-to-peer agent coordination
– Model Context Protocol (MCP) for tool/resource access by agents
• It’s structured as a set of Python services: MCP servers, A2A servers (host + sub-agents), and helper libraries.
File structure
Top-level dirs & their roles:
• a2a_servers/agent_servers: three A2A HTTP servers (host_agent, google_search_agent, stock_report_agent)
• a2a_servers/agents: ADKAgent implementation bridging ADK → A2A
• a2a_servers/common: shared A2A client/server, task manager, types, utils
• a2a_servers/hosts/cli: a CLI client for local testing
• mcp_server: two MCP servers—stdio transport and SSE transport—for search & stocks
• services/search_engine_service & services/stocks_service: wrappers around Serper.dev & Finnhub APIs
• adk_agents_testing: scripts to spin up MCP clients and test pipelines
Key README insights
• Two MCP servers (crawler = SerperDevService, stock retriever = FinHubService), each exposed over STDIO or SSE
• An ADK “Runner” that spawns an LlmAgent (root + sub-agents) and wires in MCP tools
• A hierarchical ADK crew and a peer-to-peer A2A crew, each running as standalone HTTP servers
• Starlette/Uvicorn used to host MCP SSE servers and A2A servers
Components
A. User / CLI Client
– Represents host_cli or any local client in a2a_servers/hosts/cli
B. Host Agent (A2A HTTP Server)
– Exposes /.well-known/agent.json and /host_agent endpoint
– Coordinates tasks, holds AgentCard for sub-agents
C. Sub-Agents (A2A HTTP Servers)
– google_search_agent and stock_report_agent
– Each exposes its own AgentCard and /<agent> endpoint
D. Agent Library Layers
– a2a_servers/common: A2A Request/Response types, TaskManager, RemoteAgentConnection
– a2a_servers/agents/adk_agent.py: ADKAgent adapter bridging LLM + tools → A2A protocol
E. Runner / Session / Artifact Services
– InMemorySessionService, InMemoryArtifactService, Runner in README
F. MCP Tool Servers
– search_server.py (stdio & SSE transports)
– stocks_server.py (stdio & SSE transports)
G. External Services
– Serper.dev (Google Search + scraper)
– Finnhub (stock data)
Relationships & Interactions
• User → CLI → Host Agent: HTTP POST tasks/sendSubscribe
• Host Agent ↔ Sub-Agents: A2A JSON-RPC over HTTP, tasks delegation
• Agents → MCP Servers:
– STDIO: subprocess stdin/stdout JSON-RPC
– SSE: HTTP POST to /sse and Server-Sent Events on /messages/
• MCP Servers → External APIs: REST calls to Serper.dev or Finnhub
• Responses flow back up the chain, with each layer enriching context/artifacts
Architectural patterns & design principles
• Microservices: each agent and MCP server is its own deployable service
• Protocol layering: A2A on top of HTTP/JSON-RPC, MCP on top of STDIO or SSE
• Separation of concerns:
– Agents focus on LLM orchestration & delegation
– MCP servers focus on tool abstraction
– services/* focus on external API integration
• Async I/O everywhere (asyncio, Starlette, Uvicorn)