---
title: "Interactive widgets in chat (MCP Apps)"
description: "ComStack tools render live, interactive cards in Claude — publish reviews, page previews, a design studio, project and usage dashboards."
url: "https://comstack.ai/docs/mcp/widgets/"
---
## 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.

## Related

- [The standard MCP workflow](/docs/mcp/guide.md)
- [Publishing and the draft lifecycle](/docs/mcp/publishing.md)
- [MCP tool catalogue](/docs/mcp/tools.md)
- [Get started with the MCP server](/docs/mcp/setup.md)