A2A and MCP Integration Patterns

Purpose: Provide integration patterns, configuration examples, and best practices for combining Agent-to-Agent Protocol with Model Context Protocol in multi-agent systems.

Activation Triggers:

• A2A + MCP integration setup

• Hybrid protocol architecture

• Agent-to-agent + agent-to-tool communication

• Composite multi-agent systems

• Protocol compatibility questions

• Cross-protocol authentication

• Combined SDK usage

Protocol Roles:

• A2A Protocol: Agent-to-agent communication and task delegation

• MCP: Agent-to-tool communication and resource access

• Combined: Agents communicate via A2A while accessing tools via MCP

Architecture Overview

Why Combine A2A and MCP?

A2A and MCP are complementary protocols:

• MCP standardizes how agents connect to tools, APIs, and data sources

• A2A standardizes how agents communicate and coordinate with each other

• Together they enable agents to collaborate while accessing shared resources

Integration Patterns

Hierarchical Agent Systems

• Coordinator agent uses A2A to delegate tasks

• Worker agents use MCP to access tools

• Results flow back through A2A

Federated Tool Access

• Multiple agents communicate via A2A

• Each agent has MCP tool access

• Agents share tool results through A2A messages

Resource-Sharing Networks

• Agents discover each other via A2A

• Agents expose MCP servers to each other

• Dynamic tool delegation through agent network

Quick Start

Python Integration

Install both SDKs

./scripts/install-python-integration.sh

Validate installation

./scripts/validate-python-integration.sh

Run example

python examples/python-hybrid-agent.py

TypeScript Integration

Install both SDKs

./scripts/install-typescript-integration.sh

Validate installation

./scripts/validate-typescript-integration.sh

Run example

ts-node examples/typescript-hybrid-agent.ts

Configuration

Environment Setup

Both protocols require environment configuration:

A2A Configuration

A2A_API_KEY=your_a2a_key_here A2A_BASE_URL=https://a2a.example.com

MCP Configuration

MCP_SERVER_URL=http://localhost:3000 MCP_TRANSPORT=stdio

Integration Settings

HYBRID_AGENT_ID=agent-001 HYBRID_AGENT_NAME=hybrid-coordinator ENABLE_A2A=true ENABLE_MCP=true

See templates/env-integration-template.txt for complete configuration.

Authentication

Handle authentication for both protocols:

• Separate Credentials: Each protocol uses its own auth

• Shared Identity: Agent identity spans both protocols

• Token Forwarding: Pass credentials through A2A messages (when appropriate)

See templates/auth-hybrid-template.txt for patterns.

Integration Patterns

Pattern 1: Coordinator-Worker with Shared Tools

Architecture:

• Coordinator agent receives tasks

• Delegates via A2A to worker agents

• Workers use MCP tools to complete tasks

• Results return via A2A

Template: templates/coordinator-worker-pattern.py

Use Case: Complex workflows requiring specialized agents with tool access

Pattern 2: Peer-to-Peer with Tool Sharing

Architecture:

• Agents communicate as peers via A2A

• Each agent exposes MCP server

• Agents can request tools from each other

• Distributed tool access

Template: templates/peer-tool-sharing-pattern.ts

Use Case: Decentralized systems where agents have different capabilities

Pattern 3: Agent Mesh with Centralized Tools

Architecture:

• Agents form A2A communication mesh

• Centralized MCP server provides tools

• All agents access same tool set

• Coordination via A2A, execution via MCP

Template: templates/mesh-centralized-tools-pattern.py

Use Case: Teams of agents working with shared infrastructure

Pattern 4: Layered Protocol Stack

Architecture:

• MCP at base layer for tool access

• A2A at orchestration layer for coordination

• Application logic at top layer

• Clean separation of concerns

Template: templates/layered-stack-pattern.ts

Use Case: Enterprise systems requiring protocol isolation

Scripts

Installation Scripts

• install-python-integration.sh

• Install Python A2A + MCP SDKs

• install-typescript-integration.sh

• Install TypeScript A2A + MCP SDKs

• install-java-integration.sh

• Install Java A2A + MCP SDKs

Validation Scripts

• validate-python-integration.sh

• Verify Python integration setup

• validate-typescript-integration.sh

• Verify TypeScript integration setup

• validate-protocol-compatibility.sh

• Check protocol version compatibility

Setup Scripts

• setup-hybrid-agent.sh

• Initialize hybrid agent environment

• setup-mcp-server.sh

• Configure MCP server for A2A agents

• setup-agent-discovery.sh

• Configure A2A agent discovery with MCP tools

Templates

Configuration Templates

• env-integration-template.txt

• Environment variables for both protocols

• auth-hybrid-template.txt

• Authentication configuration

• agent-config-hybrid.json

• Agent configuration with A2A+MCP

Code Templates

Python:

• coordinator-worker-pattern.py

• Coordinator-worker implementation

• mesh-centralized-tools-pattern.py

• Agent mesh with central MCP

• python-hybrid-agent.py

• Basic hybrid agent

TypeScript:

• peer-tool-sharing-pattern.ts

• Peer-to-peer tool sharing

• layered-stack-pattern.ts

• Layered protocol architecture

• typescript-hybrid-agent.ts

• Basic hybrid agent

Java:

• java-hybrid-agent.java

• Basic Java integration

• java-coordinator-pattern.java

• Coordinator pattern in Java

Configuration:

• mcp-server-config.json

• MCP server configuration for A2A agents

• a2a-agent-card.json

• Agent card with MCP tool references

Common Integration Scenarios

Scenario 1: Multi-Agent Data Pipeline

Problem: Multiple agents process data through different tools

Solution:

• Coordinator receives request via A2A

• Delegates to specialized agents (data-fetcher, data-processor, data-storage)

• Each agent uses MCP tools for its domain

• Results aggregate via A2A back to coordinator

Example: examples/data-pipeline-integration.py

Scenario 2: Distributed Research Assistant

Problem: Research task requires web search, document analysis, and synthesis

Solution:

• Agents communicate via A2A to coordinate

• Search agent uses MCP web search tools

• Analysis agent uses MCP document processing tools

• Synthesis agent combines results using MCP output tools

Example: examples/research-assistant-integration.ts

Scenario 3: Microservice-Style Agent Architecture

Problem: Need modular, scalable agent system

Solution:

• Each agent is a microservice with A2A interface

• Agents use MCP to access shared databases, APIs

• Service discovery via A2A agent cards

• Load balancing across agent instances

Example: examples/microservice-agents.py

Error Handling

Protocol-Specific Errors

Handle errors from both protocols:

from a2a import A2AError from mcp import MCPError

try: # A2A communication response = await a2a_client.send_task(task)

# MCP tool execution
result = await mcp_client.call_tool("search", params)

except A2AError as e: # Handle A2A communication errors logger.error(f"A2A error: {e}")

except MCPError as e: # Handle MCP tool errors logger.error(f"MCP error: {e}")

See examples/error-handling-integration.py for complete patterns.

Connection Failures

Both protocols may fail independently:

• A2A failure, MCP working: Agent can execute local tools

• MCP failure, A2A working: Agent can delegate to others

• Both failing: Implement fallback logic

See templates/failover-pattern.py for resilience patterns.

Security Considerations

Authentication Boundaries

Separate Auth Per Protocol:

• A2A credentials for agent communication

• MCP credentials for tool access

• Never share credentials across protocols

Message Security

A2A Messages:

• End-to-end encryption between agents

• Signature verification for agent identity

• Do not include MCP credentials in A2A messages

MCP Communication:

• Secure tool access with proper authentication

• Validate tool responses before sharing via A2A

• Sandbox tool execution

Network Security

Hybrid Deployment:

• A2A may be internet-facing for agent discovery

• MCP should be internal for tool security

• Use VPN/private networks for MCP traffic

• Implement network segmentation

See examples/security-best-practices.md for detailed guidance.

Performance Optimization

Protocol Selection

Choose the right protocol for each interaction:

Use A2A when:

• Delegating tasks to other agents

• Coordinating multi-agent workflows

• Sharing results between agents

Use MCP when:

• Accessing tools and APIs

• Reading/writing data sources

• Executing specialized functions

Connection Pooling

Both protocols benefit from connection pooling:

A2A connection pool

a2a_pool = A2AConnectionPool( max_connections=10, timeout=30 )

MCP connection pool

mcp_pool = MCPConnectionPool( max_connections=5, timeout=15 )

See templates/connection-pooling.py for implementation.

Caching Strategies

Agent Discovery Caching:

• Cache A2A agent cards (refresh periodically)

• Cache MCP tool schemas

• Invalidate on protocol updates

Result Caching:

• Cache expensive MCP tool results

• Share cache across A2A agent network

• Implement cache coherence protocol

Testing

Integration Tests

Test both protocols together:

Run integration test suite

./scripts/test-integration.sh

Test specific pattern

./scripts/test-pattern.sh coordinator-worker

Test protocol compatibility

./scripts/test-protocol-versions.sh

Mock Servers

Use mock servers for development:

Start mock A2A server

./scripts/start-mock-a2a.sh

Start mock MCP server

./scripts/start-mock-mcp.sh

Run tests against mocks

./scripts/test-with-mocks.sh

Examples

Complete working examples:

Python:

• python-hybrid-agent.py

• Basic hybrid agent

• data-pipeline-integration.py

• Multi-agent data pipeline

• microservice-agents.py

• Microservice architecture

• error-handling-integration.py

• Error handling patterns

TypeScript:

• typescript-hybrid-agent.ts

• Basic hybrid agent

• research-assistant-integration.ts

• Distributed research

• peer-coordination.ts

• Peer-to-peer coordination

Configuration:

• docker-compose-integration.yml

• Docker setup for hybrid system

• kubernetes-hybrid-agents.yaml

• Kubernetes deployment

Documentation:

• security-best-practices.md

• Security guidelines

• troubleshooting-integration.md

• Common issues and solutions

• architecture-patterns.md

• Detailed architecture patterns

Troubleshooting

Common Issues

Protocol Version Mismatch:

Check versions

./scripts/validate-protocol-compatibility.sh

Upgrade if needed

pip install --upgrade a2a-protocol mcp-sdk

Authentication Errors:

Verify both protocol credentials

echo $A2A_API_KEY echo $MCP_SERVER_URL

Test separately

python -c "from a2a import Client; Client().ping()" python -c "from mcp import Client; Client().ping()"

Connection Issues:

• Check A2A agent is reachable

• Verify MCP server is running

• Test network connectivity separately

• Review firewall rules

See examples/troubleshooting-integration.md for detailed solutions.

Resources

Official Documentation:

• A2A Protocol: https://a2a-protocol.org

• MCP: https://modelcontextprotocol.io

• Integration Guide: https://docs.a2a-protocol.org/mcp-integration

GitHub Repositories:

• A2A+MCP Examples: https://github.com/a2a/mcp-integration-examples

• Python Integration: https://github.com/a2a/python-mcp-integration

• TypeScript Integration: https://github.com/a2a/typescript-mcp-integration

Community:

• A2A Discord: https://discord.gg/a2a-protocol

• MCP Discussion: https://github.com/modelcontextprotocol/specification/discussions

• Integration Patterns: https://community.a2a-protocol.org/integrations

Version: 1.0.0 A2A Protocol Compatibility: 1.0+ MCP Compatibility: 1.0+ Last Updated: 2025-12-20