a2a-server-config

A2A Server Configuration

Provides complete patterns and templates for configuring Agent-to-Agent (A2A) servers with different transport mechanisms (HTTP, STDIO, SSE, WebSocket) following MCP (Model Context Protocol) standards.

Security: API Key Handling

CRITICAL: When generating any configuration files or code:

• NEVER hardcode actual API keys or secrets

• NEVER include real credentials in examples

• NEVER commit sensitive values to git

• ALWAYS use placeholders: your_service_key_here

• ALWAYS create .env.example with placeholders only

• ALWAYS add .env* to .gitignore (except .env.example)

• ALWAYS read from environment variables in code

• ALWAYS document where to obtain keys

Placeholder format: {service}_{env}_your_key_here

Instructions

Phase 1: Analyze Requirements

Determine server configuration needs:

1. Transport Type

   • HTTP: Remote access, REST-like communication, CORS support
   • STDIO: Local process communication, pipe-based I/O
   • SSE (Server-Sent Events): Real-time streaming, one-way server push
   • WebSocket: Bidirectional real-time communication

2. Framework Detection

   • Python: FastAPI, Flask, Starlette
   • TypeScript: Express, Fastify, Node.js native http
   • Detect from package.json or requirements.txt

3. Configuration Needs

   • Port and host settings
   • CORS configuration
   • Authentication requirements
   • Environment variables

Phase 2: Select and Load Templates

Based on requirements, use templates from templates/:

Python Templates:

• templates/python-http-server.py - FastAPI HTTP server
• templates/python-stdio-server.py - STDIO transport
• templates/python-sse-server.py - SSE streaming
• templates/python-websocket-server.py - WebSocket bidirectional

TypeScript Templates:

• templates/typescript-http-server.ts - Express HTTP server
• templates/typescript-stdio-server.ts - STDIO transport
• templates/typescript-sse-server.ts - SSE streaming
• templates/typescript-websocket-server.ts - WebSocket bidirectional

Phase 3: Configure Transport

Apply configuration based on transport type:

HTTP Configuration:

# Python (FastAPI)
if __name__ == "__main__":
    import uvicorn
    uvicorn.run(
        "main:app",
        host="0.0.0.0",
        port=8000,
        reload=True
    )

// TypeScript (Express)
const PORT = process.env.PORT || 8000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

STDIO Configuration:

# Python
mcp.run(transport="stdio")

// TypeScript
server.connect(new StdioServerTransport());

SSE Configuration:

# Python
@app.get("/events")
async def events():
    return EventSourceResponse(event_generator())

WebSocket Configuration:

# Python
@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()

Phase 4: Add CORS and Security

For HTTP/SSE/WebSocket servers:

# Python
from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # Configure appropriately
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

// TypeScript
import cors from 'cors';
app.use(cors({
  origin: process.env.ALLOWED_ORIGINS?.split(',') || '*',
  credentials: true
}));

Phase 5: Environment Configuration

Create .env.example with placeholders:

# Server Configuration
PORT=8000
HOST=0.0.0.0
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173

# API Keys (NEVER commit real values)
ANTHROPIC_API_KEY=your_anthropic_key_here
OPENAI_API_KEY=your_openai_key_here

# Transport Settings
TRANSPORT_TYPE=http
ENABLE_CORS=true

Phase 6: Validation

Run validation script:

bash scripts/validate-config.sh <server-file>

Checks:

• No hardcoded API keys
• Environment variable usage
• CORS configuration
• Transport setup validity
• .gitignore includes .env files

Scripts

• scripts/validate-config.sh - Validate server configuration
• scripts/generate-server.sh - Generate server from template
• scripts/test-transport.sh - Test transport connectivity

Templates

Python:

• templates/python-http-server.py - HTTP server with FastAPI
• templates/python-stdio-server.py - STDIO transport
• templates/python-sse-server.py - SSE streaming server
• templates/python-websocket-server.py - WebSocket server

TypeScript:

• templates/typescript-http-server.ts - HTTP server with Express
• templates/typescript-stdio-server.ts - STDIO transport
• templates/typescript-sse-server.ts - SSE streaming server
• templates/typescript-websocket-server.ts - WebSocket server

Examples

• examples/http-fastapi-example.md - Complete HTTP server with FastAPI
• examples/stdio-simple-example.md - Basic STDIO server
• examples/sse-streaming-example.md - SSE streaming configuration
• examples/websocket-bidirectional-example.md - WebSocket bidirectional communication

Requirements

• Framework-specific dependencies (FastAPI/Express/etc.)
• CORS middleware for HTTP/SSE/WebSocket
• Environment variable management (python-dotenv/dotenv)
• No hardcoded API keys or secrets
• .gitignore protection for sensitive files

Use Cases

1. Setting up HTTP server for remote A2A communication

   • Load http template
   • Configure CORS
   • Set environment variables
   • Validate configuration

2. Configuring STDIO for local agent communication

   • Load stdio template
   • Configure process pipes
   • Test connectivity

3. Implementing SSE for real-time agent updates

   • Load sse template
   • Configure event streams
   • Set up CORS
   • Test streaming

4. Setting up WebSocket for bidirectional agent chat

   • Load websocket template
   • Configure connection handling
   • Set up authentication
   • Test bidirectional flow