Build ChatGPT App
Overview
Scaffold ChatGPT Apps SDK implementations with a docs-first, example-first workflow, then generate code that follows current Apps SDK and MCP Apps bridge patterns.
This skill produces:
- A primary app-archetype classification and repo-shape decision
- A tool plan (names, schemas, annotations, outputs)
- An upstream starting-point recommendation (official example, ext-apps example, or local fallback scaffold)
- An MCP server scaffold (resource registration, tool handlers, metadata)
- A widget scaffold (MCP Apps bridge first,
window.openai compatibility/extensions second)
- A reusable Node +
@modelcontextprotocol/ext-apps starter scaffold for low-dependency fallbacks
- A validation report against the minimum working repo contract
- Local dev and connector setup steps
- A short stakeholder summary of what the app does (when requested)
When to Use
Use this skill when the task involves any of the following:
- Scaffolding a new ChatGPT App (MCP server + widget UI)
- Planning tool surfaces for an Apps SDK project
- Adapting an official OpenAI example or
@modelcontextprotocol/ext-apps example into a ChatGPT app
- Refactoring an existing Apps SDK demo into a production-ready structure
- Wiring the MCP Apps bridge (
postMessage JSON-RPC) or window.openai compatibility APIs
- Applying Apps SDK metadata, CSP allowlists, domain settings, or URI versioning
- Preparing an app for local ChatGPT Developer Mode testing or public submission
- Troubleshooting tool descriptors, widget rendering, or connector setup
Trigger keywords: ChatGPT app, Apps SDK, MCP server, widget, ext-apps, connector, scaffold, tool plan, submission, window.openai, MCP Apps bridge, structuredContent, resourceUri.
Prerequisites
- Docs-first workflow is mandatory. Use
$openai-docs first whenever building or changing a ChatGPT Apps SDK app. If $openai-docs is unavailable, use mcp__openaiDeveloperDocs__search_openai_docs and mcp__openaiDeveloperDocs__fetch_openai_doc.
- Node.js installed for the fallback scaffold script (
scripts/scaffold_node_ext_apps.mjs).
- PowerShell as the primary shell on Windows host. All commands below assume PowerShell unless noted.
- ngrok (or equivalent HTTPS tunnel) for local ChatGPT Developer Mode testing.
- MCP Inspector for runtime validation of tool descriptors and widget rendering.
- OpenAI Platform dashboard access for submission tasks (org verification + Owner role).
Procedure
0. Classify the App Archetype
Before choosing examples, repo shape, or scaffolds, classify the request into one primary archetype and state it explicitly.
tool-only — no UI; MCP server with tools only
vanilla-widget — minimal HTML widget via MCP Apps bridge
react-widget — React widget using @modelcontextprotocol/ext-apps/react or similar
interactive-decoupled — decoupled data/render tools with stateful widget
submission-ready — public directory launch target
Rules:
- Prefer a single primary archetype instead of mixing several.
- If the request is broad, infer the smallest archetype that can still satisfy it.
- Escalate to
submission-ready only when the user asks for public launch, directory submission, or review-ready deployment.
- Call out the chosen archetype in your response so the user can correct it early.
Load references/app-archetypes.md for the full decision rubric.
1. Plan Tools Before Code
Define the tool surface area from user intents before writing any implementation code.
- Use one job per tool.
- Write tool descriptions that start with "Use this when..." behavior cues.
- Make inputs explicit and machine-friendly (enums, required fields, bounds).
- Decide whether each tool is data-only, render-only, or both.
- Set annotations accurately:
readOnlyHint, destructiveHint, openWorldHint; add idempotentHint when true.
- If the app is connector-like, data-only, sync-oriented, or intended for company knowledge or deep research, default to the standard
search and fetch tools instead of inventing custom read-only equivalents.
- For educational/demo apps, prefer one concept per tool so the model can pick the right example cleanly.
- Group demo tools by learning objective: data into the widget, widget actions back into the conversation or tools, host/layout environment signals, and lifecycle/streaming behavior.
Load references/search-fetch-standard.md when search and fetch may be relevant.
2. Choose an App Architecture
Choose the simplest structure that fits the goal.
- Minimal demo pattern — for quick prototypes, workshops, or proofs of concept.
- Decoupled data/render pattern — for production UX so the widget does not re-render on every tool call.
Prefer the decoupled pattern for non-trivial apps:
- Data tools return reusable
structuredContent.
- Render tools attach
_meta.ui.resourceUri and optional _meta["openai/outputTemplate"].
- Render tool descriptions state prerequisites (for example, "Call
search first").
2a. Start From an Upstream Example When One Fits
Default to upstream examples for greenfield work when they are close to the requested app.
- Check the official OpenAI examples first for ChatGPT-facing apps, polished UI patterns, React components, file upload flows, modal flows, or apps that resemble the docs examples.
- Use
@modelcontextprotocol/ext-apps examples when the request is closer to raw MCP Apps bridge/server wiring, or when version-matched package patterns matter more than ChatGPT-specific polish.
- Pick the smallest matching example and copy only the relevant files; do not transplant an entire showcase app unchanged.
- After copying, reconcile the example with the current docs you fetched: tool names/descriptions, annotations,
_meta.ui.*, CSP, URI versioning, and local run instructions.
- State which example you chose and why in one sentence.
Load references/upstream-example-workflow.md for the selection and adaptation rubric.
2b. Use the Starter Script When a Low-Dependency Fallback Helps
Use scripts/scaffold_node_ext_apps.mjs only when:
- The user wants a quick, greenfield Node starter
- A vanilla HTML widget is acceptable
- No upstream example is a better starting point
Skip the script when:
- A close official example exists
- The user already has an existing app structure
- They need a non-Node stack
- They explicitly want React first
- They only want a plan/review instead of code
To run the fallback scaffold (PowerShell):
node scripts/scaffold_node_ext_apps.mjs
After running it:
- Patch the generated output to match the current docs and the user request: adjust tool names/descriptions, annotations, resource metadata, URI versioning, and README/run instructions.
- The generated widget keeps follow-up messaging on the standard
ui/message bridge and only uses window.openai for optional host signals/extensions.
- If you choose the script instead of an upstream example, say why the fallback is better for that request.
3. Scaffold the MCP Server
Generate a server that:
- Registers a widget resource/template with the MCP Apps UI MIME type (
text/html;profile=mcp-app) or the SDK constant (RESOURCE_MIME_TYPE) when using @modelcontextprotocol/ext-apps/server.
- Registers tools with clear names, schemas, titles, and descriptions.
- Returns
structuredContent (model + widget), content (model narration), and _meta (widget-only data) intentionally.
- Keeps handlers idempotent or documents non-idempotent behavior explicitly.
- Includes tool status strings (
openai/toolInvocation/*) when helpful in ChatGPT.
Keep structuredContent concise. Move large or sensitive widget-only payloads to _meta.
4. Scaffold the Widget UI
Use the MCP Apps bridge first for portability, then add ChatGPT-specific window.openai APIs when they materially improve UX.
- Listen for
ui/notifications/tool-result (JSON-RPC over postMessage).
- Render from
structuredContent.
- Use
tools/call for component-initiated tool calls.
- Use
ui/update-model-context only when UI state should change what the model sees.
Use window.openai for compatibility and extensions (file upload, modal, display mode, etc.), not as the only integration path for new apps.
API Surface Guardrails
- Some examples wrap the bridge with an
app object (for example, @modelcontextprotocol/ext-apps/react) and expose helper names like app.sendMessage(), app.callServerTool(), app.openLink(), or host getter methods.
- Treat those wrappers as implementation details or convenience layers, not the canonical public API to teach by default.
- For ChatGPT-facing guidance, prefer the current documented surface:
window.openai.callTool(...)
window.openai.sendFollowUpMessage(...)
window.openai.openExternal(...)
window.openai.requestDisplayMode(...)
- Direct globals:
window.openai.theme, window.openai.locale, window.openai.displayMode, window.openai.toolInput, window.openai.toolOutput, window.openai.toolResponseMetadata, window.openai.widgetState
- If you reference wrapper helpers from repo examples, map them back to the documented
window.openai or MCP Apps bridge primitives and call out that the wrapper is not the normative API surface.
Load references/window-openai-patterns.md for the wrapper-to-canonical mapping and for React helper extraction patterns.
5. Add Resource Metadata and Security
Set resource metadata deliberately on the widget resource/template:
_meta.ui.csp with exact connectDomains and resourceDomains
_meta.ui.domain for app submission-ready deployments
_meta.ui.prefersBorder (or OpenAI compatibility alias when needed)
- Optional
openai/widgetDescription to reduce redundant narration
Avoid frameDomains unless iframe embeds are core to the product.
5a. Enforce a Minimum Working Repo Contract
Every generated repo should satisfy a small, stable contract before you consider it done:
- The repo shape matches the chosen archetype.
- The MCP server and tools are wired to a reachable
/mcp endpoint.
- Tools have clear descriptions, accurate annotations, and UI metadata where needed.
- Connector-like, data-only, sync-oriented, and company-knowledge-style apps use the standard
search and fetch tool shapes when relevant.
- The widget uses the MCP Apps bridge correctly when a UI exists.
- The repo includes enough scripts or commands for a user to run and check it locally.
- The response explicitly says what validation was run and what was not run.
Load references/repo-contract-and-validation.md for the detailed checklist and validation ladder.
6. Validate the Local Loop
Validate against the minimum working repo contract, not just "did files get created."
Lowest-cost checks first:
- Static contract review
- Syntax or compile checks when feasible
- Local
/mcp health check when feasible
Then move up to runtime checks:
4. Verify tool descriptors and widget rendering in MCP Inspector
5. Test the app in ChatGPT developer mode through HTTPS tunneling
6. Exercise retries and repeated tool calls to confirm idempotent behavior
7. Check widget updates after host events and follow-up tool calls
If you are only delivering a scaffold and are not installing dependencies, still run low-cost checks and say exactly what you did not run.
Load references/repo-contract-and-validation.md for the validation ladder.
7. Connect and Test in ChatGPT (Developer Mode)
For local development, include explicit ChatGPT setup steps:
Run the MCP server locally on http://localhost:<port>/mcp.
Expose the local server with a public HTTPS tunnel:
ngrok http <port>
Use the tunneled HTTPS URL plus /mcp path when connecting from ChatGPT.
In ChatGPT, enable Developer Mode under Settings → Apps & Connectors → Advanced settings.
In ChatGPT app settings, create a new app for the remote MCP server and paste the public MCP URL.
Tell users to refresh the app after MCP tool/metadata changes so ChatGPT reloads the latest descriptors.
Note: Some docs/screenshots still use older "connector" terminology. Prefer current product wording ("app") while acknowledging both labels when giving step-by-step instructions.
8. Plan Production Hosting and Deployment
When the user asks to deploy or prepare for launch, generate hosting guidance for the MCP server (and widget assets if hosted separately):
- Host behind a stable public HTTPS endpoint (not a tunnel) with dependable TLS.
- Preserve low-latency streaming behavior on
/mcp.
- Configure secrets outside the repo (environment variables / secret manager).
- Add logging, request latency tracking, and error visibility for tool calls.
- Add basic observability (CPU, memory, request volume) and a troubleshooting path.
- Re-test the hosted endpoint in ChatGPT Developer Mode before submission.
9. Prepare Submission and Publish (Public Apps Only)
Only include these steps when the user intends a public directory listing:
- Use
apps-sdk/deploy/submission for the submission flow and apps-sdk/app-submission-guidelines for review requirements.
- Keep private/internal apps in Developer Mode instead of submitting.
- Confirm org verification and Owner-role prerequisites before submission work.
- Ensure the MCP server uses a public production endpoint (no localhost/testing URLs) and has submission-ready CSP configured.
- Prepare submission artifacts: app metadata, logo/screenshots, privacy policy URL, support contact, test prompts/responses, localization info.
- If auth is required, include review-safe demo credentials and test the login path end-to-end.
- Submit for review in the Platform dashboard, monitor review status, and publish only after approval.
Mandatory Docs-First Workflow
Use $openai-docs first whenever building or changing a ChatGPT Apps SDK app.
- Invoke
$openai-docs (preferred) or call the OpenAI docs MCP server directly.
- Fetch current Apps SDK docs before writing code, especially (baseline pages):
apps-sdk/build/mcp-server
apps-sdk/build/chatgpt-ui
apps-sdk/build/examples
apps-sdk/plan/tools
apps-sdk/reference
- Fetch
apps-sdk/quickstart when scaffolding a new app or generating a first-pass implementation, and check the official examples repo/page before inventing a scaffold from scratch.
- Fetch deployment/submission docs when the task includes local ChatGPT testing, hosting, or public launch:
apps-sdk/deploy
apps-sdk/deploy/submission
apps-sdk/app-submission-guidelines
- Cite the docs URLs you used when explaining design choices or generated scaffolds.
- Prefer current docs guidance over older repo patterns when they differ, and call out compatibility aliases explicitly.
- If doc search times out or returns poor matches, fetch the canonical Apps SDK pages directly by URL and continue; do not let search failure block scaffolding.
If $openai-docs is unavailable, use:
mcp__openaiDeveloperDocs__search_openai_docs
mcp__openaiDeveloperDocs__fetch_openai_doc
Load references/apps-sdk-docs-workflow.md for suggested doc queries and a compact checklist.
Prompt Guidance
Use prompts that explicitly pair this skill with $openai-docs so the resulting scaffold is grounded in current docs.
Preferred prompt patterns:
Use $build-chatgpt-app with $openai-docs to scaffold a ChatGPT app for <use case> with a <TS/Python> MCP server and <React/vanilla> widget.
Use $build-chatgpt-app with $openai-docs to adapt the closest official Apps SDK example into a ChatGPT app for <use case>.
Use $build-chatgpt-app and $openai-docs to refactor this Apps SDK demo into a production-ready structure with tool annotations, CSP, and URI versioning.
Use $build-chatgpt-app with $openai-docs to plan tools first, then generate the MCP server and widget code.
When responding, ask for or infer these inputs before coding:
- Use case and primary user flows
- Read-only vs mutating tools
- Demo vs production target
- Private/internal use vs public directory submission
- Backend language and UI stack
- Auth requirements
- External API domains for CSP allowlists
- Hosting target and local dev approach
- Org ownership/verification readiness (for submission tasks)
Interactive State Guidance
Load references/interactive-state-sync-patterns.md when the app has long-lived widget state, repeated interactions, or component-initiated tool calls (for example, games, boards, maps, dashboards, editors).
Use it to choose patterns for:
- State snapshots plus monotonic event tokens (
stateVersion, resetCount, etc.)
- Idempotent retry-safe handlers
structuredContent vs _meta partitioning
- MCP Apps bridge-first update flows with optional
window.openai compatibility
- Decoupled data/render tool architecture for more complex interactive apps
Default Starting-Point Order
For greenfield apps, prefer these starting points in order:
- Official OpenAI examples when a close example already matches the requested stack or interaction pattern.
- Version-matched
@modelcontextprotocol/ext-apps examples when the user needs a lower-level or more portable MCP Apps baseline.
scripts/scaffold_node_ext_apps.mjs only when no close example fits, the user wants a tiny Node + vanilla starter, or network access/example retrieval is undesirable.
Do not generate a large custom scaffold from scratch if a close upstream example already exists. Copy the smallest matching example, remove unrelated demo code, then patch it to the current docs and the user request.
Output Expectations
When using this skill to scaffold code, produce output in this order unless the user asks otherwise:
- Primary app archetype chosen and why
- Tool plan and architecture choice (minimal vs decoupled)
- Upstream starting point chosen (official example, ext-apps example, or local fallback scaffold) and why
- Doc pages/URLs used from
$openai-docs
- File tree to create or modify
- Implementation (server + widget)
- Validation performed against the minimum working repo contract
- Local run/test instructions (including tunnel + ChatGPT Developer Mode app setup)
- Deployment/hosting guidance (if requested or implied)
- Submission-readiness checklist (for public launch requests)
- Risks, gaps, and follow-up improvements
For direct scaffold requests, do not stop at the plan: give the brief plan, then create the files immediately.
Pitfalls
- Do not invent APIs or CLI flags. Only use documented
window.openai.* methods and MCP Apps bridge primitives. Wrapper helpers (app.sendMessage(), app.callServerTool(), etc.) are implementation details, not the canonical public API.
- Do not skip the docs-first workflow. Always fetch current Apps SDK docs before writing code. If search times out, fetch canonical pages directly by URL.
- Do not generate a large custom scaffold from scratch if a close upstream example exists. Copy the smallest matching example, remove unrelated demo code, then patch.
- Do not use
frameDomains unless iframe embeds are core to the product.
- Do not put large or sensitive widget-only payloads in
structuredContent. Move them to _meta.
- Do not use
ui/update-model-context casually. Only when UI state should change what the model sees.
- Do not submit private/internal apps to the public directory. Keep them in Developer Mode.
- Do not use localhost/testing URLs for submission. The MCP server must use a public production endpoint.
- Do not let doc search failure block scaffolding. Fetch canonical pages directly by URL and continue.
- Do not mix multiple archetypes. Pick one primary archetype; escalate to
submission-ready only for public launch.
- Do not forget to tell users to refresh the app after MCP tool/metadata changes so ChatGPT reloads the latest descriptors.
- Do not drop the "what validation was run and what was not run" statement — always include it.
Verification
Static Contract Review
Check the generated repo against the minimum working repo contract:
# Verify repo structure matches archetype
Get-ChildItem -Recurse -Name | Select-String -Pattern "server|web|widget|mcp"
Syntax / Compile Checks
# TypeScript compile check (if applicable)
npx tsc --noEmit
# Node syntax check for server entry
node --check server/index.ts
Local /mcp Health Check
# Start the server
npm run dev
# In another terminal, verify the /mcp endpoint responds
curl http://localhost:<port>/mcp
MCP Inspector Validation
# Launch MCP Inspector against the local server
npx @modelcontextprotocol/inspector node server/index.ts
Verify:
- Tool descriptors appear with correct names, schemas, and annotations
- Widget resource/template is registered with
text/html;profile=mcp-app MIME type
structuredContent and _meta are returned correctly
ChatGPT Developer Mode Test
# Tunnel the local server
ngrok http <port>
Then in ChatGPT:
- Settings → Apps & Connectors → Advanced settings → enable Developer Mode
- Create a new app, paste the tunneled HTTPS URL +
/mcp
- Exercise each tool and confirm widget rendering
- Test repeated tool calls for idempotent behavior
- Check widget updates after host events and follow-up tool calls
Submission Readiness Checklist (Public Apps Only)
References
| File |
When to Load |
references/app-archetypes.md |
Classifying requests into supported app shapes before choosing examples or scaffolds |
references/apps-sdk-docs-workflow.md |
Doc queries, page targets, and code-generation checklist for the docs-first workflow |
references/interactive-state-sync-patterns.md |
Long-lived widget state, repeated interactions, or component-initiated tool calls (games, boards, maps, dashboards, editors) |
references/repo-contract-and-validation.md |
Generating or reviewing a repo against the minimum working repo contract and validation ladder |
references/search-fetch-standard.md |
Connector-like, data-only, sync-oriented apps, or apps meant to work with company knowledge or deep research |
references/upstream-example-workflow.md |
Starting a greenfield app or deciding whether to adapt an upstream example or use the local fallback scaffold |
references/window-openai-patterns.md |
ChatGPT-specific widget behavior or translating repo examples that use wrapper-specific app.* helpers |
scripts/scaffold_node_ext_apps.mjs |
Minimal Node + @modelcontextprotocol/ext-apps fallback starter scaffold (vanilla HTML widget) |
1---
2name: build-chatgpt-app
3description: "Scaffolds ChatGPT Apps SDK apps that pair an MCP server with widget UI (MCP Apps bridge, window.openai, CSP, tool plans, Developer Mode, directory submission). Use when designing ChatGPT app tools, registering UI resources, wiring ext-apps, or producing a docs-aligned scaffold. Not for generic MCP servers outside ChatGPT Apps (mcp-server-authoring). Never invent window.openai APIs from memory — fetch current Apps SDK docs first."
4version: 1.0.1
5metadata:
6 source: https://skillmd.com/skills/kayforkind/build-chatgpt-app
7---
8
9# Build ChatGPT App
10
11## Overview
12
13Scaffold ChatGPT Apps SDK implementations with a docs-first, example-first workflow, then generate code that follows current Apps SDK and MCP Apps bridge patterns.
14
15This skill produces:
16
17- A primary app-archetype classification and repo-shape decision
18- A tool plan (names, schemas, annotations, outputs)
19- An upstream starting-point recommendation (official example, ext-apps example, or local fallback scaffold)
20- An MCP server scaffold (resource registration, tool handlers, metadata)
21- A widget scaffold (MCP Apps bridge first, `window.openai` compatibility/extensions second)
22- A reusable Node + `@modelcontextprotocol/ext-apps` starter scaffold for low-dependency fallbacks
23- A validation report against the minimum working repo contract
24- Local dev and connector setup steps
25- A short stakeholder summary of what the app does (when requested)
26
27## When to Use
28
29Use this skill when the task involves any of the following:
30
31- Scaffolding a new ChatGPT App (MCP server + widget UI)
32- Planning tool surfaces for an Apps SDK project
33- Adapting an official OpenAI example or `@modelcontextprotocol/ext-apps` example into a ChatGPT app
34- Refactoring an existing Apps SDK demo into a production-ready structure
35- Wiring the MCP Apps bridge (`postMessage` JSON-RPC) or `window.openai` compatibility APIs
36- Applying Apps SDK metadata, CSP allowlists, domain settings, or URI versioning
37- Preparing an app for local ChatGPT Developer Mode testing or public submission
38- Troubleshooting tool descriptors, widget rendering, or connector setup
39
40**Trigger keywords:** ChatGPT app, Apps SDK, MCP server, widget, ext-apps, connector, scaffold, tool plan, submission, `window.openai`, MCP Apps bridge, structuredContent, resourceUri.
41
42## Prerequisites
43
44- **Docs-first workflow is mandatory.** Use `$openai-docs` first whenever building or changing a ChatGPT Apps SDK app. If `$openai-docs` is unavailable, use `mcp__openaiDeveloperDocs__search_openai_docs` and `mcp__openaiDeveloperDocs__fetch_openai_doc`.
45- **Node.js** installed for the fallback scaffold script (`scripts/scaffold_node_ext_apps.mjs`).
46- **PowerShell** as the primary shell on Windows host. All commands below assume PowerShell unless noted.
47- **ngrok** (or equivalent HTTPS tunnel) for local ChatGPT Developer Mode testing.
48- **MCP Inspector** for runtime validation of tool descriptors and widget rendering.
49- **OpenAI Platform dashboard access** for submission tasks (org verification + Owner role).
50
51## Procedure
52
53### 0. Classify the App Archetype
54
55Before choosing examples, repo shape, or scaffolds, classify the request into one primary archetype and state it explicitly.
56
57- `tool-only` — no UI; MCP server with tools only
58- `vanilla-widget` — minimal HTML widget via MCP Apps bridge
59- `react-widget` — React widget using `@modelcontextprotocol/ext-apps/react` or similar
60- `interactive-decoupled` — decoupled data/render tools with stateful widget
61- `submission-ready` — public directory launch target
62
63**Rules:**
64- Prefer a single primary archetype instead of mixing several.
65- If the request is broad, infer the smallest archetype that can still satisfy it.
66- Escalate to `submission-ready` only when the user asks for public launch, directory submission, or review-ready deployment.
67- Call out the chosen archetype in your response so the user can correct it early.
68
69**Load `references/app-archetypes.md`** for the full decision rubric.
70
71### 1. Plan Tools Before Code
72
73Define the tool surface area from user intents before writing any implementation code.
74
751. Use one job per tool.
762. Write tool descriptions that start with "Use this when..." behavior cues.
773. Make inputs explicit and machine-friendly (enums, required fields, bounds).
784. Decide whether each tool is data-only, render-only, or both.
795. Set annotations accurately: `readOnlyHint`, `destructiveHint`, `openWorldHint`; add `idempotentHint` when true.
806. If the app is connector-like, data-only, sync-oriented, or intended for company knowledge or deep research, default to the standard `search` and `fetch` tools instead of inventing custom read-only equivalents.
817. For educational/demo apps, prefer one concept per tool so the model can pick the right example cleanly.
828. Group demo tools by learning objective: data into the widget, widget actions back into the conversation or tools, host/layout environment signals, and lifecycle/streaming behavior.
83
84**Load `references/search-fetch-standard.md`** when `search` and `fetch` may be relevant.
85
86### 2. Choose an App Architecture
87
88Choose the simplest structure that fits the goal.
89
90- **Minimal demo pattern** — for quick prototypes, workshops, or proofs of concept.
91- **Decoupled data/render pattern** — for production UX so the widget does not re-render on every tool call.
92
93Prefer the decoupled pattern for non-trivial apps:
94- Data tools return reusable `structuredContent`.
95- Render tools attach `_meta.ui.resourceUri` and optional `_meta["openai/outputTemplate"]`.
96- Render tool descriptions state prerequisites (for example, "Call `search` first").
97
98### 2a. Start From an Upstream Example When One Fits
99
100Default to upstream examples for greenfield work when they are close to the requested app.
101
1021. Check the **official OpenAI examples** first for ChatGPT-facing apps, polished UI patterns, React components, file upload flows, modal flows, or apps that resemble the docs examples.
1032. Use **`@modelcontextprotocol/ext-apps` examples** when the request is closer to raw MCP Apps bridge/server wiring, or when version-matched package patterns matter more than ChatGPT-specific polish.
1043. Pick the smallest matching example and copy only the relevant files; do not transplant an entire showcase app unchanged.
1054. After copying, reconcile the example with the current docs you fetched: tool names/descriptions, annotations, `_meta.ui.*`, CSP, URI versioning, and local run instructions.
1065. State which example you chose and why in one sentence.
107
108**Load `references/upstream-example-workflow.md`** for the selection and adaptation rubric.
109
110### 2b. Use the Starter Script When a Low-Dependency Fallback Helps
111
112Use `scripts/scaffold_node_ext_apps.mjs` only when:
113- The user wants a quick, greenfield Node starter
114- A vanilla HTML widget is acceptable
115- No upstream example is a better starting point
116
117**Skip the script when:**
118- A close official example exists
119- The user already has an existing app structure
120- They need a non-Node stack
121- They explicitly want React first
122- They only want a plan/review instead of code
123
124**To run the fallback scaffold (PowerShell):**
125
126```powershell
127node scripts/scaffold_node_ext_apps.mjs
128```
129
130After running it:
131- Patch the generated output to match the current docs and the user request: adjust tool names/descriptions, annotations, resource metadata, URI versioning, and README/run instructions.
132- The generated widget keeps follow-up messaging on the standard `ui/message` bridge and only uses `window.openai` for optional host signals/extensions.
133- If you choose the script instead of an upstream example, say why the fallback is better for that request.
134
135### 3. Scaffold the MCP Server
136
137Generate a server that:
138
1391. Registers a widget resource/template with the MCP Apps UI MIME type (`text/html;profile=mcp-app`) or the SDK constant (`RESOURCE_MIME_TYPE`) when using `@modelcontextprotocol/ext-apps/server`.
1402. Registers tools with clear names, schemas, titles, and descriptions.
1413. Returns `structuredContent` (model + widget), `content` (model narration), and `_meta` (widget-only data) intentionally.
1424. Keeps handlers idempotent or documents non-idempotent behavior explicitly.
1435. Includes tool status strings (`openai/toolInvocation/*`) when helpful in ChatGPT.
144
145**Keep `structuredContent` concise.** Move large or sensitive widget-only payloads to `_meta`.
146
147### 4. Scaffold the Widget UI
148
149Use the MCP Apps bridge first for portability, then add ChatGPT-specific `window.openai` APIs when they materially improve UX.
150
1511. Listen for `ui/notifications/tool-result` (JSON-RPC over `postMessage`).
1522. Render from `structuredContent`.
1533. Use `tools/call` for component-initiated tool calls.
1544. Use `ui/update-model-context` only when UI state should change what the model sees.
155
156Use `window.openai` for compatibility and extensions (file upload, modal, display mode, etc.), not as the only integration path for new apps.
157
158#### API Surface Guardrails
159
160- Some examples wrap the bridge with an `app` object (for example, `@modelcontextprotocol/ext-apps/react`) and expose helper names like `app.sendMessage()`, `app.callServerTool()`, `app.openLink()`, or host getter methods.
161- Treat those wrappers as implementation details or convenience layers, not the canonical public API to teach by default.
162- For ChatGPT-facing guidance, prefer the current documented surface:
163 - `window.openai.callTool(...)`
164 - `window.openai.sendFollowUpMessage(...)`
165 - `window.openai.openExternal(...)`
166 - `window.openai.requestDisplayMode(...)`
167 - Direct globals: `window.openai.theme`, `window.openai.locale`, `window.openai.displayMode`, `window.openai.toolInput`, `window.openai.toolOutput`, `window.openai.toolResponseMetadata`, `window.openai.widgetState`
168- If you reference wrapper helpers from repo examples, map them back to the documented `window.openai` or MCP Apps bridge primitives and call out that the wrapper is not the normative API surface.
169
170**Load `references/window-openai-patterns.md`** for the wrapper-to-canonical mapping and for React helper extraction patterns.
171
172### 5. Add Resource Metadata and Security
173
174Set resource metadata deliberately on the widget resource/template:
175
176- `_meta.ui.csp` with exact `connectDomains` and `resourceDomains`
177- `_meta.ui.domain` for app submission-ready deployments
178- `_meta.ui.prefersBorder` (or OpenAI compatibility alias when needed)
179- Optional `openai/widgetDescription` to reduce redundant narration
180
181Avoid `frameDomains` unless iframe embeds are core to the product.
182
183### 5a. Enforce a Minimum Working Repo Contract
184
185Every generated repo should satisfy a small, stable contract before you consider it done:
186
187- The repo shape matches the chosen archetype.
188- The MCP server and tools are wired to a reachable `/mcp` endpoint.
189- Tools have clear descriptions, accurate annotations, and UI metadata where needed.
190- Connector-like, data-only, sync-oriented, and company-knowledge-style apps use the standard `search` and `fetch` tool shapes when relevant.
191- The widget uses the MCP Apps bridge correctly when a UI exists.
192- The repo includes enough scripts or commands for a user to run and check it locally.
193- The response explicitly says what validation was run and what was not run.
194
195**Load `references/repo-contract-and-validation.md`** for the detailed checklist and validation ladder.
196
197### 6. Validate the Local Loop
198
199Validate against the minimum working repo contract, not just "did files get created."
200
201**Lowest-cost checks first:**
2021. Static contract review
2032. Syntax or compile checks when feasible
2043. Local `/mcp` health check when feasible
205
206**Then move up to runtime checks:**
2074. Verify tool descriptors and widget rendering in MCP Inspector
2085. Test the app in ChatGPT developer mode through HTTPS tunneling
2096. Exercise retries and repeated tool calls to confirm idempotent behavior
2107. Check widget updates after host events and follow-up tool calls
211
212If you are only delivering a scaffold and are not installing dependencies, still run low-cost checks and say exactly what you did not run.
213
214**Load `references/repo-contract-and-validation.md`** for the validation ladder.
215
216### 7. Connect and Test in ChatGPT (Developer Mode)
217
218For local development, include explicit ChatGPT setup steps:
219
2201. Run the MCP server locally on `http://localhost:<port>/mcp`.
2212. Expose the local server with a public HTTPS tunnel:
222
223 ```powershell
224 ngrok http <port>
225 ```
226
2273. Use the tunneled HTTPS URL plus `/mcp` path when connecting from ChatGPT.
2284. In ChatGPT, enable Developer Mode under **Settings → Apps & Connectors → Advanced settings**.
2295. In ChatGPT app settings, create a new app for the remote MCP server and paste the public MCP URL.
2306. Tell users to refresh the app after MCP tool/metadata changes so ChatGPT reloads the latest descriptors.
231
232> **Note:** Some docs/screenshots still use older "connector" terminology. Prefer current product wording ("app") while acknowledging both labels when giving step-by-step instructions.
233
234### 8. Plan Production Hosting and Deployment
235
236When the user asks to deploy or prepare for launch, generate hosting guidance for the MCP server (and widget assets if hosted separately):
237
2381. Host behind a stable public HTTPS endpoint (not a tunnel) with dependable TLS.
2392. Preserve low-latency streaming behavior on `/mcp`.
2403. Configure secrets outside the repo (environment variables / secret manager).
2414. Add logging, request latency tracking, and error visibility for tool calls.
2425. Add basic observability (CPU, memory, request volume) and a troubleshooting path.
2436. Re-test the hosted endpoint in ChatGPT Developer Mode before submission.
244
245### 9. Prepare Submission and Publish (Public Apps Only)
246
247Only include these steps when the user intends a public directory listing:
248
2491. Use `apps-sdk/deploy/submission` for the submission flow and `apps-sdk/app-submission-guidelines` for review requirements.
2502. Keep private/internal apps in Developer Mode instead of submitting.
2513. Confirm org verification and Owner-role prerequisites before submission work.
2524. Ensure the MCP server uses a public production endpoint (no localhost/testing URLs) and has submission-ready CSP configured.
2535. Prepare submission artifacts: app metadata, logo/screenshots, privacy policy URL, support contact, test prompts/responses, localization info.
2546. If auth is required, include review-safe demo credentials and test the login path end-to-end.
2557. Submit for review in the Platform dashboard, monitor review status, and publish only after approval.
256
257## Mandatory Docs-First Workflow
258
259Use `$openai-docs` first whenever building or changing a ChatGPT Apps SDK app.
260
2611. Invoke `$openai-docs` (preferred) or call the OpenAI docs MCP server directly.
2622. Fetch current Apps SDK docs before writing code, especially (baseline pages):
263 - `apps-sdk/build/mcp-server`
264 - `apps-sdk/build/chatgpt-ui`
265 - `apps-sdk/build/examples`
266 - `apps-sdk/plan/tools`
267 - `apps-sdk/reference`
2683. Fetch `apps-sdk/quickstart` when scaffolding a new app or generating a first-pass implementation, and check the official examples repo/page before inventing a scaffold from scratch.
2694. Fetch deployment/submission docs when the task includes local ChatGPT testing, hosting, or public launch:
270 - `apps-sdk/deploy`
271 - `apps-sdk/deploy/submission`
272 - `apps-sdk/app-submission-guidelines`
2735. Cite the docs URLs you used when explaining design choices or generated scaffolds.
2746. Prefer current docs guidance over older repo patterns when they differ, and call out compatibility aliases explicitly.
2757. If doc search times out or returns poor matches, fetch the canonical Apps SDK pages directly by URL and continue; do not let search failure block scaffolding.
276
277If `$openai-docs` is unavailable, use:
278- `mcp__openaiDeveloperDocs__search_openai_docs`
279- `mcp__openaiDeveloperDocs__fetch_openai_doc`
280
281**Load `references/apps-sdk-docs-workflow.md`** for suggested doc queries and a compact checklist.
282
283## Prompt Guidance
284
285Use prompts that explicitly pair this skill with `$openai-docs` so the resulting scaffold is grounded in current docs.
286
287Preferred prompt patterns:
288
289- `Use $build-chatgpt-app with $openai-docs to scaffold a ChatGPT app for <use case> with a <TS/Python> MCP server and <React/vanilla> widget.`
290- `Use $build-chatgpt-app with $openai-docs to adapt the closest official Apps SDK example into a ChatGPT app for <use case>.`
291- `Use $build-chatgpt-app and $openai-docs to refactor this Apps SDK demo into a production-ready structure with tool annotations, CSP, and URI versioning.`
292- `Use $build-chatgpt-app with $openai-docs to plan tools first, then generate the MCP server and widget code.`
293
294When responding, ask for or infer these inputs before coding:
295
296- Use case and primary user flows
297- Read-only vs mutating tools
298- Demo vs production target
299- Private/internal use vs public directory submission
300- Backend language and UI stack
301- Auth requirements
302- External API domains for CSP allowlists
303- Hosting target and local dev approach
304- Org ownership/verification readiness (for submission tasks)
305
306## Interactive State Guidance
307
308**Load `references/interactive-state-sync-patterns.md`** when the app has long-lived widget state, repeated interactions, or component-initiated tool calls (for example, games, boards, maps, dashboards, editors).
309
310Use it to choose patterns for:
311
312- State snapshots plus monotonic event tokens (`stateVersion`, `resetCount`, etc.)
313- Idempotent retry-safe handlers
314- `structuredContent` vs `_meta` partitioning
315- MCP Apps bridge-first update flows with optional `window.openai` compatibility
316- Decoupled data/render tool architecture for more complex interactive apps
317
318## Default Starting-Point Order
319
320For greenfield apps, prefer these starting points in order:
321
3221. **Official OpenAI examples** when a close example already matches the requested stack or interaction pattern.
3232. **Version-matched `@modelcontextprotocol/ext-apps` examples** when the user needs a lower-level or more portable MCP Apps baseline.
3243. **`scripts/scaffold_node_ext_apps.mjs`** only when no close example fits, the user wants a tiny Node + vanilla starter, or network access/example retrieval is undesirable.
325
326Do not generate a large custom scaffold from scratch if a close upstream example already exists. Copy the smallest matching example, remove unrelated demo code, then patch it to the current docs and the user request.
327
328## Output Expectations
329
330When using this skill to scaffold code, produce output in this order unless the user asks otherwise:
331
3321. Primary app archetype chosen and why
3332. Tool plan and architecture choice (minimal vs decoupled)
3343. Upstream starting point chosen (official example, ext-apps example, or local fallback scaffold) and why
3354. Doc pages/URLs used from `$openai-docs`
3365. File tree to create or modify
3376. Implementation (server + widget)
3387. Validation performed against the minimum working repo contract
3398. Local run/test instructions (including tunnel + ChatGPT Developer Mode app setup)
3409. Deployment/hosting guidance (if requested or implied)
34110. Submission-readiness checklist (for public launch requests)
34211. Risks, gaps, and follow-up improvements
343
344For direct scaffold requests, do not stop at the plan: give the brief plan, then create the files immediately.
345
346## Pitfalls
347
348- **Do not invent APIs or CLI flags.** Only use documented `window.openai.*` methods and MCP Apps bridge primitives. Wrapper helpers (`app.sendMessage()`, `app.callServerTool()`, etc.) are implementation details, not the canonical public API.
349- **Do not skip the docs-first workflow.** Always fetch current Apps SDK docs before writing code. If search times out, fetch canonical pages directly by URL.
350- **Do not generate a large custom scaffold from scratch if a close upstream example exists.** Copy the smallest matching example, remove unrelated demo code, then patch.
351- **Do not use `frameDomains` unless iframe embeds are core to the product.**
352- **Do not put large or sensitive widget-only payloads in `structuredContent`.** Move them to `_meta`.
353- **Do not use `ui/update-model-context` casually.** Only when UI state should change what the model sees.
354- **Do not submit private/internal apps to the public directory.** Keep them in Developer Mode.
355- **Do not use localhost/testing URLs for submission.** The MCP server must use a public production endpoint.
356- **Do not let doc search failure block scaffolding.** Fetch canonical pages directly by URL and continue.
357- **Do not mix multiple archetypes.** Pick one primary archetype; escalate to `submission-ready` only for public launch.
358- **Do not forget to tell users to refresh the app** after MCP tool/metadata changes so ChatGPT reloads the latest descriptors.
359- **Do not drop the "what validation was run and what was not run" statement** — always include it.
360
361## Verification
362
363### Static Contract Review
364
365Check the generated repo against the minimum working repo contract:
366
367```powershell
368# Verify repo structure matches archetype
369Get-ChildItem -Recurse -Name | Select-String -Pattern "server|web|widget|mcp"
370```
371
372### Syntax / Compile Checks
373
374```powershell
375# TypeScript compile check (if applicable)
376npx tsc --noEmit
377
378# Node syntax check for server entry
379node --check server/index.ts
380```
381
382### Local /mcp Health Check
383
384```powershell
385# Start the server
386npm run dev
387
388# In another terminal, verify the /mcp endpoint responds
389curl http://localhost:<port>/mcp
390```
391
392### MCP Inspector Validation
393
394```powershell
395# Launch MCP Inspector against the local server
396npx @modelcontextprotocol/inspector node server/index.ts
397```
398
399Verify:
400- Tool descriptors appear with correct names, schemas, and annotations
401- Widget resource/template is registered with `text/html;profile=mcp-app` MIME type
402- `structuredContent` and `_meta` are returned correctly
403
404### ChatGPT Developer Mode Test
405
406```powershell
407# Tunnel the local server
408ngrok http <port>
409```
410
411Then in ChatGPT:
4121. Settings → Apps & Connectors → Advanced settings → enable Developer Mode
4132. Create a new app, paste the tunneled HTTPS URL + `/mcp`
4143. Exercise each tool and confirm widget rendering
4154. Test repeated tool calls for idempotent behavior
4165. Check widget updates after host events and follow-up tool calls
417
418### Submission Readiness Checklist (Public Apps Only)
419
420- [ ] Public production HTTPS endpoint (no localhost/tunnel)
421- [ ] Submission-ready CSP configured (`_meta.ui.csp` with exact `connectDomains` and `resourceDomains`)
422- [ ] `_meta.ui.domain` set for app submission-ready deployments
423- [ ] Org verification and Owner-role confirmed
424- [ ] Submission artifacts prepared (metadata, logo/screenshots, privacy policy URL, support contact, test prompts/responses, localization info)
425- [ ] If auth required: review-safe demo credentials included and login path tested end-to-end
426- [ ] Submitted for review in Platform dashboard; publish only after approval
427
428## References
429
430| File | When to Load |
431|------|-------------|
432| `references/app-archetypes.md` | Classifying requests into supported app shapes before choosing examples or scaffolds |
433| `references/apps-sdk-docs-workflow.md` | Doc queries, page targets, and code-generation checklist for the docs-first workflow |
434| `references/interactive-state-sync-patterns.md` | Long-lived widget state, repeated interactions, or component-initiated tool calls (games, boards, maps, dashboards, editors) |
435| `references/repo-contract-and-validation.md` | Generating or reviewing a repo against the minimum working repo contract and validation ladder |
436| `references/search-fetch-standard.md` | Connector-like, data-only, sync-oriented apps, or apps meant to work with company knowledge or deep research |
437| `references/upstream-example-workflow.md` | Starting a greenfield app or deciding whether to adapt an upstream example or use the local fallback scaffold |
438| `references/window-openai-patterns.md` | ChatGPT-specific widget behavior or translating repo examples that use wrapper-specific `app.*` helpers |
439| `scripts/scaffold_node_ext_apps.mjs` | Minimal Node + `@modelcontextprotocol/ext-apps` fallback starter scaffold (vanilla HTML widget) |