Skip to main content
Glama

a2a-mcp

A light MCP server that lets an MCP client — Claude Code, Claude Desktop, Cursor, Codex — talk to other agents over the A2A (Agent-to-Agent) protocol.

  • One file, standard library only. No dependencies, no install step: python3 a2a_mcp.py.

  • A2A v1.0, with fallback to v0.3 method names and message shapes for older peers.

  • Long tasks don't break. Replies are streamed and the stream is held open in the background, so a tool call can return "still working" and the model checks back later with a2a_get_task — the remote task isn't dropped when the tool call returns. Streaming keepalives also carry tasks past proxy idle limits (verified: a 2-minute task through a Cloudflare Tunnel, whose limit is 100 s).

  • Works behind auth layers. Per-agent headers (bearer tokens, Cloudflare Access service tokens, …) with secrets pulled from environment variables or files, never stored in the client config.

Tools

Tool

What it does

a2a_list_agents

Configured agents, plus tasks sent this session

a2a_discover

Fetch an agent's Agent Card: description, skills, streaming support

a2a_send

Send a message/task and return the reply — or a task id if it's still running

a2a_get_task

Wait for / check on a task

a2a_cancel_task

Ask the agent to cancel a task

Pass context_id from a reply to a2a_send to continue the same conversation. If an agent answers input-required, reply with the same context_id and task_id.

Related MCP server: mcp-a2a-bridge

Setup

1. Get the server

git clone https://github.com/tylew/a2a-mcp ~/src/a2a-mcp

(or pipx install git+https://github.com/tylew/a2a-mcp / uvx --from git+https://github.com/tylew/a2a-mcp a2a-mcp if you prefer an a2a-mcp command on your PATH).

2. Describe your agents

~/.config/a2a-mcp/agents.json (or point A2A_MCP_CONFIG at another file, or put the same JSON in the A2A_MCP_AGENTS environment variable):

{
  "agents": {
    "hermes": {
      "url": "https://a2a.example.com",
      "description": "My Hermes agent on the home server",
      "headers": {
        "Authorization": "Bearer ${file:~/.config/a2a-mcp/hermes.token}",
        "CF-Access-Client-Id": "${CF_ACCESS_CLIENT_ID}",
        "CF-Access-Client-Secret": "${CF_ACCESS_CLIENT_SECRET}"
      },
      "timeout": 30
    }
  }
}

Field

url

Base URL. The Agent Card is read from /.well-known/agent-card.json (falls back to agent.json).

headers

Sent on every request. ${VAR} reads an environment variable, ${file:PATH} reads a file (trimmed). A missing variable or file is an error, never an empty header.

description

Shown to the model by a2a_list_agents.

timeout

Seconds for non-streaming requests (default 30).

rpc_url

Optional: override the JSON-RPC endpoint instead of taking it from the card.

The file is re-read on every call, so edits apply without restarting your client. Keep secret files chmod 600.

3. Register with your client

Claude Code

claude mcp add --scope user a2a -- python3 ~/src/a2a-mcp/a2a_mcp.py

Claude Desktop / Cursor / others (mcpServers JSON):

{
  "mcpServers": {
    "a2a": { "command": "python3", "args": ["/absolute/path/to/a2a_mcp.py"] }
  }
}

Then ask: "use a2a to ask hermes what's on my calendar tomorrow".

Example: Hermes Agent

Hermes Agent ships an A2A platform. Enable it in config.yaml:

platforms:
  a2a:
    enabled: true
    extra:
      port: 9900

and give this client its own credential in Hermes' .env:

A2A_PEER_TOKENS=claude:<long random token>
A2A_TRUSTED_PEERS=claude
A2A_PUBLIC_URL=https://a2a.example.com   # if it sits behind a proxy/tunnel

Hermes keeps listening on 127.0.0.1 only; expose it with an SSH tunnel, Tailscale, or a Cloudflare Tunnel + Access application. Messages arrive in Hermes' live agent (same memory and tools as its other platforms), passed through its prompt-injection filters as untrusted peer input.

Security notes

  • Credentials stay with their origin. Headers are only sent to the configured url's origin. If an Agent Card advertises an endpoint on a different origin it is ignored, so a card can't redirect your tokens elsewhere. Ad-hoc URLs passed directly to a tool never get configured credentials.

  • Replies are untrusted input. The server tells the model so, but treat another agent's output the way you'd treat a web page.

  • Think about what the remote agent can do. Sending a task to an agent with shell or account access is equivalent to giving the model calling this tool that access, through the remote agent's own approval rules.

  • Tasks held open in the background live as long as the MCP server process (your client session).

Development

python3 -m unittest discover -s tests -v

The tests run the real stdio server against mock v1.0 (streaming) and v0.3 (blocking) peers. Set A2A_MCP_DEBUG=1 for logs on stderr.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables BCH agents to be exposed via MCP/A2A protocols for discovery and task delegation, and allows delegation to external A2A agents.
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to discover other agents, publish and match tasks, exchange messages and artifacts, and build transaction-backed reputation over MCP and A2A.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to interact with A2A agents through four ordinary tools, translating agent discovery, messaging, task reading, and cancellation between the A2A and MCP protocols, with support for the tasks extension.
      43 npm
      2
      Apache 2.0