Skip to main content
Agents call tools and APIs that return structured data, and every tool reinvents how to present that data in chat. widgentic replaces the per-tool UI with one contract and a small set of generic widgets, so any MCP-aware host can render rich tool output.

​
What it is

​
A contract

Every widget is one normalized payload:
kind names the widget, data is the value to show, hints steer presentation (columns, layout, images, links, display formats) and meta carries chrome such as a title. Payloads are validated before anything renders, and renderers ignore fields they do not know, so the contract can grow without breaking hosts. See the payload contract.

​
A catalog of generic widgets

Five kinds are built in: card, table, tree, custom, and group, which shows several widgets of mixed kinds in one response with layout hints. On top of them you add your own kinds as templates: serializable JSON that binds data into elements with bind, each and when. Templates are data, not code — they contain no expressions and no scripts, which is what makes them safe for untrusted authors. Themes are JSON too: a registry of --wg-* tokens plus your own x-* variables. See the template DSL and themes.

​
An MCP server

widgentic is itself an MCP server. The hosted endpoint is https://mcp.widgentic.dev/mcp, and the same assembly ships in @widgentic/mcp so you can run your own. It exposes seven tools: With an API key the catalog is yours: your saved widgets, themes, schemas and actions are composed on top of the built-ins for every request. See per-principal catalogs.

​
Designers

Widgets, themes, schemas and actions are authored in browser-based designers with live validation and a preview mounted through the real render pipeline. They are hosted in the app at widgentic.dev/app, where saving puts the entry straight into your MCP catalog, and they ship as embeddable factories and custom elements in @widgentic/designer. See the widget designer.

​
What it is not

  • Not a charting library. Widgets show records, fields, rows and trees; there is no chart kind.
  • Not a forms library. Widgets can carry buttons and links that propose a message or call a declared URL, with arguments resolved from the widget’s data at render time; they do not collect input from the reader.
  • Not a UI framework. The packages have zero runtime dependencies and render plain DOM from a pure render tree; you bring whatever host you like.
  • No agent write path. Agents cannot save anything. They read the catalog through the tools and draft import JSON using get_authoring_guide; you import, validate and save in the designer. Registration over MCP deliberately does not exist, because API keys travel into third-party hosts and prompt-injectable contexts. See authoring with an agent and the trust model.

​
Where widgets appear

Hosts that implement MCP Apps mount widgets inline in the conversation, in a sandboxed iframe fed from the render result; the widget content stays script-free with no external references. Every other host receives the same result as text. See inline rendering and the host matrix.