Integration patterns for combining Agent-to-Agent (A2A) Protocol with Model Context Protocol (MCP) for hybrid agent communication. Use when building systems that need both agent-to-agent communication and agent-to-tool integration, implementing composite architectures, or when user mentions A2A+MCP integration, hybrid protocols, or multi-agent tool access.
This skill is limited to using the following tools:
examples/architecture-patterns.mdexamples/data-pipeline-integration.pyexamples/python-hybrid-agent.pyexamples/security-best-practices.mdexamples/troubleshooting-integration.mdexamples/typescript-hybrid-agent.tsscripts/install-python-integration.shscripts/install-typescript-integration.shscripts/setup-hybrid-agent.shscripts/validate-protocol-compatibility.shscripts/validate-python-integration.shscripts/validate-typescript-integration.shtemplates/auth-hybrid-template.txttemplates/coordinator-worker-pattern.pytemplates/env-integration-template.txttemplates/layered-stack-pattern.tstemplates/mesh-centralized-tools-pattern.pytemplates/peer-tool-sharing-pattern.tsPurpose: Provide integration patterns, configuration examples, and best practices for combining Agent-to-Agent Protocol with Model Context Protocol in multi-agent systems.
Activation Triggers:
Protocol Roles:
A2A and MCP are complementary protocols:
Hierarchical Agent Systems
Federated Tool Access
Resource-Sharing Networks
# Install both SDKs
./scripts/install-python-integration.sh
# Validate installation
./scripts/validate-python-integration.sh
# Run example
python examples/python-hybrid-agent.py
# Install both SDKs
./scripts/install-typescript-integration.sh
# Validate installation
./scripts/validate-typescript-integration.sh
# Run example
ts-node examples/typescript-hybrid-agent.ts
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.
Handle authentication for both protocols:
See templates/auth-hybrid-template.txt for patterns.
Architecture:
Template: templates/coordinator-worker-pattern.py
Use Case: Complex workflows requiring specialized agents with tool access
Architecture:
Template: templates/peer-tool-sharing-pattern.ts
Use Case: Decentralized systems where agents have different capabilities
Architecture:
Template: templates/mesh-centralized-tools-pattern.py
Use Case: Teams of agents working with shared infrastructure
Architecture:
Template: templates/layered-stack-pattern.ts
Use Case: Enterprise systems requiring protocol isolation
install-python-integration.sh - Install Python A2A + MCP SDKsinstall-typescript-integration.sh - Install TypeScript A2A + MCP SDKsinstall-java-integration.sh - Install Java A2A + MCP SDKsvalidate-python-integration.sh - Verify Python integration setupvalidate-typescript-integration.sh - Verify TypeScript integration setupvalidate-protocol-compatibility.sh - Check protocol version compatibilitysetup-hybrid-agent.sh - Initialize hybrid agent environmentsetup-mcp-server.sh - Configure MCP server for A2A agentssetup-agent-discovery.sh - Configure A2A agent discovery with MCP toolsenv-integration-template.txt - Environment variables for both protocolsauth-hybrid-template.txt - Authentication configurationagent-config-hybrid.json - Agent configuration with A2A+MCPPython:
coordinator-worker-pattern.py - Coordinator-worker implementationmesh-centralized-tools-pattern.py - Agent mesh with central MCPpython-hybrid-agent.py - Basic hybrid agentTypeScript:
peer-tool-sharing-pattern.ts - Peer-to-peer tool sharinglayered-stack-pattern.ts - Layered protocol architecturetypescript-hybrid-agent.ts - Basic hybrid agentJava:
java-hybrid-agent.java - Basic Java integrationjava-coordinator-pattern.java - Coordinator pattern in JavaConfiguration:
mcp-server-config.json - MCP server configuration for A2A agentsa2a-agent-card.json - Agent card with MCP tool referencesProblem: Multiple agents process data through different tools
Solution:
Example: examples/data-pipeline-integration.py
Problem: Research task requires web search, document analysis, and synthesis
Solution:
Example: examples/research-assistant-integration.ts
Problem: Need modular, scalable agent system
Solution:
Example: examples/microservice-agents.py
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.
Both protocols may fail independently:
See templates/failover-pattern.py for resilience patterns.
Separate Auth Per Protocol:
A2A Messages:
MCP Communication:
Hybrid Deployment:
See examples/security-best-practices.md for detailed guidance.
Choose the right protocol for each interaction:
Use A2A when:
Use MCP when:
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.
Agent Discovery Caching:
Result Caching:
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
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
Complete working examples:
Python:
python-hybrid-agent.py - Basic hybrid agentdata-pipeline-integration.py - Multi-agent data pipelinemicroservice-agents.py - Microservice architectureerror-handling-integration.py - Error handling patternsTypeScript:
typescript-hybrid-agent.ts - Basic hybrid agentresearch-assistant-integration.ts - Distributed researchpeer-coordination.ts - Peer-to-peer coordinationConfiguration:
docker-compose-integration.yml - Docker setup for hybrid systemkubernetes-hybrid-agents.yaml - Kubernetes deploymentDocumentation:
security-best-practices.md - Security guidelinestroubleshooting-integration.md - Common issues and solutionsarchitecture-patterns.md - Detailed architecture patternsProtocol 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:
See examples/troubleshooting-integration.md for detailed solutions.
Official Documentation:
GitHub Repositories:
Community:
Version: 1.0.0 A2A Protocol Compatibility: 1.0+ MCP Compatibility: 1.0+ Last Updated: 2025-12-20