Agent Skills: Chat Apps UI SDK Best Practices

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 - Split output across structuredContent, content, and _meta
• tool-specific-verb-names - Name tools as specific action verbs
• tool-output-schema-validation - Declare an output schema for structuredContent
• tool-safety-annotations - Set readOnlyHint and destructiveHint accurately
• tool-minimal-scoped-inputs - Request minimal, task-scoped tool inputs
• tool-feed-widget-in-response - Return everything the widget needs in one response
• tool-honest-descriptions - Write honest tool descriptions and status text

2. UI Resource Wiring & Templates (CRITICAL)

• wire-resource-uri-link - Link each tool to its UI with resourceUri
• wire-mcp-app-mimetype - Serve UI resources with the mcp-app MIME type
• wire-ui-scheme-and-handler - Match the ui:// URI to a registered resource
• wire-version-uri-cache-key - Version the resource URI as a cache key
• wire-inline-self-contained-bundle - Inline the component bundle into the resource
• wire-set-ui-domain - Set a unique ui.domain for the component

3. Host–Component Data Bridge (HIGH)

• bridge-render-from-notifications - Render from tool output, not first paint
• bridge-call-tools-app-visibility - Expose tools to the app before calling them
• bridge-followup-vs-silent-call - Choose follow-up messages or silent tool calls
• bridge-validate-postmessage-origin - Validate postMessage source in the host
• bridge-handle-all-mcpui-actions - Handle every MCP-UI onUIAction type
• bridge-use-host-apis - Use host bridge APIs instead of reimplementing

4. Display Modes & Responsive Layout (HIGH)

• display-pick-the-right-mode - Pick the display mode that fits the task
• display-request-mode-with-fallback - Request fullscreen but render inline first
• display-report-intrinsic-height - Report intrinsic height and respect maxHeight
• display-avoid-nested-scroll - Avoid nested scroll inside inline cards
• display-respect-theme - Respect the host theme and color scheme
• display-responsive-breakpoints - Collapse layout gracefully on small screens

5. State & Model Context (HIGH)

• state-separate-three-stores - Separate widget, server, and model state
• state-persist-widget-state - Persist UI state through setWidgetState
• state-no-secrets-in-state - Keep secrets and PII out of widget state
• state-update-model-context - Push user decisions to model context
• state-keep-state-small - Keep widget state small and serializable

6. Security & Data Boundaries (HIGH)

• sec-declare-csp-allowlist - Declare a CSP allowlist for the widget
• sec-avoid-frame-domains - Avoid nested frame domains in the widget
• sec-no-secrets-in-payloads - Never embed secrets in bundles or payloads
• sec-enforce-server-side-auth - Enforce authorization on the server
• sec-signal-oauth-challenge - Signal auth with a www-authenticate challenge
• sec-minimize-restricted-data - Minimize and avoid restricted data inputs

7. Visual Design & UX Polish (MEDIUM-HIGH)

• design-inherit-native-typography - Inherit native fonts and limit type sizes
• design-restrain-brand-color - Restrain brand color to accents
• design-render-loading-empty-error - Render loading, empty, and error states
• design-meet-wcag-contrast - Meet WCAG AA contrast and provide alt text
• design-limit-actions-hierarchy - Limit actions and keep a clear hierarchy
• design-respect-reduced-motion - Respect reduced-motion preferences

8. Distribution & Cross-Host Portability (MEDIUM)

• dist-build-on-mcp-apps-standard - Build on the shared MCP Apps standard
• dist-degrade-without-ui - Return a text fallback when UI is unsupported
• dist-provide-submission-metadata - Provide accurate submission metadata
• dist-feature-detect-host-apis - 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 - Category structure and impact levels
• Rule template - Template for adding new rules
• AGENTS.md - Compiled table of contents across all rules

Reference Files

| File | Description | |------|-------------| | references/_sections.md | Category definitions and impact ordering | | assets/templates/_template.md | Template for new rules | | 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.