a2a-mcp-bridge

MCP server that bridges A2A (Agent-to-Agent) protocol agents into Claude Code and other MCP clients.

Discovers external A2A agents via their Agent Cards, then exposes them as MCP tools so any MCP-compatible client (Claude Code, Cursor, Windsurf, etc.) can interact with them.

Quick Start with Claude Code

Option 1: One-liner (recommended)

Add the bridge as an MCP server with env vars inline:

claude mcp add a2a-bridge \
  -e A2A_AGENT_URLS=https://your-a2a-server.com \
  -e A2A_API_TOKEN=your-token \
  -- npx a2a-mcp-bridge

This writes to your project-level .mcp.json. Done — Claude Code will auto-start the bridge.

Option 2: Global (available in all projects)

claude mcp add a2a-bridge --scope user \
  -e A2A_AGENT_URLS=https://your-a2a-server.com \
  -e A2A_API_TOKEN=your-token \
  -- npx a2a-mcp-bridge

Option 3: Manual config

Add to your project's .mcp.json (create it in the project root if it doesn't exist):

{
  "mcpServers": {
    "a2a-bridge": {
      "command": "npx",
      "args": ["a2a-mcp-bridge"],
      "env": {
        "A2A_AGENT_URLS": "https://your-a2a-server.com",
        "A2A_API_TOKEN": "your-token"
      }
    }
  }
}

Option 4: Env vars via settings file

If you prefer to keep secrets out of .mcp.json, add the server without env vars:

claude mcp add a2a-bridge -- npx a2a-mcp-bridge

Then add env vars to .claude/settings.local.json (git-ignored):

{
  "env": {
    "A2A_AGENT_URLS": "https://your-a2a-server.com",
    "A2A_API_TOKEN": "your-token"
  }
}

Connecting to multiple A2A servers

Pass comma-separated URLs:

claude mcp add a2a-bridge \
  -e A2A_AGENT_URLS=https://server1.com,https://server2.com,https://server3.com \
  -e A2A_API_TOKEN=shared-token \
  -- npx a2a-mcp-bridge

Verify it works

After adding, restart Claude Code and run:

> use the list_agents tool to show all available A2A agents

Claude will call the list_agents MCP tool and show you all discovered agents.

Other MCP Clients

Cursor / Windsurf / any MCP-compatible editor

Add to your MCP config file (location varies by editor):

{
  "mcpServers": {
    "a2a-bridge": {
      "command": "npx",
      "args": ["a2a-mcp-bridge"],
      "env": {
        "A2A_AGENT_URLS": "https://your-a2a-server.com",
        "A2A_API_TOKEN": "your-token"
      }
    }
  }
}

Run standalone

A2A_AGENT_URLS=https://your-a2a-server.com A2A_API_TOKEN=your-token npx a2a-mcp-bridge

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | A2A_AGENT_URLS | Yes | Comma-separated base URLs of A2A agents to discover | | A2A_API_TOKEN | No | Global API token sent as X-API-TOKEN header | | A2A_AGENT_TOKENS | No | JSON object mapping agent slugs to per-agent tokens | | A2A_REFRESH_INTERVAL_MS | No | Auto-refresh interval in ms (default: 300000 = 5 min, 0 = disabled) |

Per-agent tokens

When different agents require different tokens:

A2A_AGENT_TOKENS='{"weather-agent":"token1","echo-agent":"token2"}'

MCP Tools

Once running, the bridge exposes 5 tools:

| Tool | Description | |------|-------------| | list_agents | List all discovered A2A agents with their skills and capabilities | | refresh_agents | Re-fetch agent cards from all configured URLs, updating skills and removing stale agents | | send_message | Send a message to an A2A agent and get a response | | get_task | Get the current status of a task from an A2A agent | | get_agent_card | Get the full cached agent card for an A2A agent |

Multi-turn conversations

The bridge automatically tracks conversation context per agent within a session. Subsequent send_message calls to the same agent reuse the conversation ID, enabling multi-turn dialogue.

You can also pass an explicit context_id to send_message to control which conversation to continue.

How It Works

1. On startup, fetches Agent Cards from each URL in A2A_AGENT_URLS
   • Tries /.well-known/agent-card.json (A2A v0.3.0) then /.well-known/agent.json (v0.2.x)
2. Registers discovered agents and exposes them as MCP tools
3. Routes send_message calls as A2A JSON-RPC 2.0 message/send requests
4. Extracts text from various A2A response formats (messages, tasks, artifacts)

Requirements

• Node.js >= 18

License

MIT