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