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:

curl -sS http://127.0.0.1:8931/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' \
  -H 'Mcp-Name: a2a_send_message' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
        "_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28",
                 "io.modelcontextprotocol/clientCapabilities":{}},
        "name":"a2a_send_message",
        "arguments":{"agent":"hello","text":"task: hello world"}}}'

A run against a public A2A agent, with the one mistake a first user makes, is in docs/USAGE-REEL.md.

Result contract

Each reply is a CallToolResult whose content holds the translated parts and whose structuredContent is an envelope:

{
  "kind": "task",
  "contextHandle": "cx_...",
  "taskHandle": "tk_...",
  "a2aState": "TASK_STATE_COMPLETED",
  "status": "completed",
  "note": "present when the mapping lost information",
  "artifacts": [{ "artifactId": "...", "name": "result" }],
  "data": {}
}

data holds the single A2A data part of the artifacts, and is absent when there is none or more than one. history is added by a2a_get_task only.

kind is message for a direct A2A message and task when the agent opened a task. Handles are opaque strings minted by the bridge, never A2A identifiers; they hide the bridge table, not what an agent chooses to write in its own messages. They live in memory for fifteen minutes after their last use by default (handleTtlMs), and an expired or unknown handle returns an explicit error. Pass contextHandle back to stay in the same conversation, and taskHandle back to answer a task the agent left waiting for input.

An agent failure (FAILED, REJECTED, AUTH_REQUIRED), and a task the agent left in the unspecified state, is a tool execution error: isError: true, the agent text in content, the A2A state and a note in the envelope. A typed A2A error (codes -32001 to -32009) is also a tool execution error, with the code in structuredContent.a2aErrorCode. The bridge never re-emits an A2A error code as a JSON-RPC code. JSON-RPC reserves -32000 to -32099 for server-defined errors, MCP already uses -32020, -32021 and -32022 in that band, and an A2A code replayed there would claim an MCP meaning it does not have.

Long-running tasks

With the tasks extension

A client that declares io.modelcontextprotocol/tasks in the per-request clientCapabilities.extensions gets a CreateTaskResult from a2a_send_message as soon as the agent opens a task, then polls tasks/get and may call tasks/update and tasks/cancel. The bridge consumes SendStreamingMessage in the background when the card announces streaming, and GetTask otherwise.

AUTH_REQUIRED is deliberately not mapped to input_required: MCP forbids form elicitation for credentials, and A2A asks for out-of-band authorization. The agent text, which usually carries the URL to visit, is returned in the result.

The extension is served on the 2026-07-28 route only. On the legacy route, tasks/* answer -32021 with the required capability. As of 2026-09-06, the two clients measured against this bridge, Claude Code and Cursor, do not declare the extension. It is exercised by the test suite in this repository and by any client that opts in per request.

CreateTaskResult leaves the bridge with an empty content array in addition to the fields the extension defines. That is a workaround for the reference SDK, which validates every tools/call result against the plain result schema (typescript-sdk issue 2637). The three extension methods are served by a small router in front of the SDK on the modern route, because the SDK answers -32601 to tasks/get and tasks/cancel before consulting its handlers (typescript-sdk issue 2598), and splitting the three across two layers would let them drift. Both workarounds are isolated and will be removed when the SDK moves.

Without the extension

a2a_send_message waits for the agent to reach a terminal or interrupted state and answers inline. A task left in INPUT_REQUIRED comes back:

• as a multi-round-trip input_required result with one form elicitation, for a client that declares elicitation, which then replays the call with the answer;
• as an ordinary result whose envelope says input_required and carries the taskHandle, for any other client, which then sends the answer with that handle.

What crosses the bridge, and what does not

Parts:

filename, artifact identity and name, message and context identifiers travel in _meta["io.github.amirk-s/a2a"] on each block.