Bring your app to ChatGPT | Codex use cases
Need
Widget framework
Default options
Why it's needed
A strong default for stateful widgets, especially when the UI needs filters, tables, or multi-step interaction.
use-cases/chatgpt-apps.md +7 −145
11name: Bring your app to ChatGPT# Bring your app to ChatGPT | Codex use cases
2tagline: Turn your use cases into focused apps for ChatGPT.
3summary: "Build one narrow ChatGPT app outcome end to end: define the tools,
4 scaffold the MCP server and optional widget, connect it in ChatGPT, and
5 iterate until the core flow works."
6skills:
7 - token: $chatgpt-apps
8 url: https://github.com/openai/skills/tree/main/skills/.curated/chatgpt-apps
9 description: Plan tools, wire MCP resources, and follow the current ChatGPT app
10 build flow.
11 - token: $openai-docs
12 url: https://github.com/openai/skills/tree/main/skills/.curated/openai-docs
13 description: Pull current official Apps SDK guidance before Codex writes code or
14 suggests architecture.
15 - token: vercel
16 url: https://github.com/openai/plugins/tree/main/plugins/vercel
17 description: Bring Vercel ecosystem guidance into Codex with curated skills and
18 the official Vercel MCP server.
19bestFor:
20 - Planning a first ChatGPT app around a user outcome
21 - Scaffolding an MCP server, tool metadata, and an optional widget without
22 overbuilding
23 - Running a tight loop from local HTTPS testing to ChatGPT developer-mode
24 verification
25starterPrompt:
26 title: Plan the App Before You Scaffold It
27 body: >-
28 Use $chatgpt-apps with $openai-docs to plan a ChatGPT app for [use case] in
29 this repo.
30 2
3Need
31 4
325 Requirements:Widget framework
33 6
347 - Start with one core user outcome.Default options
35 8
369 - Propose 3-5 tools with clear names, descriptions, inputs, and outputs.[React](https://react.dev/)
37 10
3811 - Recommend whether v1 needs a widget or can start data-only.Why it's needed
39 12
4013 - Prefer TypeScript for the MCP server and React for the widget.A strong default for stateful widgets, especially when the UI needs filters, tables, or multi-step interaction.
41 14
42 - Call out auth, deployment, and test requirements.
43
44
45 Output:
46
47 - Tool plan
48
49 - Proposed file tree
50
51 - Golden prompt set
52
53 - Risks and open questions
54 suggestedEffort: medium
55relatedLinks:
56 - label: Apps SDK quickstart
57 url: /apps-sdk/quickstart
58 - label: Build an MCP server
59 url: /apps-sdk/build/mcp-server
60 - label: Testing
61 url: /apps-sdk/deploy/testing
62techStack:
63 - need: Widget framework
64 goodDefault: "[React](https://react.dev/)"
65 why: A strong default for stateful widgets, especially when the UI needs
66 filters, tables, or multi-step interaction.
67 - need: Hosting
68 goodDefault: "[Vercel](https://vercel.com/docs)"
69 why: Quick deploys, preview environments, automatic HTTPS, and a clear path to
70 hosted MCP endpoints.
71
72## What you build
73
74Every ChatGPT app has three parts:
75
76- An MCP server that defines tools, returns data, enforces auth, and points ChatGPT at any UI resources.
77- An optional web component that renders inside a ChatGPT iframe. You can build it with React or with plain HTML, CSS, and JavaScript.
78- A model that decides when to call the app's tools based on the metadata you provide.
79
80Codex is most useful when it owns the repetitive engineering work around those parts:
81
82- Planning the tool surface and metadata.
83- Scaffolding the server and widget.
84- Wiring local run scripts.
85- Adding auth and deployment changes in focused passes.
86- Writing the verification loop that proves the app works in ChatGPT.
87
88## Why Codex is a strong fit
89
90- ChatGPT apps already split cleanly into a server, an optional widget, and model-driven tool calls.
91- Codex prompting works best when the task is explicit, scoped, and straightforward to verify, which matches app-building work well.
92- Skills and `AGENTS.md` give Codex the reusable instructions and project rules it needs to stay grounded.
93
94To learn more about how to install and use skills, see our [skills documentation](https://developers.openai.com/codex/skills).
95
96## How to use
97
98## Prerequisites
99
100- Start with one core user outcome instead of trying to port an entire product into chat.
101- Choose the stack up front: TypeScript or Python for the server, and React or plain HTML, CSS, and JavaScript for the widget.
102- Decide what HTTPS path you will use during development, such as `ngrok` or Cloudflare Tunnel.
103- Current docs usually say app, but some older pages and settings still say connector. During local testing, treat them as the same setup object.
104
1051. Start with one narrow app outcome and ask Codex to propose three to five tools with clear names, descriptions, inputs, and outputs.
1062. Decide whether v1 can stay data-only or needs a widget, then scaffold the MCP server and optional widget using existing repo patterns before adding dependencies.
1073. Run the app locally behind HTTPS, connect it in ChatGPT developer mode, and test it with a small direct, indirect, and negative prompt set.
1084. Iterate on metadata, state handling, `structuredContent`, and `_meta` payloads until the core read flow behaves reliably inside ChatGPT.
1095. Add OAuth 2.1 only when user-specific data or write actions require it, while keeping anonymous or read-only flows simple where possible.
1106. Prepare a hosted preview with a stable `/mcp` endpoint, verify streaming and widget asset hosting, and review the launch checklist before sharing or submitting the app.
111
112## Suggested prompts
113
114Strong prompts for this workflow share the same ingredients:
115
116- One clear outcome: say what the app should help the user do inside ChatGPT.
117- A concrete stack: say whether you want TypeScript or Python on the server, and whether the widget should use React or stay lightweight.
118- Explicit tool boundaries: ask Codex to propose or build a small set of tools with one job per tool.
119- Auth expectations: state whether the first version can be anonymous or whether it needs linked accounts and write actions.
120- A local development path: mention the tunnel or hosting path you expect for HTTPS testing in ChatGPT.
121- Verification steps: tell Codex what commands to run, what prompts to test, and what evidence to report back.
122
123Avoid one giant prompt that asks for planning, implementation, auth, deployment, submission, and polish in one pass. Split the work into smaller milestones instead.
124
125**Plan the App Before You Scaffold It**
126
127**Scaffold the First Working Version**
128
129**Add Auth Only After the Core Flow Works**
130
131**Prepare the App for Deployment and Review**
132
133## Launch readiness
134
135- The app has one narrow outcome that is obvious to a user.
136- The tool set stays small and has explicit metadata, inputs, and outputs.
137- The MCP server works end to end and returns concise `structuredContent`, reserving widget-only data for `_meta`.
138- The widget, if needed, renders correctly inside ChatGPT.
139- A local HTTPS testing loop works through ChatGPT developer mode.
140- A small direct, indirect, and negative prompt set passes with the expected conversation flow and tool payloads.
141- Auth is added only where user-specific data or write actions require it.
142- A deployment plan and launch-readiness review cover metadata, tool hints, privacy, and test prompts before the app is shared or submitted.
143
144## Common pitfalls
145
146- Asking Codex to port the whole product into ChatGPT. Better move: ask for one core user outcome, three to five tools, and one narrow widget.
147- Starting with a giant implementation prompt. Better move: split the work into planning, scaffold, auth, deployment, and review passes.
148- Writing UI before the tool contract is clear. Better move: plan the tool surface and response schema first, then build the widget.
149- Skipping official docs grounding. Better move: pair `$chatgpt-apps` with `$openai-docs` so the scaffold follows current Apps SDK guidance.
150- Treating metadata as an afterthought. Better move: write tool descriptions and parameter docs early, then replay a prompt set against them.
151- Adding auth before proving the anonymous or read-only path. Better move: get the core tool flow working first, then add OAuth for the tools that actually need it.
152- Declaring the app done before testing inside ChatGPT. Better move: connect the app in developer mode, inspect tool payloads, and verify the real conversation flow.