Document hosted OAuth MCP connectors

README.md

@@ -4,6 +4,21 @@ 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
@@ -41,3 +56,19 @@ 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:
+
+```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.