A2A-MCP Integration Workshop

This project demonstrates how to build a multi-agent system using Agent-to-Agent (A2A) communication with the Model Context Protocol (MCP).

Features

This workshop demonstrates a multi-agent system with:

• Host Agent: Orchestrates requests between specialized agents
• Slack Agent: Send messages to Slack channels (local)
• GitHub Agent: Create issues, PRs, and manage repositories (local)
• Bench Agent: Provides technical assistance and project insights (remote)
• Webhook Server: HTTP server that processes incoming webhooks and delegates to appropriate agents
• Admin WebUI: WebUI for viewing Agent logs, Webhooks and testing the webhook

Overview

The repository contains:

1. A Host Agent that intelligently routes user requests to specialized sub-agents
2. Three specialized agents:
3. Slack Agent: Send messages to Slack channels (runs locally)
4. GitHub Agent: Create issues in GitHub repositories (runs locally)
5. Bench Agent: Provides technical assistance and project insights (runs remotely)

The local agents connect to external services via the Model Context Protocol (MCP), while the remote Bench agent is accessed via A2A protocol over HTTP. This demonstrates a hybrid architecture where some agents run in your local environment while others can be accessed as remote services.

Architecture

┌─────────────┐     ┌───────────────┐
│             │     │ Slack Agent   │
│             ├────►│ (Port 41243)  │──► Slack Channels
│ Host Agent  │     │ [LOCAL]       │
│ (Port 41240)│     └───────────────┘
│             │     ┌───────────────┐
│  CLI        ├────►│ GitHub Agent  │──► GitHub Issues
│  Interface  │     │ (Port 41245)  │
│             │     │ [LOCAL]       │
│             │     └───────────────┘
│             │     ┌───────────────┐
│             ├────►│ Bench Agent   │──► Bench API
└─────────────┘     │ (Remote URL)  │
                    │ [REMOTE]      │
                    └───────────────┘
                    ┌───────────────┐
                    │ Webhook Server│──► Web UI Dashboard
                    │ (Port 3000)   │    Monitoring & Debug
                    └───────────────┘

System Flow Diagram

graph TD
    User[User] -->|Requests| CLI[CLI Interface]
    User -->|Monitors| WebUI[Web UI Dashboard]
    CLI -->|Tasks| Host[Host Agent]
    Host -->|Delegates| SlackAgent[Slack Agent - LOCAL]
    Host -->|Delegates| GitHubAgent[GitHub Agent - LOCAL]
    Host -->|A2A Protocol| BenchAgent[Bench Agent - REMOTE]

    SlackAgent -->|MCP| Zapier[Zapier MCP Server]
    GitHubAgent -->|MCP| Zapier
    BenchAgent -->|Remote API| BenchAPI[Bench API]

    Zapier -->|API| SlackAPI[Slack API]
    Zapier -->|API| GitHubAPI[GitHub API]

    WebhookServer[Webhook Server] -->|Provides| WebUI
    WebhookServer -->|Receives Webhooks| Host

    class Host,SlackAgent,GitHubAgent local;
    class BenchAgent remote;
    class Zapier middleware;
    class SlackAPI,GitHubAPI,BenchAPI external;
    class WebhookServer,WebUI monitoring;

    classDef local fill:#d070d0,stroke:#333,stroke-width:2px,color:#fff;
    classDef remote fill:#ff7070,stroke:#333,stroke-width:2px,color:#fff;
    classDef middleware fill:#7070d0,stroke:#333,stroke-width:2px,color:#fff;
    classDef external fill:#70b070,stroke:#333,stroke-width:2px,color:#fff;
    classDef monitoring fill:#ff7070,stroke:#333,stroke-width:2px,color:#fff;

Slack Agent Flow

sequenceDiagram
    participant User as User
    participant Host as Host Agent
    participant Slack as Slack Agent
    participant MCP as MCP Layer
    participant Zapier as Zapier MCP Server
    participant SlackAPI as Slack API

    User->>Host: "Send a message to #general"
    Host->>Slack: Delegate task
    Slack->>Slack: Parse channel and message
    Slack->>MCP: Format MCP tool call
    MCP->>Zapier: Call slack_send_channel_message tool
    Zapier->>SlackAPI: Send message
    SlackAPI-->>Zapier: Confirm sent
    Zapier-->>MCP: Return tool result
    MCP-->>Slack: Structure response
    Slack-->>Host: Report success
    Host-->>User: "Message sent successfully"

A2A vs MCP

• A2A (Agent-to-Agent): Protocol for communication between AI agents
• MCP (Model Context Protocol): Protocol for connecting AI models to external services
• Together: They create a powerful ecosystem for building multi-agent systems with external integrations

This workshop demonstrates a hybrid architecture: - Local Agents (Host, Slack, GitHub): Run on your machine and connect to external services via MCP - Remote Agents (Bench): Run on external infrastructure and are accessed via A2A protocol over HTTP

This approach allows you to: - Keep sensitive operations local while leveraging remote AI capabilities - Scale individual agents independently - Demonstrate both local and distributed agent architectures - Show how A2A protocol enables seamless communication regardless of agent location

graph LR
    AI[AI Model] -->|Tool Calls| MCP[MCP Layer]
    MCP -->|MCP Protocol| Zapier[Zapier MCP Server]
    Zapier -->|API Calls| Services[External Services]
    Services -->|Responses| Zapier
    Zapier -->|Tool Results| MCP
    MCP -->|Structured Data| AI

    subgraph "External Services"
        Slack[Slack API]
        GitHub[GitHub API]
        Other[Other APIs]
    end

    Zapier --> Slack
    Zapier --> GitHub
    Zapier --> Other

    class AI,MCP connector;
    class Zapier middleware;

    classDef connector fill:#7070d0,stroke:#333,stroke-width:2px,color:#fff;
    classDef middleware fill:#9070d0,stroke:#333,stroke-width:2px,color:#fff;

Prerequisites

• Node.js 18+
• npm or pnpm
• A free Zapier account
• A free Gemini API key
• A Slack workspace with admin privileges (for testing)

Required Zapier MCP Tools

This workshop requires the following Zapier MCP tools to be configured in your Zapier account:

Slack Integration: - Send Channel Message - Enables the Slack Agent to send messages to Slack channels

GitHub Integration:
- Create Issue - Enables the GitHub Agent to create issues in GitHub repositories

Setup Instructions: 1. Log into your free Zapier MCP account 2. Navigate to the Zapier MCP tools section 3. Configure the above tools with your Slack workspace and GitHub account 4. Copy the SSE (not the streamable http) MCP server URL from Zapier for use in your .env file

Getting Started

1. Clone the repository
2. Install dependencies: bash npm install
3. Configure your .env file with: ``` MCP_SERVER_URL=your_zapier_mcp_server_url BENCH_API_KEY=your_bench_api_key GEMINI_API_KEY=your_gemini_api_key

# Agent URLs (configure as needed) HOST_AGENT_URL=http://localhost:41240 SLACK_AGENT_URL=http://localhost:41243 GITHUB_AGENT_URL=http://localhost:41245 BENCH_AGENT_URL=http://ec2-54-183-197-218.us-west-1.compute.amazonaws.com:41246

# Slack Configuration SLACK_CHANNEL=#test-slack-damien

# GitHub Configuration
GITHUB_REPOSITORY=DamienBench/a2a-mcp-webhook-workshop ```

Note: The Bench agent is configured to run remotely at the specified URL. Local agents (Host, Slack, GitHub) will be started automatically, while the remote Bench agent is accessed over HTTP.

Webhook Server & Web UI

The webhook server provides a web-based interface for monitoring and debugging the multi-agent system. It includes a dashboard for real-time stats, webhook testing tools, and agent log viewing.

Running the Application

The agents and webhook server is automatically started when you run this script

npm run start:all

Stop all agents and services:

npm run stop:all

Accessing the Web UI

Once the webhook server is running, access the web dashboard at:

http://localhost:3000

Check the startup logs in the logs folder for errors if anything is not working

Web UI Features

The dashboard provides several key features:

• Real-time Statistics: Monitor webhook processing stats and agent activity
• Recent Invocations: View recent webhook calls with status and details
• Agent Status: Check the current status of all agents in the system
• Host Agent Messages: Debug messages sent from the Host Agent to sub-agents
• Webhook Testing: Send test data to specific webhooks and view responses
• Agent Logs: Real-time log viewer for all agents with syntax highlighting
• JSON Formatting: Format and validate webhook payloads

Webhook Endpoints

The server provides REST API endpoints:

• POST /webhook/:id - Receive webhook data for a specific webhook ID
• GET /api/webhooks - List all webhook configurations
• POST /api/test/webhook/:id - Test a webhook configuration
• GET /api/logs/:agent - Get logs for a specific agent
• GET /api/stats - Get webhook processing statistics

Agents

• Host Agent on port 41240
• Slack Agent on port 41243
• GitHub Agent on port 41245
• Webhook Server on port 3000

Note: The Bench agent runs remotely and does not need to be started locally. The system will automatically connect to the remote Bench agent at the configured URL.

All local agents run in the background, with logs stored in the logs/ directory. The web UI will show different indicators for local vs remote agents.

Troubleshooting

• View the logs of each agent and webhook server in the logs folder

Common Issues

• Zapier webhook configuration issues
• Problem: Webhook not receiving data

• Solution: Verify webhook URL in .env

• Missing or misconfigured Zapier MCP tools

• Problem: "Tool not found" or "Integration not available" errors

• Solution:

  • Ensure Send Channel Message (Slack) and Create Issue (GitHub) tools are configured in Zapier
  • Verify your Slack workspace and GitHub account are properly connected in Zapier
  • Check that the MCP server URL in .env is correct and active

• Gemini API key problems

• Problem: "API key not valid" errors

• Solution: Regenerate key and update .env

• Local agent communication failures

• Problem: Local agents can't communicate

• Solution: Check all local agents are running on correct ports

• Remote Bench agent connectivity issues

• Problem: "Failed to connect to remote agent" errors
• Solution:
  • Verify BENCH_AGENT_URL in .env file
  • Check network connectivity to remote server
  • Ensure remote agent is running and accessible
  • Test connectivity with npm run test:bench

Resources

• A2A documentation: https://github.com/google/A2A
• MCP documentation: https://modelcontextprotocol.github.io/
• Zapier: https://zapier.com
• Gemini API: https://aistudio.google.com/app/apikey

System Architecture

Decoupled Agent Design

This system implements a fully decoupled architecture where:

1. Zero Knowledge Design: Each agent (host and sub-agents) has no direct knowledge about other agents in their code or prompts
2. Protocol-based Communication: All interaction happens exclusively through the A2A protocol
3. Dynamic Discovery: The Host Agent discovers available agents at runtime
4. Task Delegation: Tasks are delegated based on capability matching, not hardcoded routing

This architectural approach provides: - Flexibility: New agents can be added without modifying existing ones - Scalability: The system can grow to include more specialized agents - Maintainability: Each agent can be developed and updated independently - Resilience: The system can function even if some agents are unavailable

Debugging with Webhook Handler

The system includes a webhook handler server with a web UI for debugging agent interactions: - Real-time monitoring of agent communication - Inspection of messages sent between agents - Testing webhook configurations - Viewing agent logs

Component Documentation

Each component has its own detailed documentation: - Host Agent - Slack Agent - GitHub Agent - Bench Agent - Webhook Handler & Web UI