Interactive widgets in chat (MCP Apps)

What this is

When you use ComStack from an MCP Apps-capable client — Claude on web, desktop, and mobile — several tools don’t just return text: they render a live, interactive card directly in the chat. Reviewing a publish, previewing a page, adjusting your site’s colours and fonts, or checking usage all happen inside these cards. In clients without MCP Apps support (Claude Code CLI, API-key machine callers), the same tools return their normal structured JSON — nothing breaks, you just don’t get the visual layer.

How it works

A widget-enabled tool carries a UI resource reference in its metadata. When the tool runs, the client mounts the widget in a sandboxed frame and feeds it the tool’s result. The widget can call a small set of ComStack tools back through the client — always as you, with your permissions, and never with its own credentials. Closing a widget never cancels server-side work: a running publish, for example, finishes on the server regardless.

Widgets are read-and-review surfaces first. The two that write — the publish reviewer’s Publish button and the Design Studio’s Apply button — only act when you click them, and they call the same audited tools (publish-confirm, update-design) the assistant would call in chat. Approving in the widget and approving in chat are equivalent.

The widgets

Publish review (publish) — every pending page with its changes: inline text diffs for knowledge pages, a Details panel for metadata changes (a title-only change is never invisible), per-page checkboxes for subset publishing, and a quiet Publish button. While publishing you can close the card; the pages go live in a few minutes either way.
Page viewer (get-page-content) — knowledge pages render as the document; custom pages open on a visual Preview of the page itself, with HTML, CSS, and JS tabs for the code-minded (each tab shows line-level changes when a draft is under review) and a mobile-width toggle on wide screens.
Upload preview (upload-custom-page) — the moment an upload lands, the draft opens on its rendered Preview with a summary of the translatable strings extracted.
Publish progress (publish-status) — re-attach to a running publish: live progress, then the published links.
Project overview (get-project-state, list-my-projects) — your site link, languages, page counts, pending drafts with validation state and edit links, and the navigation tree.
Design Studio (update-design) — colour pickers for your accent palette, a Google Fonts picker with live type previews, colour-scheme and mic-glow controls, and a live mini preview of how buttons and highlights will feel. Apply saves only what you changed.
Usage & credit (get-usage-report, get-credit-balance) — charges and event counts as scaled bars, and your credit balance.
Who am I (whoami) — a small identity card showing the signed-in user.

When to use it

You asked to publish and want to check exactly what changes before confirming — or publish only some of the pending pages.
You want to see a custom page the way visitors will, not as source code.
You’re tuning brand colours or fonts and want to iterate visually instead of describing hex codes in prose.
You want a one-glance picture of a project: what’s live, what’s drafted, what needs fixing.

Common errors

“I only see JSON / plain text, no card.” Your client doesn’t support MCP Apps (Claude Code CLI and API-key callers never render widgets), or the connector predates the widget release — remove and re-add the ComStack connector in Claude, then start a new chat.
“The widget says it couldn’t connect to the host.” A client-side hiccup while mounting the frame; re-run the tool call (ask the assistant to retry).
“Font previews are unavailable” in the Design Studio. The client blocked the font preview download. Your font choice still applies — it loads on your published site regardless of the preview.
“The publish card lost track of the publish.” The status poll was interrupted; the publish itself continues server-side. Ask the assistant for publish-status to re-attach.
A custom page shows “This page is an Astro component” instead of a preview. Astro component sources can’t be rendered client-side. Open the live page or the editor link instead; the HTML/CSS/JS tabs still show exactly what changed.