tomevault-io 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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.