1name: Bring your app to ChatGPT1# 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 

32 Requirements:5Widget framework

33 6 

34 - Start with one core user outcome.7Default options

35 8 

36 - Propose 3-5 tools with clear names, descriptions, inputs, and outputs.9[React](https://react.dev/)

37 10 

38 - Recommend whether v1 needs a widget or can start data-only.11Why it's needed

39 12 

40 - Prefer TypeScript for the MCP server and React for the widget.13A 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.