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