ai-agents-workspace-starter: Skill for Claude Code

Skill: Agent Patterns (A2A + MCP)

Implementation patterns for multi-agent systems. Based on a2a-python (Google) and mcp (Anthropic) SDKs. Read also: .agents/rules/agent-rules.md for hard rules.

---

A. MCP Server Template

MCP Server = lightweight container exposing tools via MCP protocol. Each MCP Server is a hexagonal adapter - connects agent to external resource.

Directory structure

mcp_servers/{server_name}/
  __init__.py
  server.py          # FastMCP instance + tool registration
  tools/
    __init__.py
    {tool_group}.py  # Related tools grouped (e.g., company.py, campaign.py)
  config.py          # Pydantic Settings (URLs, timeouts)
  Dockerfile
  requirements.txt

Rules

1. server.py: Create FastMCP instance with json_response=True. Register tools by importing register_{group}_tools(mcp, settings) functions from tools/ modules.
2. Tool functions: Each tool is an async def decorated with @mcp.tool(). Uses httpx.AsyncClient with explicit timeout for HTTP calls. Returns dict.
3. Config: Use pydantic_settings.BaseSettings with env_prefix per server (e.g., MCP_GATEWAY_). Fields: port, db_gateway_url, log_level.
4. Transport: Production uses streamable-http. Tests use stdio. Legacy uses sse.
5. Dockerfile: Multi-stage build. python:3.12-slim. Non-root appuser. Healthcheck via httpx.get. Expose port. Image < 100 MB.
6. Dependencies: Minimal per server: mcp>=1.0, httpx>=0.27, pydantic>=2.9, pydantic-settings>=2.5, structlog>=24.0.

MCP Response Design

1. Success: Return {"data": ..., "hint": "Use X(id) for details"} - hint guides LLM to next step.
2. Error: Return {"error": "...", "suggestion": "Retry in 30s or inform user"} - actionable, not raw traceback.
3. Detail levels: Add detail_level: minimal | standard | full parameter for complex objects. Default minimal (ID + key fields).
4. Pagination: Lists ALWAYS with limit (default 10, max 50). Never return unbounded collections.
5. Pass-by-reference: Return resource IDs for large data (research results, long content). Agent fetches details with a separate tool call.