widget-studio

An agent capability for creating and displaying rich UI widgets (cards, dashboards, task lists, charts, forms, tables) inline in conversations — packaged as a Claude Code plugin, an Agent Skill, standalone CLI scripts, and an MCP server with MCP Apps support. Widgets use the ChatKit widget JSON format, generated by prompting Widget Studio's hosted generator; the JSON is edited directly only for small tweaks.

Architecture

The MCP server is optional — the skills + CLI deliver the full generate→render loop on their own. The server is the layer that adds interactive inline widgets in MCP Apps hosts. Each host gets the richest rendering it supports:

Rendering paths

• MCP Apps hosts (Claude Desktop, claude.ai, ChatGPT): interactive iframe via the standard _meta.ui.resourceUri → ui://widget-studio/widget.html, a fully self-contained HTML renderer (CSP-safe, light/dark, actions post back to chat). Legacy openai/outputTemplate alias included for older ChatGPT builds.

• Non-UI MCP clients (Claude Code CLI, others): the server detects the missing MCP Apps capability at initialize and attaches a PNG image of the widget to the tool result instead (see PNG rendering). Override with WIDGET_STUDIO_IMAGE=auto|always|never.

• No MCP at all: widget-render (scripts/render-widget.mjs) produces the same PNG or a self-contained HTML preview from a widget JSON file.

Related MCP server: mcp-interactive-ui-server

Install

Note: the npx forms and one-click badges below go live with the first npm release of widget-studio-mcp. Until then, use the from-source form — everything else is identical.

As a Claude Code plugin (recommended for Claude)

/plugin marketplace add ericlewis/widget-studio-mcp
/plugin install widget-studio@widget-studio

The plugin registers the MCP server, puts widget-generate/widget-render/widget-export on PATH, and installs the skill family (/widget-studio:make, :tweak, :preview, :doctor). dist/ ships self-contained bundles — no npm install needed.

MCP server, per host

claude mcp add widget-studio -- npx -y widget-studio-mcp@latest

claude_desktop_config.json (Settings → Developer → Edit Config):

{ "mcpServers": { "widget-studio": { "command": "npx", "args": ["-y", "widget-studio-mcp@latest"] } } }

Use the install badge above, or .cursor/mcp.json:

{ "mcpServers": { "widget-studio": { "command": "npx", "args": ["-y", "widget-studio-mcp@latest"] } } }

code --add-mcp '{"name":"widget-studio","command":"npx","args":["-y","widget-studio-mcp@latest"]}'

codex mcp add widget-studio -- npx -y widget-studio-mcp@latest

Or ~/.codex/config.toml:

[mcp_servers.widget-studio]
command = "npx"
args = ["-y", "widget-studio-mcp@latest"]

As an extension (bundles the MCP server and skills):

gemini extensions install https://github.com/ericlewis/widget-studio-mcp

~/.codeium/windsurf/mcp_config.json:

{ "mcpServers": { "widget-studio": { "command": "npx", "args": ["-y", "widget-studio-mcp@latest"] } } }

goose session --with-extension "npx -y widget-studio-mcp@latest"

amp mcp add widget-studio -- npx -y widget-studio-mcp@latest

ChatGPT connects to remote MCP servers only. Run the HTTP transport behind a tunnel or deploy, then add the URL under Settings → Connectors (developer mode):

npx -y widget-studio-mcp@latest --http 3400   # stateless streamable HTTP, POST /mcp

ChatGPT implements the MCP Apps standard natively, so widgets render interactively; in --http mode the server also always attaches the PNG. Bridge for stdio-only hosts hitting a remote: npx -y mcp-remote https://your-host/mcp.

git clone https://github.com/ericlewis/widget-studio-mcp && cd widget-studio-mcp
npm install && npm run build
claude mcp add widget-studio -- node "$(pwd)/dist/index.js"   # or the equivalent for your host

PNG rendering

Built in — pure JS/WASM (satori + resvg with bundled Inter fonts). No browser, no playwright/puppeteer, no native dependencies, nothing to install.

Develop

npm run build   # typecheck + bundle the iframe app and self-contained server into dist/
npm test        # protocol smoke test (incl. one real API generation)
npm run eval    # render golden fixtures to PNG + offline protocol checks

Manual preview of any widget JSON:

node scripts/render-widget.mjs --in evals/golden/sales-dashboard.json --png dashboard.png
node scripts/render-widget.mjs --in evals/golden/sales-dashboard.json --html dashboard.html

dist/ is committed on purpose: plugin installs copy the repo as-is, so the bundles must ship prebuilt. Rebuild before committing changes under src/.

Notes

• The Widget Studio API is the unauthenticated hosted service behind the public editor; requests carry a stable random user ID (WIDGET_STUDIO_USER_ID to pin).

• The renderer covers the full ChatKit component set; unknown components degrade to rendering their children. External images are blocked by host CSP in interactive mode (placeholder shown) but fine in PNG/HTML output.