Skip to main content
Widgets let your MCP server return interactive UI that renders directly inside the AI conversation. Instead of plain text, the user sees buttons, forms, charts, or any HTML/React component.

How Widgets Work

When a tool returns a widget, the MCP client renders it inline:

Defining Widgets

@app.tool()
def show_products(query: str) -> dict:
    """Search and display products in an interactive grid."""
    products = db.search(query)
    return {
        "products": products,
        "_widget": {
            "type": "product-grid",
            "data": products,
        }
    }
Widget support depends on the MCP client. Clients that don’t support widgets will fall back to showing the raw JSON response.

Use Cases

E-Commerce

Product grids, cart summaries, checkout forms with payment inputs.

Dashboards

Real-time charts, KPI cards, data tables with sorting and filtering.

Forms

Multi-step forms, file uploads, signature capture.

Maps

Location pickers, route visualization, geospatial data display.

Widgets + Stages

Widgets are especially powerful with staged workflows. Each stage can present a different UI:
StageWidgetUser sees
BrowseProduct gridBrowsable catalog with filters
CartCart summaryItems with quantities and remove buttons
CheckoutPayment formCredit card input and order confirmation