Skip Navigation Links

MCP A2UI Widgets Guide

Guide how an MCP server returns A2UI widgets that Flip Ask AI renders in the chat with the Flip Swirl catalog

This guide explains how an MCP server connected to a Flip Ask AI custom agent returns a widget instead of only text. Ask AI renders the widget in the chat with Flip's own design system, Swirl. Widgets follow A2UI at protocol version v0.9, transported as described in A2UI over MCP. Ask AI renders a subset of A2UI, defined by the Swirl catalog.

The guide is written for the team implementing the MCP server. How to connect the MCP server to a custom agent is described in How to Set Up Custom Agents with MCP Servers.

How it works

  1. A tool declares in its definition that it can return a widget.
  2. When Ask AI calls the tool, it tells the MCP server which catalog it renders.
  3. The tool result carries the widget as A2UI messages in an embedded resource, next to the usual text.
  4. Ask AI validates the widget against the Swirl catalog. The custom agent hands the widget to Ask AI's chat agent, which shows it to the user with its answer and does not repeat in text what the widget shows.

The text blocks of the tool result still reach the language model. A widget is never the only place where the model learns what the tool found.

The Swirl catalog

The catalog is public as a JSON Schema document, without authentication:

https://{domain}/a2ui/v0.9/swirl-catalog.json

{domain} is any Flip domain, for example the domain your organisation opens Flip on. The document follows the A2UI catalog format: components holds one schema per component, functions one schema per function call, and $defs the shared types. It is built from the same definitions Ask AI validates widgets with, so it always matches what Ask AI accepts.

The catalog ID is swirl-catalog. It is a plain identifier, not the URL above.

Step 1: Declare the widget on the tool

Add _meta.ui to the tool definition in your tools/list response:

FieldMeaning
resourceUriIdentifies the widget. It must start with a2ui://. For a template, it is also the resource Ask AI reads.
mimeTypeAlways application/a2ui+json.

A tool without _meta.ui is treated as text, even if its result holds an A2UI resource. A tool that declares _meta.ui may still answer with text alone, for example when there is nothing to show. That call then has no widget.

Step 2: Read the client capabilities

Every tools/call from Ask AI carries the catalogs it renders in _meta.a2ui.clientCapabilities:

If you serve other A2UI clients too, use this to choose the Swirl catalog for Ask AI. Ask AI does not accept inline catalogs.

Step 3: Return the widget

Return the widget as an embedded resource of mime type application/a2ui+json. Its text is a JSON list of A2UI v0.9 messages, serialized as a string. Put a short text block next to it that summarises the result in a sentence. The model reads that text, not the widget.

Decoded, the text above holds three messages. Together they describe one complete widget, a surface in A2UI terms:

MessagePurpose
createSurfaceStarts the surface. catalogId must be swirl-catalog.
updateComponentsThe component tree, as a flat list. Components reference their children by id.
updateDataModelThe data the components read through bindings.

All three messages must name the same surfaceId. Any string works.

Templates

When the layout is the same on every call, you can serve it once as a template and send only the data with each result.

  1. Serve the createSurface and updateComponents messages as an MCP resource at the tool's resourceUri, with mime type application/a2ui+json. The resource's text is the JSON list of messages, as in a tool result.
  2. Return only the updateDataModel message in the tool result, with the same surfaceId as the template.

Ask AI reads the template with resources/read the first time a result needs it, and reuses it for the rest of that agent run. A result that contains its own createSurface is complete and does not use the template.

Components

Ask AI renders the components the Swirl catalog defines, for example Text, Card, Column, Row, Divider and Tag. The catalog may define more components than this guide names. It is the complete list, with each component's properties and allowed values. Every component has an id and its component name. Leave out an optional property instead of sending null.

Where a property is a string, you can send:

  • a literal, e.g. "Printer offline"
  • a data binding, e.g. { "path": "/title" }
  • a function call, see Functions

Lists

children of a Column or Row is either a list of component ids, or a template that repeats one component for every entry of a list in the data model:

Inside the repeated component and its descendants, a path without a leading / is relative to the current entry. A path with a leading / still starts at the root of the data model. This widget lists vacations, one card per entry of /entries:

Functions

Dates and times are formatted in the viewer's locale and timezone, so send them as ISO 8601 values and let a function format them.

FunctionArgumentsResult
formatDateTimevalue: an ISO 8601 instant, e.g. 2026-10-26T09:30:00ZDate and time in the viewer's locale and timezone.
formatDateRangestart, end: ISO 8601 dates, e.g. 2026-11-02The period in the viewer's locale. A range that starts and ends on the same day shows as that one day.

Each argument is a literal, a data binding or another function call. A2UI's translate and basic functions are not available. Ask AI does not translate a widget, so send finished text.

Rules a widget must follow

  • One surface per tool result, with catalogId swirl-catalog. Any other catalog is rejected.
  • The data model is set as a whole. updateDataModel must have path / and an object as value. Updates below the root are rejected. If a result holds several, the last one wins.
  • The tree is complete. One component has the id root, ids are unique, and every child reference resolves to a component.
  • Only catalog components and properties. A component or property outside the catalog is rejected.
  • Size. At most 200 components, and at most 64 KiB of A2UI text in the tool result and in the template each.

⚠️ Widgets are display only

Button, TextField, DatePicker and other interactive components are rejected, and no user action from a widget reaches your MCP server. Let the user act through the conversation and your tools instead.

When a widget is rejected

The tool call still succeeds. The user sees no widget, and the model gets the tool's text with a note that the visual result could not be shown, so it answers in text. Ask AI does not report the reason to your server or to the user.

A result with isError: true is not a widget at all: the model gets the whole result as text, including any A2UI resources, and may retry the call.

Testing a widget

  • Validate the messages against the Swirl catalog with any JSON Schema 2020-12 validator. Check the rules that the schema does not express, such as the root component and the size limits, in your own tests.
  • Check the text without the widget. Ask a question whose answer needs the tool, and read the answer as if the widget were missing. The text block must carry the facts.
  • Try it end to end in a test organisation: connect the MCP server to a custom agent and ask a question that makes the agent call the tool.

Additional resources


For questions or assistance, please contact your Customer Success representative.