orcaqubits/a2a-mcp-bridge

A2A + MCP Bridge

Before writing code

Fetch live docs:

1. Fetch https://a2a-protocol.org/latest/specification/ for the A2A protocol details
2. Web-search a2a mcp integration bridge agent tool for patterns combining the two protocols
3. Web-search site:github.com a2aproject A2A MCP for any official A2A-MCP integration examples
4. Web-search site:modelcontextprotocol.io specification for the latest MCP specification

Conceptual Architecture

A2A vs MCP — Complementary Protocols

| Aspect | A2A | MCP | |--------|-----|-----| | Purpose | Agent-to-agent delegation | Agent-to-tool/data access | | Participants | Agents (opaque, autonomous) | Agent + tool server (transparent) | | Communication | Tasks with messages | Tool calls with structured I/O | | State | Long-lived tasks with lifecycle | Stateless tool invocations | | Discovery | Agent Cards | Server manifests | | Transport | JSON-RPC over HTTP | JSON-RPC over stdio/HTTP+SSE |

Why Bridge Them

Real-world multi-agent systems need both:

• A2A for delegating complex, open-ended work to other agents
• MCP for accessing specific tools, databases, APIs, and data sources

Bridging patterns enable agents to participate in both ecosystems.

Bridge Patterns

Pattern 1: A2A Agent Wrapping MCP Tools

An A2A agent that internally uses MCP tools to fulfill tasks.

Client Agent → (A2A) → Bridge Agent → (MCP) → Tool Server

• Client sends a task via A2A
• Bridge agent interprets the task
• Bridge agent calls MCP tools to gather data/perform actions
• Bridge agent composes the result and returns via A2A

Pattern 2: MCP Tool Wrapping an A2A Agent

An MCP tool that delegates work to an A2A agent.

Agent → (MCP tool call) → MCP Server → (A2A) → Specialist Agent

• Agent calls an MCP tool
• MCP server sends a task to a specialist A2A agent
• A2A agent processes and returns
• MCP server returns the result as tool output

Pattern 3: Hybrid Orchestrator

A coordinator agent that uses both A2A and MCP:

Orchestrator Agent
  ├── (A2A) → Research Agent
  ├── (A2A) → Writing Agent
  ├── (MCP) → Database Tool
  └── (MCP) → Search Tool

Implementation Considerations

A2A agent using MCP tools:

• The agent's handler connects to MCP servers as part of its processing
• MCP tool calls happen inside the working state
• Results from MCP tools inform the A2A task response
• The A2A client doesn't know or care that MCP is used internally

MCP tool wrapping A2A agent:

• MCP tool definition describes what the A2A agent can do
• Tool handler creates an A2A task, waits for completion
• Map A2A task failures to MCP tool errors
• Handle A2A multi-turn by either auto-responding or failing with a message

State mapping:

• A2A tasks are long-lived; MCP tool calls are short-lived
• For synchronous MCP tools wrapping A2A, block until the A2A task completes
• For async scenarios, consider returning a task ID and providing a status-check tool

Architecture Guidelines

• Keep the bridge layer thin — don't add unnecessary abstraction
• Clearly document which protocol each component uses
• Handle timeout mismatches (MCP tools typically expect fast responses; A2A tasks can be long)
• Map error codes between protocols appropriately
• Log cross-protocol calls for debugging

Best Practices

• Use A2A for delegation to autonomous agents, MCP for accessing deterministic tools
• Don't wrap simple tool calls as A2A agents — use MCP directly
• Don't use MCP for complex, multi-turn agent interactions — use A2A
• Consider the latency implications of cross-protocol bridges
• Test the bridge with realistic payloads and error scenarios
• Document the agent topology so developers understand the flow

Fetch the latest A2A specification and MCP specification for current schemas and integration guidance before implementing bridges.