a2a cloud
Deploy 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 instead?
MCP gateway

Use a2a agents in your editor.

a2amcp is a tiny Model Context Protocol gateway. Runs on your machine, exposes private or public a2a cloud agents to Claude Code, Cursor, Windsurf, and other MCP clients. Each call still goes through the agent's hosted identity, auth, file grants, receipt trail.

Node 18.17+macOS · Linux · Windowsstdio MCPApache-2.0
setupa2amcp
$

Quick start

1
Log in once

Same credentials as the Python a2a CLI; token in ~/.a2a/credentials.json.

npx -y a2amcp login
2
Add agents
npx -y a2amcp add greeter
npx -y a2amcp add research-agent

Browse all public and private agents your account can access: npx -y a2amcp agents.

3
Wire into your MCP client (one time)

Add this block to your client's MCP config and restart the editor. Done once — adding new agents later just edits a local file the gateway re-reads on each call.

{
  "mcpServers": {
    "a2a": { "command": "npx", "args": ["-y", "a2amcp"] }
  }
}

Per-client setup

Claude Code
~/.claude/mcp.json

Or run `claude mcp add a2a -- npx -y a2amcp`.

Cursor
Settings → MCP → Add new server

Paste the JSON block above as the server definition.

Windsurf / Cline / Continue
MCP servers config (varies)

Any stdio MCP client works. Same JSON block.

Managing agents

Gateway reads ~/.a2a/mcp.json on every tools/list call — no gateway restart, only editor restart 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. Calls execute in the hosted runtime where permissions and proof are enforced — not as local scripts.

  Claude Code / Cursor
        │  stdio MCP
        ▼
   a2amcp 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 on every upstream call.

What carries through

  • Agent identity
    Tools map back to deployed agent, skill, version, AgentCard.
  • Account access
    Private agents stay private. Gateway uses your a2a login.
  • Hosted runtime
    Execution in the cloud agent service, not inside your editor.
  • Proof trail
    Tool calls produce receipts, artifacts, file ops, evals, review history.

Remote MCP (no local install)

If your client supports Streamable HTTP MCP, skip the gateway and connect directly to a single agent:

{
  "mcpServers": {
    "greeter": { "type": "http", "url": "https://greeter.a2acloud.io/mcp" }
  }
}

Trade-off: one MCP server per agent, manage auth headers yourself. Gateway is better when you have more than one.

Troubleshooting

  • Tools missing? Run a2a-mcp doctor — pings every enabled agent and reports per-agent tool counts.
  • 401 from upstream? Token expired. Re-run a2a-mcp login.
  • Agent not in list? Probably still building — a2a-mcp agents shows status.
  • Pin a version? Use npx -y a2amcp@0.1.2 in client config.
Browse the registry →
Deploy your own agentMCP docs ↗