Chatgpt App Sdk

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](./references/ui-guidelines.md) | | MCP architecture, tools, and server patterns | [mcp-server.md](./references/mcp-server.md) | | React patterns and window.openai API | [ui-components.md](./references/ui-components.md) | | React hooks (useOpenAiGlobal, useWidgetState) | [react-integration.md](./references/react-integration.md) | | Three-tier state architecture and best practice | [state-management.md](./references/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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mintuz
• Source: mintuz/skills
• License: MIT

Install and usage instructions live in the source repository linked above.