---

name: mcp-widget-authoring description: Create ChatKit UI widgets in MCP servers. Use when building visual components that render in ChatKit from tool results. Covers widget templates with JSON Schema validation, WidgetTemplateService for hydration, BaseMCPServer patterns, and multi-channel support for Slack. Triggers on widget template, MCP widget, tool result widget, or ChatKit Card.

MCP Widget Authoring

Create visual widgets that render in ChatKit from MCP tool results.

Quick Start

Widgets flow from MCP server → tool result → ChatKit rendering:

CopyMCP Server Tool → WidgetTemplateService.hydrate_for_tool_result() → ui:// resource → ChatKit

Key components:

1. Widget template file (.widget or .yml)
2. WidgetTemplateService for hydration
3. BaseMCPServer for tool registration
4. MCP-compliant tool result format

Widget Template Format

Create templates in config/ui_widget_templates/:

Copy{
  "version": "1.0",
  "name": "weatherCurrent",
  "copy_text": "Weather in {{location}}: {{temperature}}",
  "template": "{\"type\":\"Card\",\"children\":[{\"type\":\"Text\",\"value\":\"{{location}}\"}]}",
  "jsonSchema": {
    "type": "object",
    "properties": {
      "location": { "type": "string" },
      "temperature": { "type": "string" }
    },
    "required": ["location", "temperature"]
  }
}

Using in MCP Server

Copyclass WeatherMCPServer::Server < BaseMCPServer
  server_name "weather"
  widget_resource "ui://widgets/weather/{instance_id}",
    name: "Weather Widget",
    description: "Displays current weather"

  tool :get_current_weather

  def get_current_weather(location:, unit: "celsius")
    weather_data = fetch_weather(location, unit)

    WidgetTemplateService.hydrate_for_tool_result(
      template: :weatherCurrent,
      data: { location: location, temperature: "#{weather_data[:temp]}#{unit_symbol}" },
      text: "Current weather in #{location}: #{weather_data[:temp]}",
      tool_name: "weather"
    )
  end
end

Result Format

The tool result embeds a ui:// resource:

Copy{
  "content": [
    { "type": "text", "text": "Current weather in Toronto: 72°F" },
    {
      "type": "resource",
      "resource": {
        "uri": "ui://widgets/weather/abc123",
        "mimeType": "application/vnd.ui.widget+json",
        "text": "{\"widget\":{...},\"copy_text\":\"...\"}"
      }
    }
  ],
  "isError": false
}

Reference Files

For detailed patterns, see:

• templates.md - Widget template format and JSON Schema
• hydration.md - WidgetTemplateService usage patterns
• mcp-server.md - BaseMCPServer integration
• components.md - Available ChatKit components (Card, Text, Image, etc.)
• multi-channel.md - Slack Work Objects and Block Kit