ChatGPT Apps SDK Best Practices

Build ChatGPT apps using the OpenAI Apps SDK, Model Context Protocol (MCP), and component-based UI patterns.

Quick Reference

Topic	Guide
Display modes, visual design, accessibility	ui-guidelines.md
MCP architecture, tools, and server patterns	mcp-server.md
React patterns and window.openai API	ui-components.md
React hooks (useOpenAiGlobal, useWidgetState)	react-integration.md
Three-tier state architecture and best practice	state-management.md

Critical Setup Requirements

Issue	Prevention
CORS blocking	Enable https://chatgpt.com origin on endpoints
Widget 404s	Use ui://widget/ prefix format for widget resources
Plain text display	Set MIME type to text/html+skybridge for widgets
Tool not suggested	Use action-oriented descriptions in tool definitions
Missing widget data	Pass initial data via _meta.initialData field
CSP script blocking	Reference external scripts from allowed CDN origins

Decision Trees

What display mode should I use?

Is this a multi-step workflow or deep exploration?
├── Yes → Fullscreen
└── No → Is this a parallel activity (game, live session)?
    ├── Yes → Picture-in-Picture (PiP)
    └── No → Inline
        ├── Single item with quick action → Inline Card
        └── 3-8 similar items → Inline Carousel

Where should state live?

Is this data from your API/database?
├── Yes → MCP Server (Business Data)
│   Return in structuredContent from tool calls
└── No → Is it user preference/cross-session data?
    ├── Yes → Backend Storage (via OAuth)
    └── No → Widget State (UI-scoped)
        Use window.openai.widgetState / useWidgetState

Should this be a separate tool?

Is this action:
- Atomic and standalone?
- Invokable by the model via natural language?
- Returning structured data?
├── Yes → Create public tool (model-accessible)
└── No → Is it only for widget interactions?
    ├── Yes → Use private tool ("openai/visibility": "private")
    └── No → Handle within existing tool logic

What should go in structuredContent vs _meta?

Does the model need this data to:
- Understand results?
- Generate follow-ups?
- Reason about next steps?
├── Yes → structuredContent (concise, model-readable)
└── No → _meta (large datasets, widget-only data)

Should I use custom UI or just text?

Does this require:
- User input beyond text?
- Structured data visualization?
- Interactive selection/filtering?
├── Yes → Custom UI component
└── No → Return plain text/markdown in content

Official Documentation

• MCP Specification: https://modelcontextprotocol.io
• TypeScript MCP SDK: https://github.com/modelcontextprotocol/typescript-sdk
• OpenAI Apps SDK: https://developers.openai.com/apps-sdk
• MCP Apps Extension: http://blog.modelcontextprotocol.io/posts/2025-11-21-mcp-apps
• ChatGPT Component Library: https://openai.github.io/apps-sdk-ui