98 lines
3.1 KiB
Markdown
98 lines
3.1 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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
|
|
|
|
```bash
|
|
npx -y a2amcp login
|
|
npx -y a2amcp search "security evidence"
|
|
npx -y a2amcp add <agent-name>
|
|
npx -y a2amcp doctor
|
|
```
|
|
|
|
Add it to your MCP client config:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"a2a": {
|
|
"command": "npx",
|
|
"args": ["-y", "a2amcp"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Restart the client after adding or removing agents.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
a2amcp login # sign in through Keycloak and save OAuth tokens
|
|
a2amcp whoami # show current account
|
|
a2amcp agents # list agents visible to your account
|
|
a2amcp search [query] # search visible agents by text, tag, or skill
|
|
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.
|
|
|
|
The gateway also exposes local management tools to MCP clients:
|
|
|
|
```text
|
|
a2a_search_agents # search visible agents from inside the MCP client
|
|
a2a_add_agent # enable one matching agent dynamically
|
|
a2a_list_enabled_agents # show agents currently exposed by this gateway
|
|
```
|
|
|
|
After `a2a_add_agent`, clients that support tool-list change notifications can
|
|
refresh tools immediately. Other clients may need a manual tool refresh or
|
|
restart.
|
|
|
|
`a2amcp login` uses Keycloak Authorization Code + PKCE. It starts a local
|
|
loopback callback server, opens the browser, exchanges the code for a Keycloak
|
|
access token, and stores the token in `~/.a2a/credentials.json`. For headless
|
|
machines, pass an existing Keycloak access token:
|
|
|
|
```bash
|
|
a2amcp login --token "$KEYCLOAK_ACCESS_TOKEN"
|
|
```
|
|
|
|
## Hosted OAuth Connectors
|
|
|
|
ChatGPT and Claude-style hosted connectors should not run this stdio gateway.
|
|
Configure them directly with the remote connector URL:
|
|
|
|
```text
|
|
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.
|