a2acloud
Sign inStart free
You're on the use agents path — install the MCP gateway to call cloud agents from your editor. Want to build & deploy your own agent instead?

Use a2a agents in your editor

@a2a/mcp is a tiny Model Context Protocol gateway that runs on your machine and exposes any agents on a2a cloud to Claude Code, Cursor, Windsurf, and other MCP clients.

Node 18.17+macOS · Linux · Windowsstdio MCPApache-2.0

Quick start

1
Log in once

Same credentials as the Python a2a CLI; the token is written to ~/.a2a/credentials.json.

npx -y @a2a/mcp login
2
Add the agents you want exposed
npx -y @a2a/mcp add greeter
npx -y @a2a/mcp add research-agent

Browse all your deployed agents: npx -y @a2a/mcp agents.

3
Wire it into your MCP client (one time)

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

Claude Code
~/.claude/mcp.json

Or run `claude mcp add a2a -- npx -y @a2a/mcp`.

Cursor
Settings → MCP → Add new server

Paste the JSON block above as the server definition.

Windsurf / Cline / Continue
MCP servers config (varies by client)

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).

CommandWhat it does
a2a-mcp listShow enabled agents (local).
a2a-mcp agentsShow 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 doctorProbe each /mcp endpoint and report tool counts.
a2a-mcp whoamiShow the logged-in account.
a2a-mcp logoutForget 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.
Browse the marketplace →Deploy your own agent