A2A to MCP bridge MCP server

a2a-to-mcp

A2A v1.0.1 agents exposed as MCP tools on a stateless MCP 2026-07-28 server, with the io.modelcontextprotocol/tasks extension.

Point the bridge at one or more A2A agents by their agent card. Any MCP client, Claude Code or Cursor among them, then sees four ordinary tools: discover an agent, send it a message, read a task, cancel a task. The bridge translates parts, artifacts, task states and errors between the two protocols and says out loud what it cannot translate.

Node 20 or later. Apache-2.0.

Quick start

npm install -g a2a-to-mcp

Or run it from the repository:

git clone https://github.com/AmirK-S/a2a-to-mcp.git && cd a2a-to-mcp && npm ci && npm run build

Write agents.json, one alias per agent, by base URL or by card URL:

{
  "agents": {
    "hello": { "url": "http://localhost:9999" },
    "planner": { "cardUrl": "https://planner.example.org/.well-known/agent-card.json" }
  },
  "port": 8931
}

Run it:

node dist/cli.js --config agents.json

The bridge listens on http://127.0.0.1:8931/mcp. Only loopback hosts are accepted in the Host and Origin headers unless allowedHosts is set in the configuration. There is no authentication in this version, on either side.

Claude Code

Add to .mcp.json at the root of the project, which is the block the bridge prints on startup:

{
  "mcpServers": {
    "a2a-to-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:8931/mcp"
    }
  }
}

Claude Code negotiates 2026-07-28 through server/discover since its v2 runtime, documented from 2.1.232 and measured here with 2.1.263. Older versions fall back to initialize and get the same four tools on the legacy route. A full annotated trace of a Claude Code session against the bridge, discovery, a task with an artifact and an elicitation round trip, is in docs/DEMO-CLAUDE-CODE.md. In headless mode (claude -p) there is nobody to answer an elicitation, so Claude Code cancels it and the bridge cancels the A2A task; the interactive mode asks the user.

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "a2a": { "url": "http://localhost:8931/mcp" }
  }
}

Cursor speaks 2025-11-25 and is served through initialize on the same endpoint.

The four tools

Every tool takes the agent alias as its first argument when several agents are configured; with a single agent the alias may be omitted and defaults to it.

Calling a tool on the wire

The argument that carries the message is text. A complete tools/call on the 2026-07-28 route, as an MCP client sends it:

Shortened. The full README is on GitHub.