Install the a2a CLI
@a2a/mcp is a tiny Model Context Protocol gateway that runs on your machine and exposes any agents you've deployed to a2a cloud to Claude Code, Cursor, Windsurf, and other MCP clients.
Quick start
Same credentials as the Python a2a CLI; the token is written to ~/.a2a/credentials.json.
npx -y @a2a/mcp login
npx -y @a2a/mcp add greeter npx -y @a2a/mcp add research-agent
Browse all your deployed agents: npx -y @a2a/mcp agents.
Add this block to your client's MCP config and restart the editor. You only do this once — adding new agents later just edits a local file that the gateway re-reads on each call.
{
"mcpServers": {
"a2a": { "command": "npx", "args": ["-y", "@a2a/mcp"] }
}
}Per-client setup
Or run `claude mcp add a2a -- npx -y @a2a/mcp`.
Paste the JSON block above as the server definition.
Any client that speaks stdio MCP works. Same JSON block.
Managing agents
The gateway reads ~/.a2a/mcp.json on every tools/list call — you never need to restart the gateway, only the editor (so it re-asks for the tool list).
| Command | What it does |
|---|---|
| a2a-mcp list | Show enabled agents (local). |
| a2a-mcp agents | Show every agent your account can see (control plane). |
| a2a-mcp add <name> | Enable an agent. Looks up its public URL. |
| a2a-mcp remove <name> | Drop an agent from the gateway. |
| a2a-mcp doctor | Probe each /mcp endpoint and report tool counts. |
| a2a-mcp whoami | Show the logged-in account. |
| a2a-mcp logout | Forget the cached token. |
How it works
Each deployed agent on a2a cloud serves MCP at POST /mcp on its public URL. The gateway aggregates many agents into a single MCP server your editor connects to over stdio:
Claude Code / Cursor
│ stdio MCP
▼
@a2a/mcp gateway ── reads ~/.a2a/mcp.json
│ Streamable HTTP + Bearer token
▼
greeter.a2acloud.io/mcp research.a2acloud.io/mcp ...Skills appear as tools named <agent>__<skill>. Auth uses the bearer token from ~/.a2a/credentials.json for every upstream call.
Remote MCP (no local install)
If your client supports Streamable HTTP MCP, you can skip the gateway and connect directly to a single agent:
{
"mcpServers": {
"greeter": { "type": "http", "url": "https://greeter.a2acloud.io/mcp" }
}
}The trade-off: one MCP server per agent, and you manage auth headers yourself. The gateway is better when you have more than one.
Troubleshooting
- Tools missing in editor? Run a2a-mcp doctor — it pings every enabled agent and reports per-agent tool counts.
- 401 from upstream? Token expired. Re-run a2a-mcp login.
- Agent not in list? It probably hasn't finished building yet — a2a-mcp agents shows status.
- Pin a version? Use npx -y @a2a/mcp@0.1.0 in your client config.