A comprehensive Node.js implementation of an Agent-to-Agent (A2A) system compliant with the A2A Protocol v0.3.0. The system features dual AI-powered agents (Buyer and Seller) for OpenDirect advertising operations, with integrated Model Context Protocol (MCP) support for tool execution.
Built on a clean modular architecture with 5 independent modules that work together seamlessly.
- π€ Dual AI Agents - Autonomous Buyer and Seller agents with natural language understanding
- π A2A Protocol v0.3.0 - Full compliance with agent card discovery, JSON-RPC 2.0, and HTTP+JSON transports
- π§ MCP Integration - 33+ auto-generated tools from OpenDirect schemas
- π¨ Schema-Driven - Single source of truth from OpenAPI 3.0 schemas
- π¬ Multi-Provider AI - Support for OpenAI, Anthropic Claude, and Google Gemini
- π Web Interface - Ready-to-use test client for agent interactions
node >= 18.0.0
npm >= 9.0.0# Clone repository
git clone https://github.com/InteractiveAdvertisingBureau/mcp-config.git
cd mcp-config
# Install dependencies
npm install
# Install test client
cd client-test && npm install && cd ..Create .env file:
NODE_ENV=development
PORT=3000
# AI Provider (choose one)
OPENAI_API_KEY=sk-proj-your-key
OPENAI_MODEL=gpt-4o-mini
# Optional: Other providers
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=...
# MCP Configuration
DEFAULT_ANALYSIS_MODEL=openai
DEFAULT_CHAT_MODEL=openai
MCP_ENABLE_ADMIN_TOOLS=falseOr use the quick-start script:
./quick-start.shnpm start
# Expected: Server on port 3000, MCP integration with 33 toolscd client-test && npm start
# Expected: Server on http://localhost:8080β Agent Card Discovery:
curl http://localhost:3000/a2a/buyer/.well-known/agent-card.json | jqβ Web Client:
http://localhost:8080
β Send test message:
"create an account for Nike"
The system is organized into four distinct layers:
-
Client Layer - Web UI (
client-test/) and A2A-compliant clients communicate via the A2A Protocol v0.3.0 over HTTPS. -
A2A Agent Layer - Express.js server (port 3000) hosting Buyer and Seller agents with multiple transport protocols (JSON-RPC 2.0, HTTP+JSON), dynamic agent card generation, and AI-powered execution.
-
MCP Layer - Schema-driven tool generator using OpenAPI 3.0 specs to dynamically create 33+ tools from the OpenDirect schema, with validation and API handlers via Server-Sent Events (SSE) transport.
-
Schema Layer - OpenAPI 3.0 specification defining 13 resource types (Account, Order, Line, Product, Creative, etc.), 40+ object definitions, and standardized endpoints with parameters and validations.
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β CLIENT LAYER β
β ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ β
β β Web Client β βClaude Desktopβ β Test Client β β
β β(client-test) β β (MCP HTTP) β β (SDK) β β
β ββββββββ¬ββββββββ ββββββββ¬ββββββββ ββββββββ¬ββββββββ β
βββββββββββΌβββββββββββββββββββΌβββββββββββββββββββΌββββββββββββββββββββ
β β β
β HTTP/JSON β SSE β HTTP
β A2A Protocol β MCP Protocol β A2A Protocol
β β β
βββββββββββΌβββββββββββββββββββΌβββββββββββββββββββΌββββββββββββββββββββ
β A2A AGENT LAYER (Port 3000) β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β Client Agent (Orchestrator) β β
β β β’ Autonomous Mode: Auto-selects buyer/seller β β
β β β’ Orchestrated Mode: User-directed routing β β
β β β’ Session management & conversation history β β
β βββββββββββββββ¬βββββββββββββββββββββββββ¬βββββββββββββββββββββ β
β β β β
β ββββββββββββββΌβββββββββββ βββββββββββΌβββββββββββ β
β β Buyer Agent β β Seller Agent β β
β β /a2a/buyer β β /a2a/seller β β
β β βββββββββββββββββββ β β ββββββββββββββββββββ β
β β β Agent Card β β β β Agent Card ββ β
β β β - Skills β β β β - Skills ββ β
β β β - Transports β β β β - Transports ββ β
β β β - Examples β β β β - Examples ββ β
β β βββββββββββββββββββ β β ββββββββββββββββββββ β
β β Skills: β β Skills: β β
β β β’ create_account β β β’ list_products β β
β β β’ create_order β β β’ search_inventory β β
β β β’ search_inventory β β β’ process_orders β β
β ββββββββββββββ¬βββββββββββ βββββββββββ¬ββββββββββββ β
ββββββββββββββββββΌββββββββββββββββββββββββββΌββββββββββββββββββββββββββ
β β
β MCP Tool Calls β MCP Tool Calls
β β
ββββββββββββββββββΌββββββββββββββββββββββββββΌββββββββββββββββββββββββββ
β MCP LAYER β
β ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ β
β β API Testing β β OpenDirect β βSchema-Driven β β
β β MCP β β MCP β β MCP β β
β β /mcp/sse β β/agenticdirectβ β /schema/mcp β β
β β (8 tools) β β /mcp/sse β β /sse β β
β β β β (10 tools) β β (33 tools) β β
β β Transport: β β Transport: β β Transport: β β
β β SSE β β SSE β β SSE β β
β ββββββββββββββββ ββββββββββββββββ ββββββββ¬ββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββ
β
β Schema Loading
β & Validation
β
βββββββββββββββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββ
β SCHEMA LAYER β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β OpenDirect OpenAPI 3.0 Schema β β
β β (opendirect-mcp-schema.json) β β
β β β β
β β π 13 Resource Types: β β
β β Account, Order, Line, Product, Creative, β β
β β Assignment, Organization, ChangeRequest, Message β β
β β β β
β β ποΈ 40+ Object Definitions: β β
β β - Request/Response schemas β β
β β - Validation rules (Zod) β β
β β - Parameter specifications β β
β β β β
β β β
CRUD Operations: create, get, list, update, delete β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
- Web UI (
client-test/): Pure HTML/CSS/JavaScript interface - A2A Protocol v0.3.0: Standard agent communication
- Features:
- Agent selection (Buyer/Seller)
- Connection management
- Real-time response display
- Message history and session tracking
- Dual Agents: Buyer (
/a2a/buyer) and Seller (/a2a/seller) - Agent Card Discovery:
/.well-known/agent-card.json - Transports:
- JSON-RPC 2.0 (
/jsonrpc) - HTTP+JSON (
/rest) - MCP tools integration
- JSON-RPC 2.0 (
- AI-Powered Execution: OpenAI GPT for natural language understanding
- Modes:
- Autonomous: Agent auto-selects sub-agents
- Orchestrated: User-directed routing
- Schema-Driven Tool Generator: Processes OpenAPI 3.0 specs
- Validation: Zod schemas for runtime parameter checking
- Tool Registry:
- API Testing MCP: 8 tools (register, test, analyze APIs)
- OpenDirect MCP: 10 tools (manual implementations)
- Schema-Driven MCP: 33 tools (auto-generated CRUD)
- Transport: Server-Sent Events (SSE) for streaming
- OpenDirect Specification: OpenAPI 3.0 format
- 13 Resource Types: Account, Order, Line, Product, Creative, etc.
- 40+ Object Definitions: Complete request/response schemas
- Validation Rules: JSON Schema with Zod transformation
βββββββββββββββ
β Client β 1. User sends message: "create account for Nike"
β (Web UI) β
ββββββββ¬βββββββ
β
β POST /api/a2a/chat
β { message: "create account for Nike" }
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Client Agent (Orchestrator) β
β β
β 2. Analyze message with AI (OpenAI GPT) β
β β Determine: Account creation needed β
β β Select: Buyer Agent β
β β Extract params: { name: "Nike" } β
ββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββ
β
β 3. Route to Buyer Agent
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Buyer Agent β
β /a2a/buyer β
β β
β 4. Receive message via JSON-RPC 2.0: β
β POST /a2a/buyer/jsonrpc β
β { β
β "method": "sendMessage", β
β "params": { β
β "message": "create account for Nike" β
β } β
β } β
ββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββ
β
β 5. Execute skill: create_account
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β MCP Layer β
β (Schema-Driven MCP Server) β
β β
β 6. Call MCP tool: create_account β
β POST /schema/mcp/sse β
β { β
β "method": "tools/call", β
β "params": { β
β "name": "create_account", β
β "arguments": { β
β "name": "Nike", β
β "type": "advertiser" β
β } β
β } β
β } β
β β
β 7. Validate with Zod schema β
β 8. Execute account creation logic β
ββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββ
β
β 9. Return result
β { accountId: "acc_123", name: "Nike", ... }
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Buyer Agent β
β β
β 10. Format response β
β "β
Created account for Nike (ID: acc_123)" β
ββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββ
β
β 11. Return to orchestrator
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Client Agent (Orchestrator) β
β β
β 12. Add to conversation history β
β 13. Publish progress events β
ββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββ
β
β 14. Return to client
β {
β response: "β
Created account...",
β data: { accountId: "acc_123", ... }
β }
β
βΌ
βββββββββββββββ
β Client β 15. Display response to user
β (Web UI) β
βββββββββββββββ
Multi-Step Workflow Example:
Message: "Create account for Adidas and create order for Adidas with budget $300"
Step 1: create_account
ββ> Response: { accountId: "acc_456" }
β
βΌ
Step 2: create_order
ββ> Input: { accountId: "acc_456", budget: 300 }
ββ> Response: { orderId: "ord_789", accountId: "acc_456" }
The orchestrator automatically:
- β Chains multiple operations
- β Passes data between steps (account ID)
- β Maintains conversation context
- β Handles errors gracefully
| Component | File/Module | Purpose |
|---|---|---|
| Main Server | server.js |
Express setup, module orchestration, routing |
| Agent Card | modules/a2a-protocol/lib/a2aEndpoints.js |
Agent discovery with skills, capabilities, security |
| Agent Executor | modules/a2a-protocol/lib/agentExecutor.js |
AI-powered tool selection and task management |
| Client Agent | modules/a2a-protocol/lib/clientAgent.js |
Agent orchestrator (autonomous/orchestrated modes) |
| MCP Server | modules/schema-driven-mcp/server.js |
Schema-driven tool registry with SSE transport |
| Tool Generator | modules/schema-driven-mcp/lib/toolGenerator.js |
Auto-generate CRUD tools from schemas |
| Schema Loader | modules/schema-driven-mcp/lib/schemaLoader.js |
Load and validate OpenAPI schemas |
| Web Client | client-test/ |
HTML/CSS/JS A2A test interface |
| OpenDirect Schema | opendirect-mcp-schema.json |
OpenAPI 3.0 resource definitions and validations |
- Web UI (
client-test/): Pure HTML/CSS/JS interface - Direct A2A protocol calls
- Agent selection (Buyer/Seller)
- Real-time monitoring and status updates
- Message streaming support
- Express.js server (Port 3000)
- Dual agents:
- Buyer:
/a2a/buyer - Seller:
/a2a/seller
- Buyer:
- Agent card discovery:
/.well-known/agent-card.json - Skills: Order creation, campaigns, creative management, product search
- Multiple transports: JSON-RPC 2.0, HTTP+JSON, MCP tools
- AI-powered orchestration: Natural language β tool mapping
- Schema-driven tool generator from OpenAPI schemas
- Input: OpenDirect OpenAPI 3.0 specification
- Output: 33+ executable MCP tools with validation
- Transport: Server-Sent Events (SSE) for streaming
- Tool categories: CRUD operations, search, validation
- OpenDirect JSON specification (OpenAPI 3.0)
- 13 resource types: Account, Order, Line, Product, Creative, etc.
- 40+ object definitions with full validation schemas
- Parameter validation and response schemas
mcp-config/
βββ server.js # Main entry point (modular architecture)
βββ package.json # Dependencies
β
βββ modules/ # 5 Independent modules
β βββ a2a-protocol/ # β Agent-to-Agent communication
β β βββ server.js # A2A agent orchestrator
β β βββ routes/ # Agent endpoints
β β βββ lib/ # Agent cards, executors, SDK integration
β βββ opendirect-mcp/ # OpenDirect MCP implementation
β βββ schema-driven-mcp/ # Schema-to-tools generator
β βββ api-testing-mcp/ # API testing & validation
β βββ ai-chat/ # Multi-provider AI chat
β
βββ shared/ # Shared utilities
β βββ config/ # Centralized configuration
β βββ database/ # Database connection
β βββ utils/ # Logger, UUID, date utilities
β βββ middleware/ # CORS, error handlers
β
βββ client/ # Frontend clients
β βββ standalone/ # AI chat UI
βββ client-test/ # β A2A test client
β βββ index.html # Web interface
β βββ app.js # Client logic
β βββ style.css # Styling
βββ client-test-sdk/ # SDK-based test client
β
βββ prompts/ # AI agent prompts
β βββ buyer/ # Buyer agent prompts
β βββ seller/ # Seller agent prompts
β
βββ tests/ # Test resources
β βββ schemas/ # Test schemas
β βββ test.sh # Module testing script
β
βββ opendirect-mcp-schema.json # OpenDirect schema
βββ claude-desktop-config.json # MCP client configuration
βββ quick-start.sh # Quick setup script
βββ deploy.sh # Cloud deployment script
βββ Dockerfile # Docker configuration
β
βββ a2a-agenticdirect-standalone/ # Standalone A2A module
Each agent exposes a standard agent card at /.well-known/agent-card.json:
# Buyer Agent Card
curl http://localhost:3000/a2a/buyer/.well-known/agent-card.json
# Seller Agent Card
curl http://localhost:3000/a2a/seller/.well-known/agent-card.jsonAgent Card Structure:
- Identity: Name, description, version
- Skills: Available operations (create_order, search_products, etc.)
- Transports: JSON-RPC 2.0, HTTP+JSON, MCP tools
- Security: Authentication requirements
- Examples: Sample requests and responses
1. Autonomous Mode (Default)
- Agent automatically selects appropriate sub-agents
- Natural language understanding
- Multi-step workflow orchestration
- Example: "Create order for Nike" β Agent calls buyer agent with correct tools
2. Orchestrated Mode
- User manually selects target agent
- Direct agent communication
- More control over agent selection
POST /a2a/{agent}/jsonrpc
Content-Type: application/json
{
"jsonrpc": "2.0",
"method": "sendMessage",
"params": {
"message": "create an account for Nike",
"context": {}
},
"id": 1
}POST /a2a/{agent}/rest
Content-Type: application/json
{
"message": "search for video ad products",
"sessionId": "optional-session-id"
}# Send message to orchestrator
POST /api/a2a/chat
# Get conversation history
GET /api/a2a/chat/:sessionId/history
# Clear conversation
DELETE /api/a2a/chat/:sessionId
# Get progress events
GET /api/a2a/chat/:sessionId/progress
# Set/get agent mode
POST /api/a2a/mode
GET /api/a2a/modePurpose: Agent-to-agent communication using official @a2a-js/sdk with AI orchestration.
Endpoints:
/a2a/agents- Agent discovery/a2a/buyer/.well-known/agent-card.json- Buyer agent card/a2a/seller/.well-known/agent-card.json- Seller agent card/api/a2a/chat- Client agent chat/api/a2a/mode- Set orchestration mode
Agent Skills:
Buyer Agent:
- Create and manage accounts
- Create advertising orders
- Manage campaigns and budgets
- Search for ad inventory
- Assign creatives to placements
Seller Agent:
- List available products
- Process orders
- Manage inventory
- Handle change requests
Key Features:
- β Agent card auto-generation with skills, examples, security
- β Multiple transports: JSON-RPC 2.0, HTTP+JSON, MCP tools
- β AI-powered natural language understanding (OpenAI GPT)
- β Autonomous and orchestrated modes
- β Session management and conversation history
- β Progress tracking and streaming responses
Purpose: Advertising operations following OpenDirect v2.1 specification.
Endpoints: /agenticdirect/mcp/sse
Tools (10 core operations):
- Organization, Account, Order, Line, Creative management
- Product search and inventory queries
- Change requests and messaging
Purpose: Auto-generate MCP tools from OpenAPI schemas with runtime validation.
Endpoints: /schema/mcp/sse
Tools (33+ auto-generated):
- CRUD operations for all OpenDirect resources
- Runtime JSON Schema validation
- Hot-reload capability without server restart
- Sandbox testing environment
Schema Management API:
POST /api/schema/register # Register custom schema
POST /api/schema/fetch-url # Fetch schema from URL
POST /api/schema/reset # Reset to default
POST /api/schema/test-tool # Test tool in sandbox
GET /api/schema/current # Get current schema
GET /api/schema/history # Get registration historyPurpose: Test and validate REST APIs with AI analysis.
Endpoints: /mcp/sse
Tools: Register APIs, test endpoints, generate AI-powered analysis and test scenarios.
Purpose: Multi-provider AI chat with MCP integration.
Endpoints: /chat
Providers: Anthropic Claude, OpenAI GPT, Google Gemini
curl http://localhost:3000/a2a/buyer/.well-known/agent-card.json | jqExpected Response:
{
"name": "OpenDirect Buyer Agent",
"version": "1.0.0",
"skills": [
{
"name": "create_account",
"description": "Create a new buyer account",
"parameters": { ... }
}
],
"transports": [
{
"type": "jsonrpc",
"version": "2.0",
"endpoint": "/a2a/buyer/jsonrpc"
}
]
}curl -X POST http://localhost:3000/a2a/buyer/jsonrpc \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "sendMessage",
"params": {
"message": "create an account for Nike"
},
"id": 1
}' | jq# List available MCP tools
curl http://localhost:3000/schema/mcp/tools | jq '.tools[].name'
# Test MCP health
curl http://localhost:3000/schema/mcp/health
curl http://localhost:3000/agenticdirect/mcp/health
curl http://localhost:3000/mcp/health./tests/test.sh# Account creation
"create an account for Nike"
# Order creation
"create an order for Adidas with budget $50000"
# Inventory search
"search for video ad inventory"
# Campaign setup
"create a campaign for summer sale targeting 25-34 age group"# Product listing
"list available products"
# Inventory search
"search for premium ad space"
# Order processing
"process order for account ABC"
# Change requests
"handle change request for order 12345"Create claude-desktop-config.json:
{
"mcpServers": {
"api-testing-mcp": {
"url": "http://localhost:3000/mcp/sse",
"transport": "http"
},
"opendirect-mcp": {
"url": "http://localhost:3000/agenticdirect/mcp/sse",
"transport": "http"
},
"schema-driven-mcp": {
"url": "http://localhost:3000/schema/mcp/sse",
"transport": "http"
}
}
}# Build image
docker build -t mcp-config .
# Run container
docker run -p 3000:3000 \
-e PORT=3000 \
-e OPENAI_API_KEY=sk-proj-... \
-e OPENAI_MODEL=gpt-4o-mini \
mcp-config# Deploy to Google Cloud Run
./deploy.sh
# Or manually
gcloud run deploy mcp-config \
--source . \
--platform managed \
--region us-east4 \
--allow-unauthenticated| Issue | Solution |
|---|---|
| Port 3000 in use | lsof -i :3000 then kill -9 <PID> |
| Missing API key | Verify .env contains OPENAI_API_KEY |
| Server not responding | curl http://localhost:3000/mcp/health |
| Client connection fails | Confirm server running, check CORS |
| Agent card 404 | Check /a2a/buyer/.well-known/agent-card.json |
| MCP tools not loading | Verify schema loaded: GET /api/schema/current |
# Enable debug logging
NODE_ENV=development node server.js
# Check server logs
tail -f /tmp/server-test.log
# Test each module independently
curl http://localhost:3000/mcp/health
curl http://localhost:3000/agenticdirect/mcp/health
curl http://localhost:3000/schema/mcp/health
curl http://localhost:3000/a2a/agentsGET /mcp/health # API Testing MCP
GET /agenticdirect/mcp/health # OpenDirect MCP
GET /schema/mcp/health # Schema-Driven MCP
GET /a2a/agents # A2A Protocol
GET /api/ai-health # AI ChatGET /a2a/agents # List agents
GET /a2a/{agent}/.well-known/agent-card.json # Agent card
POST /a2a/{agent}/jsonrpc # JSON-RPC 2.0
POST /a2a/{agent}/rest # HTTP+JSON
POST /api/a2a/chat # Client chat
GET /api/a2a/chat/:sessionId/history # History
POST /api/a2a/mode # Set modePOST /mcp/sse # API Testing MCP (SSE)
POST /agenticdirect/mcp/sse # OpenDirect MCP (SSE)
POST /schema/mcp/sse # Schema-Driven MCP (SSE)
GET /schema/mcp/tools # List generated tools
GET /schema/mcp/resources # List resourcesAfter setup, verify:
- β
Server running on
http://localhost:3000 - β
Test client running on
http://localhost:8080 - β
Agent cards accessible:
http://localhost:3000/a2a/buyer/.well-known/agent-card.jsonhttp://localhost:3000/a2a/seller/.well-known/agent-card.json
- β
MCP endpoints healthy:
http://localhost:3000/mcp/healthhttp://localhost:3000/schema/mcp/health
- β Messages sent/received successfully via web client
- β Response data displayed as JSON
- β Multi-step workflows execute sequentially
- Protocol Compliance - Full A2A v0.3.0 support with agent cards
- Scalability - Modular design allows independent scaling
- Extensibility - Schema-driven tool generation from OpenAPI
- Maintainability - Clear separation of concerns across modules
- AI-Powered - Natural language understanding with multiple AI providers
- Interoperability - Standard MCP protocol for tool execution
- Explore Agent Cards - Review buyer and seller capabilities
- Test with Web Client - Use
http://localhost:8080for interactive testing - Review MCP Tools - Check
/schema/mcp/toolsfor available operations - Integrate with Claude - Use HTTP transport configuration
- Deploy to Production - Use
deploy.shfor Cloud Run deployment - Customize Agents - Modify prompts in
prompts/buyer/andprompts/seller/
- A2A Protocol: https://a2a-protocol.org/v0.3.0/specification/
- OpenDirect Spec: https://www.iab.com/guidelines/opendirect/
- MCP Protocol: https://modelcontextprotocol.io/
- JSON-RPC 2.0: https://www.jsonrpc.org/specification
- IABTechLab MCP Server: https://mcpclient.iabtechlab.com