chat-apps-ui-sdk

# Chat Apps UI SDK Best Practices A reference for building beautiful, review-ready apps that render interactive UI inside the chat surface of ChatGPT and Claude. As of January 2026 these platforms share one foundation — the **MCP Apps** standard (`@modelcontextprotocol/ext-apps`), rendered by Claude, ChatGPT, VS Code, and Goose. The **OpenAI Apps SDK** is a superset adding the `window.openai` bridge, and **MCP-UI** (`@mcp-ui/server` / `@mcp-ui/client`) is the community implementation. This skill contains 46 rules across 8 categories, ordered by impact so the highest-leverage decisions come first. The mental model: an app is an **MCP tool first, UI second**. The model invokes a tool; the tool returns data plus a link to a UI resource; the host renders that resource in a sandboxed iframe; the iframe talks back over a defined bridge. Mistakes early in that chain mean nothing renders; mistakes later mean it renders broken, unsafe, or unpolished. ## When to Apply Reference these guidelines when: - Designing the MCP tool and `structuredContent` / `content` / `_meta` contract for a chat app - Wiring a tool to a component (`_meta.ui.resourceUri`, the `text/html;profile=mcp-app` MIME type, the `ui://` scheme) - Writing the iframe component and its bridge (`window.openai`, `ui/notifications/*`, MCP-UI `onUIAction`) - Choosing display modes, widget state, theming, and responsive layout - Hardening a chat app (CSP, sandbox, secrets, OAuth) or preparing it for directory submission - Reviewing or refactoring existing ChatGPT-app / Claude-app / MCP-UI code ## Rule Categories by Priority | Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | MCP Tool & Discovery Design | CRITICAL | `tool-` | | 2 | UI Resource Wiring & Templates | CRITICAL | `wire-` | | 3 | Host–Component Data Bridge | HIGH | `bridge-` | | 4 | Display Modes & Responsive Layout | HIGH | `display-` | | 5 | State & Model Context | HIGH | `state-` | | 6 | Security & Data Boundaries | HIGH | `sec-` | | 7 | Visual Design & UX Polish | MEDIUM-HIGH | `design-` | | 8 | Distribution & Cross-Host Portability | MEDIUM | `dist-` | ## Quick Reference ### 1. MCP Tool & Discovery Design (CRITICAL) - [`tool-structured-content-contract`](references/tool-structured-content-contract.md) - Split output across structuredContent, content, and _meta - [`tool-specific-verb-names`](references/tool-specific-verb-names.md) - Name tools as specific action verbs - [`tool-output-schema-validation`](references/tool-output-schema-validation.md) - Declare an output schema for structuredContent - [`tool-safety-annotations`](references/tool-safety-annotations.md) - Set readOnlyHint and destructiveHint accurately - [`tool-minimal-scoped-inputs`](references/tool-minimal-scoped-inputs.md) - Request minimal, task-scoped tool inputs - [`tool-feed-widget-in-response`](references/tool-feed-widget-in-response.md) - Return everything the widget needs in one response - [`tool-honest-descriptions`](references/tool-honest-descriptions.md) - Write honest tool descriptions and status text ### 2. UI Resource Wiring & Templates (CRITICAL) - [`wire-resource-uri-link`](references/wire-resource-uri-link.md) - Link each tool to its UI with resourceUri - [`wire-mcp-app-mimetype`](references/wire-mcp-app-mimetype.md) - Serve UI resources with the mcp-app MIME type - [`wire-ui-scheme-and-handler`](references/wire-ui-scheme-and-handler.md) - Match the ui:// URI to a registered resource - [`wire-version-uri-cache-key`](references/wire-version-uri-cache-key.md) - Version the resource URI as a cache key - [`wire-inline-self-contained-bundle`](references/wire-inline-self-contained-bundle.md) - Inline the component bundle into the resource - [`wire-set-ui-domain`](references/wire-set-ui-domain.md) - Set a unique ui.domain for the component ### 3. Host–Component Data Bridge (HIGH) - [`bridge-render-from-notifications`](references/bridge-render-from-notifications.md) - Render from tool output, not first paint - [`bridge-call-tools-app-visibility`](references/bridge-call-tools-app-visibility.md) - Expose tools to the app before calling them - [`bridge-followup-vs-silent-call`](references/bridge-followup-vs-silent-call.md) - Choose follow-up messages or silent tool calls - [`bridge-validate-postmessage-origin`](references/bridge-validate-postmessage-origin.md) - Validate postMessage source in the host - [`bridge-handle-all-mcpui-actions`](references/bridge-handle-all-mcpui-actions.md) - Handle every MCP-UI onUIAction type - [`bridge-use-host-apis`](references/bridge-use-host-apis.md) - Use host bridge APIs instead of reimplementing ### 4. Display Modes & Responsive Layout (HIGH) - [`display-pick-the-right-mode`](references/display-pick-the-right-mode.md) - Pick the display mode that fits the task - [`display-request-mode-with-fallback`](references/display-request-mode-with-fallback.md) - Request fullscreen but render inline first - [`display-report-intrinsic-height`](references/display-report-intrinsic-height.md) - Report intrinsic height and respect maxHeight - [`display-avoid-nested-scroll`](references/display-avoid-nested-scroll.md) - Avoid nested scroll inside inline cards - [`display-respect-theme`](references/display-respect-theme.md) - Respect the host theme and color scheme - [`display-responsive-breakpoints`](references/display-responsive-breakpoints.md) - Collapse layout gracefully on small screens ### 5. State & Model Context (HIGH) - [`state-separate-three-stores`](references/state-separate-three-stores.md) - Separate widget, server, and model state - [`state-persist-widget-state`](references/state-persist-widget-state.md) - Persist UI state through setWidgetState - [`state-no-secrets-in-state`](references/state-no-secrets-in-state.md) - Keep secrets and PII out of widget state - [`state-update-model-context`](references/state-update-model-context.md) - Push user decisions to model context - [`state-keep-state-small`](references/state-keep-state-small.md) - Keep widget state small and serializable ### 6. Security & Data Boundaries (HIGH) - [`sec-declare-csp-allowlist`](references/sec-declare-csp-allowlist.md) - Declare a CSP allowlist for the widget - [`sec-avoid-frame-domains`](references/sec-avoid-frame-domains.md) - Avoid nested frame domains in the widget - [`sec-no-secrets-in-payloads`](references/sec-no-secrets-in-payloads.md) - Never embed secrets in bundles or payloads - [`sec-enforce-server-side-auth`](references/sec-enforce-server-side-auth.md) - Enforce authorization on the server - [`sec-signal-oauth-challenge`](references/sec-signal-oauth-challenge.md) - Signal auth with a www-authenticate challenge - [`sec-minimize-restricted-data`](references/sec-minimize-restricted-data.md) - Minimize and avoid restricted data inputs ### 7. Visual Design & UX Polish (MEDIUM-HIGH) - [`design-inherit-native-typography`](references/design-inherit-native-typography.md) - Inherit native fonts and limit type sizes - [`design-restrain-brand-color`](references/design-restrain-brand-color.md) - Restrain brand color to accents - [`design-render-loading-empty-error`](references/design-render-loading-empty-error.md) - Render loading, empty, and error states - [`design-meet-wcag-contrast`](references/design-meet-wcag-contrast.md) - Meet WCAG AA contrast and provide alt text - [`design-limit-actions-hierarchy`](references/design-limit-actions-hierarchy.md) - Limit actions and keep a clear hierarchy - [`design-respect-reduced-motion`](references/design-respect-reduced-motion.md) - Respect reduced-motion preferences ### 8. Distribution & Cross-Host Portability (MEDIUM) - [`dist-build-on-mcp-apps-standard`](references/dist-build-on-mcp-apps-standard.md) - Build on the shared MCP Apps standard - [`dist-degrade-without-ui`](references/dist-degrade-without-ui.md) - Return a text fallback when UI is unsupported - [`dist-provide-submission-metadata`](references/dist-provide-submission-metadata.md) - Provide accurate submission metadata - [`dist-feature-detect-host-apis`](references/dist-feature-detect-host-apis.md) - Detect host capabilities before use ## How to Use Read the individual reference files for full explanations and incorrect-vs-correct code examples. Start at the top — category 1 (`tool-`) and category 2 (`wire-`) gate whether anything renders at all, so resolve those before touching display or design. - [Section definitions](references/_sections.md) - Category structure and impact levels - [Rule template](assets/templates/_template.md) - Template for adding new rules - [AGENTS.md](AGENTS.md) - Compiled table of contents across all rules ## Reference Files | File | Description | |------|-------------| | [references/_sections.md](references/_sections.md) | Category definitions and impact ordering | | [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules | | [metadata.json](metadata.json) | Version and reference URLs | ## Related Skills - `build-mcp-server` — Entry point for designing the MCP server shape (deployment model, tool patterns) this skill's UI rules build on top of.