From 820bba451efa573fb09e42cd21f7dcc9ec8069cf Mon Sep 17 00:00:00 2001 From: Rajhans Jadhao Date: Sun, 15 Feb 2026 13:44:42 +0530 Subject: [PATCH] docs(protocol): define MCP transport binding for A2UI and align MCP sample payload to messages[] --- samples/agent/adk/mcp/server.py | 8 +++-- specification/v0_10/docs/a2ui_protocol.md | 42 ++++++++++++++++++++++- specification/v0_9/docs/a2ui_protocol.md | 42 ++++++++++++++++++++++- 3 files changed, 87 insertions(+), 5 deletions(-) diff --git a/samples/agent/adk/mcp/server.py b/samples/agent/adk/mcp/server.py index 19a9e6af3..c8dc9027f 100644 --- a/samples/agent/adk/mcp/server.py +++ b/samples/agent/adk/mcp/server.py @@ -24,6 +24,8 @@ from starlette.requests import Request from a2ui.extension.a2ui_schema_utils import wrap_as_json_array +A2UI_MCP_MESSAGES_KEY = "messages" + def load_a2ui_schema() -> dict[str, Any]: current_dir = pathlib.Path(__file__).resolve().parent @@ -80,7 +82,7 @@ def main(port: int, transport: str) -> int: @app.call_tool() async def handle_call_tool(name: str, arguments: dict[str, Any]) -> dict[str, Any]: if name == "get_recipe_a2ui": - return {"events": recipe_a2ui_json} + return {A2UI_MCP_MESSAGES_KEY: recipe_a2ui_json} if name == "send_a2ui_user_action": return {"response": f"Received A2UI user action", "args": arguments} @@ -102,8 +104,8 @@ async def list_tools() -> list[types.Tool]: # TODO fix this in MCP SDK outputSchema={ "type": "object", - "properties": {"events": a2ui_schema}, - "required": ["events"], + "properties": {A2UI_MCP_MESSAGES_KEY: a2ui_schema}, + "required": [A2UI_MCP_MESSAGES_KEY], "additionalProperties": False, }, ), diff --git a/specification/v0_10/docs/a2ui_protocol.md b/specification/v0_10/docs/a2ui_protocol.md index 75220cd87..88edc32c2 100644 --- a/specification/v0_10/docs/a2ui_protocol.md +++ b/specification/v0_10/docs/a2ui_protocol.md @@ -107,11 +107,51 @@ A2A is uniquely capable of handling remote agent communication, and can also pro **[AG-UI](https://docs.ag-ui.com/introduction)** is also an excellent transport option for A2UI Agent–User Interaction protocol. AG UI provides convenient integrations into many agent frameworks and frontends. AG UI provides low latency and shared state message passing between front ends and agentic backends. +#### MCP (Model Context Protocol) binding + +A2UI over MCP uses a single JSON object payload, transported through MCP tool results or MCP resources. + +- **Message container**: The canonical payload shape is an object with a `messages` field. +- **Schema binding**: + - For server-to-client UI updates, `messages` MUST validate against [server_to_client_list.json](../json/server_to_client_list.json). + - For client-to-server events, `messages` MUST validate against [client_to_server_list.json](../json/client_to_server_list.json). +- **Aggregation and ordering**: `messages` is an ordered batch. Receivers MUST process messages in order. +- **Error handling**: If a message in the batch fails validation or application, receivers SHOULD report/log that message-level failure and SHOULD continue processing later messages in the same batch. +- **Tool vs. resource usage**: + - Use MCP **tools** for request/response flows (initial render requests and user actions). + - Use MCP **resources** (including subscriptions/updates) for long-lived UI surfaces that are updated over time. +- **Post-creation updates**: UIs remain mutable after first render. Additional batches MAY contain `updateComponents`, `updateDataModel`, and `deleteSurface` for previously created `surfaceId`s. +- **Catalog negotiation**: Before the first `createSurface`, clients MUST provide `a2uiClientCapabilities` that conform to [`a2ui_client_capabilities.json`]. Servers MUST choose a compatible catalog and set it in `createSurface.catalogId`. + +Example MCP payload: + +```json +{ + "messages": [ + { + "version": "v0.10", + "createSurface": { + "surfaceId": "main", + "catalogId": "https://a2ui.org/specification/v0_10/standard_catalog.json" + } + }, + { + "version": "v0.10", + "updateComponents": { + "surfaceId": "main", + "components": [ + { "id": "root", "component": "Text", "text": "Hello from MCP" } + ] + } + } + ] +} +``` + #### Other transports A2UI can also be carried over: -- **[MCP (Model Context Protocol)](https://modelcontextprotocol.io/docs/getting-started/intro)**: Delivered as tool outputs or resource subscriptions. - **[SSE](https://en.wikipedia.org/wiki/Server-sent_events) with [JSON RPC](https://www.jsonrpc.org/)**: Standard server-sent events for web integrations that support streaming, and JSON RPC for client-server communication. - **[WebSockets](https://en.wikipedia.org/wiki/WebSocket)**: For bidirectional, real-time sessions. - **[REST](https://cloud.google.com/discover/what-is-rest-api?hl=en)**: For simple use case, REST APIs will work but lack streaming capabilities. diff --git a/specification/v0_9/docs/a2ui_protocol.md b/specification/v0_9/docs/a2ui_protocol.md index fca2262ba..f9a73666e 100644 --- a/specification/v0_9/docs/a2ui_protocol.md +++ b/specification/v0_9/docs/a2ui_protocol.md @@ -112,11 +112,51 @@ A2A is uniquely capable of handling remote agent communication, and can also pro **[AG-UI](https://docs.ag-ui.com/introduction)** is also an excellent transport option for A2UI Agent–User Interaction protocol. AG UI provides convenient integrations into many agent frameworks and frontends. AG UI provides low latency and shared state message passing between front ends and agentic backends. +#### MCP (Model Context Protocol) binding + +A2UI over MCP uses a single JSON object payload, transported through MCP tool results or MCP resources. + +- **Message container**: The canonical payload shape is an object with a `messages` field. +- **Schema binding**: + - For server-to-client UI updates, `messages` MUST validate against [server_to_client_list.json](../json/server_to_client_list.json). + - For client-to-server events, `messages` MUST validate against [client_to_server_list.json](../json/client_to_server_list.json). +- **Aggregation and ordering**: `messages` is an ordered batch. Receivers MUST process messages in order. +- **Error handling**: If a message in the batch fails validation or application, receivers SHOULD report/log that message-level failure and SHOULD continue processing later messages in the same batch. +- **Tool vs. resource usage**: + - Use MCP **tools** for request/response flows (initial render requests and user actions). + - Use MCP **resources** (including subscriptions/updates) for long-lived UI surfaces that are updated over time. +- **Post-creation updates**: UIs remain mutable after first render. Additional batches MAY contain `updateComponents`, `updateDataModel`, and `deleteSurface` for previously created `surfaceId`s. +- **Catalog negotiation**: Before the first `createSurface`, clients MUST provide `a2uiClientCapabilities` that conform to [`a2ui_client_capabilities.json`]. Servers MUST choose a compatible catalog and set it in `createSurface.catalogId`. + +Example MCP payload: + +```json +{ + "messages": [ + { + "version": "v0.9", + "createSurface": { + "surfaceId": "main", + "catalogId": "https://a2ui.org/specification/v0_9/standard_catalog.json" + } + }, + { + "version": "v0.9", + "updateComponents": { + "surfaceId": "main", + "components": [ + { "id": "root", "component": "Text", "text": "Hello from MCP" } + ] + } + } + ] +} +``` + #### Other transports A2UI can also be carried over: -- **[MCP (Model Context Protocol)](https://modelcontextprotocol.io/docs/getting-started/intro)**: Delivered as tool outputs or resource subscriptions. - **[SSE](https://en.wikipedia.org/wiki/Server-sent_events) with [JSON RPC](https://www.jsonrpc.org/)**: Standard server-sent events for web integrations that support streaming, and JSON RPC for client-server communication. - **[WebSockets](https://en.wikipedia.org/wiki/WebSocket)**: For bidirectional, real-time sessions. - **[REST](https://cloud.google.com/discover/what-is-rest-api?hl=en)**: For simple use case, REST APIs will work but lack streaming capabilities.