MCP tools

Descriptions are the exact text advertised to agents over tools/list; they carry the steering, so they are longer than a reference usually is.

list_widgets

List the available widget kinds with their purpose, expected data shape, an example data value, and supported hints. Call this first to decide which widget fits your data, then call render_widget. ALWAYS call it again when the user asks what widgets are available or says they saved/imported something in the designer — catalogs are served per API key and change between calls; never answer from an earlier listing.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

list_schemas

List the user’s saved shared data schemas — name, label, description, and the schema object itself. Call this when the user asks for a widget built on one of their schemas (‘use my person schema’): bind the schema’s actual properties and set the widget’s descriptor.dataSchemaRef to the schema’s NAME instead of copying the schema inline — an inline copy forks the moment the user edits the shared one. Served per API key, like list_widgets; anonymous keys see an empty list.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

list_themes

List the themes registered on this server — name, label, description and token map for each. Pass any listed name as render_widget’s ‘theme’ input instead of composing tokens by hand.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

list_theme_tokens

List the theming vocabulary for render_widget’s ‘theme’ input: every token name with its light-mode default, ready-made presets (e.g. dark), and the value rules. Call this before building a theme.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

get_authoring_guide

Get the complete guide for AUTHORING widget and theme JSON: entry shapes, the template DSL’s node forms and safety rules, identifier rules and reserved kinds, style and schema constraints, theme tokens, and per-user limits. Call this before drafting a custom widget or theme for your user — you draft the JSON, your user imports and saves it in the designer at widgentic.dev (there is no registration tool).

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

render_widget

Validate and render a widget. Returns the rendered HTML plus an embedded widgentic payload block that widgentic-aware hosts can mount natively. On invalid input, returns a structured error describing what to correct. To show several widgets at once, render ONE ‘group’ (items of mixed kinds, layout hints) instead of calling repeatedly.

{
  "type": "object",
  "properties": {
    "widget": {
      "type": "string",
      "description": "Widget kind id, as returned by list_widgets."
    },
    "data": {
      "type": [
        "array",
        "object",
        "string",
        "number",
        "boolean",
        "null"
      ],
      "description": "Widget data matching the kind's documented dataShape."
    },
    "hints": {
      "type": "object",
      "description": "Optional renderer hints (see the kind's hints doc)."
    },
    "meta": {
      "type": "object",
      "description": "Optional metadata (title, subtitle, source, ...)."
    },
    "format": {
      "type": "string",
      "enum": [
        "both",
        "html",
        "widget",
        "page",
        "app"
      ],
      "description": "Output selection (default 'both'): 'html' fragment only (no payload block — plain consumers only; strands widgentic-aware hosts), 'widget' payload block only, 'page' a self-contained styled HTML document (plus the payload block), 'app' the page as a ui:// text/html resource for inline display — Apps hosts use the html resource, native hosts the payload block."
    },
    "theme": {
      "type": [
        "object",
        "string"
      ],
      "description": "Either a registered theme NAME (discover with list_themes — the simplest path, e.g. 'dark') or a token map of bare token names to CSS string values, always strings ('6px', not 6). When the user refers to a theme by name ('use nord dark'), pass the NAME — their saved themes live server-side and are the source of truth; do NOT reconstruct the tokens from memory (your copy drifts the moment they edit it). Inline maps are for one-off, unsaved styling. Discover tokens, defaults, and presets with list_theme_tokens; author extras as 'x-<name>' custom variables. Applied to 'page' output and embedded in the widget payload for native hosts on every format."
    }
  },
  "required": [
    "widget",
    "data"
  ],
  "additionalProperties": false
}

execute_action

Called by widgentic widgets, not by agents: runs a widget’s bound http action (a stored, author-declared request) server-side and returns the re-rendered widget. Requires a key with the ‘execute’ scope. Agents should call render_widget instead.

{
  "type": "object",
  "properties": {
    "widget": {
      "type": "string",
      "description": "The rendered widget's kind."
    },
    "action": {
      "type": "string",
      "description": "Binding identifier: the element's dotted template path, or \"load\"."
    },
    "args": {
      "type": "object",
      "description": "Arguments as resolved in the element's descriptor.",
      "additionalProperties": true
    },
    "payload": {
      "type": "object",
      "description": "The widget's current payload { kind, data, hints?, meta? }.",
      "additionalProperties": true
    },
    "at": {
      "type": "string",
      "description": "Inside a group: dotted path of the item payload within 'payload' (e.g. data.items.2)."
    },
    "item": {
      "type": "string",
      "description": "Inside a group: the item's kind."
    }
  },
  "required": [
    "widget",
    "action",
    "payload"
  ],
  "additionalProperties": false
}

Generated from the validators

API export index

list_widgets

list_schemas

list_themes

list_theme_tokens

get_authoring_guide

render_widget

execute_action

​list_widgets

​list_schemas

​list_themes

​list_theme_tokens

​get_authoring_guide

​render_widget

​execute_action

list_widgets

list_schemas

list_themes

list_theme_tokens

get_authoring_guide

render_widget

execute_action