MCP Widget Authoring Skill

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:

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

Key components:

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

Widget Template Format

Create templates in config/ui_widget_templates/:

{
  "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

class 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:

{
  "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

Agent Skills: MCP Widget Authoring