a2a-mcp/README.md

a2amcp

MCP gateway for a2acloud agents. It runs locally as a stdio MCP server and exposes deployed A2A agents as tools to Claude Code, Cursor, and other MCP clients.

This package is the local stdio gateway. It is different from the hosted OAuth MCP connector endpoints used by ChatGPT/Claude web connectors:

Local stdio gateway:        npx -y a2amcp
Remote standard MCP:        https://<agent>.a2acloud.io/mcp
Remote connector MCP:       https://<agent>.a2acloud.io/connector-mcp
Remote orchestrator MCP:    https://api.a2acloud.io/connector-mcp

Use a2amcp for editor clients that launch a local MCP server process. Use the remote /connector-mcp URL for hosted connector UIs that need OAuth login, Dynamic Client Registration, async job polling, and structured approval/input interrupts.

Quickstart

npx -y a2amcp login
npx -y a2amcp add <agent-name>
npx -y a2amcp doctor

Add it to your MCP client config:

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

Restart the client after adding or removing agents.

Commands

a2amcp login              # save control-plane credentials
a2amcp whoami             # show current account
a2amcp agents             # list agents visible to your account
a2amcp add <name>         # expose one agent through this gateway
a2amcp list               # list locally enabled agents
a2amcp remove <name>      # stop exposing an agent
a2amcp doctor             # probe enabled agents and count tools
a2amcp logout             # clear local credentials

Running a2amcp with no command starts the MCP gateway over stdio.

Hosted OAuth Connectors

ChatGPT and Claude-style hosted connectors should not run this stdio gateway. Configure them directly with the remote connector URL:

https://api.a2acloud.io/connector-mcp
https://<agent>.a2acloud.io/connector-mcp

Choose OAuth authentication. The server advertises protected-resource metadata, the client dynamically registers with Keycloak, and the browser consent flow issues tokens scoped to MCP access. Long-running connector calls return a job_id; the client should poll chat_result on the orchestrator connector or job_result on a leaf-agent connector.