ChatGPT Apps
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 from scratch or adapting an upstream example
- Designing or refactoring MCP tools for a ChatGPT App (names, schemas, annotations,
structuredContent, _meta)
- Wiring the MCP Apps bridge in a widget (
ui/notifications/tool-result, tools/call, ui/update-model-context)
- Applying
window.openai compatibility APIs (file upload, modal, display mode, theme, locale)
- Setting resource metadata and security (
_meta.ui.csp, _meta.ui.domain, connectDomains, resourceDomains)
- Preparing an app for local testing in ChatGPT Developer Mode via HTTPS tunnel
- Preparing an app for public submission to the ChatGPT app directory
- Troubleshooting tool descriptors, widget rendering, CSP violations, or bridge communication
Trigger keywords: ChatGPT app, Apps SDK, MCP Apps bridge, widget, ext-apps, tool annotations, structuredContent, submission, connector, window.openai, MCP server scaffold.
Prerequisites
- Node.js (v18+ recommended) installed and available on
PATH
- PowerShell as the primary shell on the Windows host (
~\agent-skills\library\chatgpt-apps\)
$openai-docs skill or the OpenAI developer docs MCP server (mcp__openaiDeveloperDocs__search_openai_docs, mcp__openaiDeveloperDocs__fetch_openai_doc) for docs-first workflow
- ngrok or equivalent HTTPS tunneling tool for local ChatGPT testing
- ChatGPT Developer Mode access (Settings → Apps & Connectors → Advanced settings)
@modelcontextprotocol/ext-apps package when using the fallback scaffold or ext-apps examples
Procedure
0. Mandatory Docs-First Workflow
Before writing any code, fetch current Apps SDK documentation.
- Invoke
$openai-docs (preferred) or call the OpenAI docs MCP server directly.
- Fetch current Apps SDK docs before writing code, especially these 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. 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.
Load these reference files at specific points:
| Reference File |
When to Load |
references/apps-sdk-docs-workflow.md |
At the start, for suggested doc queries and a compact checklist |
references/app-archetypes.md |
Before choosing examples or scaffolds, to classify the request into a supported app shape |
references/repo-contract-and-validation.md |
When generating or reviewing a repo, to keep output inside a stable "working app" contract |
references/search-fetch-standard.md |
When the app is connector-like, data-only, sync-oriented, or meant to work with company knowledge or deep research |
references/upstream-example-workflow.md |
When starting a greenfield app or deciding whether to adapt an upstream example or use the local fallback scaffold |
references/window-openai-patterns.md |
When the task needs ChatGPT-specific widget behavior or when translating repo examples that use wrapper-specific app.* helpers |
references/interactive-state-sync-patterns.md |
When the app has long-lived widget state, repeated interactions, or component-initiated tool calls (games, boards, maps, dashboards, editors) |
1. 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, just MCP tools
vanilla-widget — minimal HTML widget, MCP Apps bridge
react-widget — React widget with @modelcontextprotocol/ext-apps/react
interactive-decoupled — decoupled data/render tools, long-lived state
submission-ready — public directory launch target
Infer the archetype unless a missing detail is truly blocking. Use the archetype to choose:
- Whether a UI is needed at all
- Whether to preserve a split
server/ + web/ layout
- Whether to prefer official OpenAI examples, ext-apps examples, or the local fallback scaffold
- Which validation checks matter most
- Whether
search and fetch should be the default read-only tool surface
Escalate to submission-ready only when the user asks for public launch, directory submission, or review-ready deployment.
Load references/app-archetypes.md for the full decision rubric.
2. Plan Tools Before Code
Define the tool surface area from user intents.
- 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
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.
3. 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").
3a. Choose a Starting Point
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.
Load references/upstream-example-workflow.md for the selection and adaptation rubric.
3b. Use the Starter Script (Low-Dependency Fallback)
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 it when:
- A close official example exists
- The user already has an existing app structure
- The user needs a non-Node stack
- The user explicitly wants React first
- The user only wants a plan/review instead of code
Run it only after fetching current docs, then reconcile the generated files with the docs you fetched.
node scripts/scaffold_node_ext_apps.mjs
The script generates a minimal @modelcontextprotocol/ext-apps server plus a vanilla HTML widget that uses the MCP Apps bridge by default. The generated widget keeps follow-up messaging on the standard ui/message bridge and only uses window.openai for optional host signals/extensions.
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.
4. 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.
5. 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.
6. 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.
7. Enforce the 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.
8. Validate the Local Loop
Validate against the minimum working repo contract, not just "did files get created."
Low-cost checks first:
- Static contract review.
- Syntax or compile checks when feasible.
- Local
/mcp health check when feasible.
# Example: check if the MCP server responds on the expected endpoint
curl http://localhost:3000/mcp
Runtime checks next:
- Verify tool descriptors and widget rendering in MCP Inspector.
- Test the app in ChatGPT developer mode through HTTPS tunneling.
- Exercise retries and repeated tool calls to confirm idempotent behavior.
- 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.
9. 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.
10. 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.
11. 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.
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
Output Expectations
When using this skill to scaffold code, produce output in this order unless the user asks otherwise:
For direct scaffold requests, do not stop at the plan: give the brief plan, then create the files immediately.
- 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
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 $chatgpt-apps with $openai-docs to scaffold a ChatGPT app for <use case> with a <TS/Python> MCP server and <React/vanilla> widget.
Use $chatgpt-apps with $openai-docs to adapt the closest official Apps SDK example into a ChatGPT app for <use case>.
Use $chatgpt-apps and $openai-docs to refactor this Apps SDK demo into a production-ready structure with tool annotations, CSP, and URI versioning.
Use $chatgpt-apps 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)
Pitfalls
- 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 current docs.
- Do not treat wrapper
app.* helpers as the canonical public API. They are implementation details. Map them back to window.openai or MCP Apps bridge primitives.
- Do not use
window.openai as the only integration path for new apps. Use the MCP Apps bridge first for portability.
- Do not let doc search failure block scaffolding. If search times out or returns poor matches, fetch canonical Apps SDK pages directly by URL.
- Do not prefer older repo patterns over current docs when they differ. Call out compatibility aliases explicitly.
- Do not skip validation. Even when only delivering a scaffold, run low-cost checks and state exactly what was not run.
- Do not submit private/internal apps to the public directory. Keep them in Developer Mode.
- Do not use localhost/testing URLs for submission. Ensure the MCP server uses a public production endpoint.
- Do not put large or sensitive payloads in
structuredContent. Move them to _meta.
- Do not use
frameDomains unless iframe embeds are core to the product.
- Do not mix multiple primary archetypes. Pick one and escalate only when the user explicitly asks for public launch.
- Do not forget to tell users to refresh the app after MCP tool/metadata changes so ChatGPT reloads the latest descriptors.
Verification
After generating or modifying a ChatGPT App, verify the following:
Static Checks
# Verify file tree matches the chosen archetype
Get-ChildItem -Recurse -Name | Select-String -Pattern "server|web|package.json"
# Verify MCP server file has no syntax errors (Node.js)
node --check server/index.ts
# or
npx tsc --noEmit
Local MCP Health Check
# Start the MCP server
npm run dev
# In a separate terminal, verify the /mcp endpoint responds
curl http://localhost:3000/mcp
Tool Descriptor Verification
- Confirm each tool has: name, description starting with "Use this when...", input schema, accurate annotations (
readOnlyHint, destructiveHint, openWorldHint, idempotentHint).
- Confirm
structuredContent, content, and _meta are returned intentionally per tool.
- Confirm widget resource/template uses MIME type
text/html;profile=mcp-app or RESOURCE_MIME_TYPE.
Widget Bridge Verification
- Confirm the widget listens for
ui/notifications/tool-result via postMessage.
- Confirm rendering comes from
structuredContent.
- Confirm
tools/call is used for component-initiated tool calls.
- Confirm
window.openai APIs are used only for extensions, not as the sole integration path.
CSP and Metadata Verification
- Confirm
_meta.ui.csp has exact connectDomains and resourceDomains.
- Confirm
_meta.ui.domain is set for submission-ready deployments.
- Confirm no
frameDomains unless iframe embeds are core to the product.
ChatGPT Developer Mode Verification
- Confirm the MCP server is running on
http://localhost:<port>/mcp.
- Confirm ngrok tunnel is active and the HTTPS URL is reachable.
- Confirm the app was created in ChatGPT with the tunneled HTTPS URL +
/mcp path.
- Confirm Developer Mode is enabled under Settings → Apps & Connectors → Advanced settings.
- Confirm tool calls execute and widget renders correctly in ChatGPT.
- Confirm repeated tool calls behave idempotently.
- Confirm widget updates after host events and follow-up tool calls.
Submission Readiness Verification (Public Apps Only)
References
references/app-archetypes.md — Classifying requests into supported app shapes
references/apps-sdk-docs-workflow.md — Doc queries, page targets, and code-generation checklist
references/interactive-state-sync-patterns.md — Reusable patterns for stateful or highly interactive widget apps
references/repo-contract-and-validation.md — Minimum working repo contract and lightweight validation ladder
references/search-fetch-standard.md — When and how to default to the standard search and fetch tools
references/upstream-example-workflow.md — Choosing between official examples, ext-apps examples, and the local fallback scaffold
references/window-openai-patterns.md — ChatGPT-specific extensions, wrapper API translation, and React helper patterns
scripts/scaffold_node_ext_apps.mjs — Minimal Node + @modelcontextprotocol/ext-apps fallback starter scaffold
Related Skills
$openai-docs — Fetch current OpenAI developer documentation; always pair with this skill for docs-first scaffolding
mcp__openaiDeveloperDocs__search_openai_docs — Direct docs search when $openai-docs is unavailable
mcp__openaiDeveloperDocs__fetch_openai_doc — Direct doc fetch when $openai-docs is unavailable
1---
2name: chatgpt-apps
3description: "Scaffolds ChatGPT Apps SDK apps that pair an MCP server with a widget UI: tool plans, resource registration, MCP Apps bridge, window.openai extensions, CSP/domain metadata, and directory submission. Use when designing tools, wiring widgets, or producing a docs-aligned Apps SDK scaffold. Not for generic ChatGPT chat prompts or standalone MCP servers with no Apps SDK widget contract."
4version: 1.0.1
5metadata:
6 source: https://skillmd.com/skills/kayforkind/chatgpt-apps
7---
8
9# ChatGPT Apps
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** from scratch or adapting an upstream example
32- **Designing or refactoring MCP tools** for a ChatGPT App (names, schemas, annotations, `structuredContent`, `_meta`)
33- **Wiring the MCP Apps bridge** in a widget (`ui/notifications/tool-result`, `tools/call`, `ui/update-model-context`)
34- **Applying `window.openai` compatibility APIs** (file upload, modal, display mode, theme, locale)
35- **Setting resource metadata and security** (`_meta.ui.csp`, `_meta.ui.domain`, `connectDomains`, `resourceDomains`)
36- **Preparing an app for local testing** in ChatGPT Developer Mode via HTTPS tunnel
37- **Preparing an app for public submission** to the ChatGPT app directory
38- **Troubleshooting** tool descriptors, widget rendering, CSP violations, or bridge communication
39
40**Trigger keywords:** ChatGPT app, Apps SDK, MCP Apps bridge, widget, ext-apps, tool annotations, structuredContent, submission, connector, `window.openai`, MCP server scaffold.
41
42## Prerequisites
43
44- **Node.js** (v18+ recommended) installed and available on `PATH`
45- **PowerShell** as the primary shell on the Windows host (`~\agent-skills\library\chatgpt-apps\`)
46- **`$openai-docs` skill** or the OpenAI developer docs MCP server (`mcp__openaiDeveloperDocs__search_openai_docs`, `mcp__openaiDeveloperDocs__fetch_openai_doc`) for docs-first workflow
47- **ngrok** or equivalent HTTPS tunneling tool for local ChatGPT testing
48- **ChatGPT Developer Mode** access (Settings → Apps & Connectors → Advanced settings)
49- **`@modelcontextprotocol/ext-apps`** package when using the fallback scaffold or ext-apps examples
50
51## Procedure
52
53### 0. Mandatory Docs-First Workflow
54
55Before writing any code, fetch current Apps SDK documentation.
56
571. Invoke `$openai-docs` (preferred) or call the OpenAI docs MCP server directly.
582. Fetch current Apps SDK docs before writing code, especially these baseline pages:
59 - `apps-sdk/build/mcp-server`
60 - `apps-sdk/build/chatgpt-ui`
61 - `apps-sdk/build/examples`
62 - `apps-sdk/plan/tools`
63 - `apps-sdk/reference`
643. Fetch `apps-sdk/quickstart` when scaffolding a new app or generating a first-pass implementation. Check the official examples repo/page before inventing a scaffold from scratch.
654. Fetch deployment/submission docs when the task includes local ChatGPT testing, hosting, or public launch:
66 - `apps-sdk/deploy`
67 - `apps-sdk/deploy/submission`
68 - `apps-sdk/app-submission-guidelines`
695. Cite the docs URLs you used when explaining design choices or generated scaffolds.
706. Prefer current docs guidance over older repo patterns when they differ, and call out compatibility aliases explicitly.
717. 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.
72
73**Load these reference files at specific points:**
74
75| Reference File | When to Load |
76|---|---|
77| `references/apps-sdk-docs-workflow.md` | At the start, for suggested doc queries and a compact checklist |
78| `references/app-archetypes.md` | Before choosing examples or scaffolds, to classify the request into a supported app shape |
79| `references/repo-contract-and-validation.md` | When generating or reviewing a repo, to keep output inside a stable "working app" contract |
80| `references/search-fetch-standard.md` | When the app is connector-like, data-only, sync-oriented, or meant to work with company knowledge or deep research |
81| `references/upstream-example-workflow.md` | When starting a greenfield app or deciding whether to adapt an upstream example or use the local fallback scaffold |
82| `references/window-openai-patterns.md` | When the task needs ChatGPT-specific widget behavior or when translating repo examples that use wrapper-specific `app.*` helpers |
83| `references/interactive-state-sync-patterns.md` | When the app has long-lived widget state, repeated interactions, or component-initiated tool calls (games, boards, maps, dashboards, editors) |
84
85### 1. Classify the App Archetype
86
87Before choosing examples, repo shape, or scaffolds, classify the request into one primary archetype and state it explicitly.
88
89- `tool-only` — no UI, just MCP tools
90- `vanilla-widget` — minimal HTML widget, MCP Apps bridge
91- `react-widget` — React widget with `@modelcontextprotocol/ext-apps/react`
92- `interactive-decoupled` — decoupled data/render tools, long-lived state
93- `submission-ready` — public directory launch target
94
95Infer the archetype unless a missing detail is truly blocking. Use the archetype to choose:
96
97- Whether a UI is needed at all
98- Whether to preserve a split `server/` + `web/` layout
99- Whether to prefer official OpenAI examples, ext-apps examples, or the local fallback scaffold
100- Which validation checks matter most
101- Whether `search` and `fetch` should be the default read-only tool surface
102
103Escalate to `submission-ready` only when the user asks for public launch, directory submission, or review-ready deployment.
104
105**Load `references/app-archetypes.md`** for the full decision rubric.
106
107### 2. Plan Tools Before Code
108
109Define the tool surface area from user intents.
110
1111. Use one job per tool.
1122. Write tool descriptions that start with "Use this when..." behavior cues.
1133. Make inputs explicit and machine-friendly (enums, required fields, bounds).
1144. Decide whether each tool is data-only, render-only, or both.
1155. Set annotations accurately:
116 - `readOnlyHint`
117 - `destructiveHint`
118 - `openWorldHint`
119 - `idempotentHint` (when true)
1206. 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.
1217. For educational/demo apps, prefer one concept per tool so the model can pick the right example cleanly.
1228. 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.
123
124**Load `references/search-fetch-standard.md`** when `search` and `fetch` may be relevant.
125
126### 3. Choose an App Architecture
127
128Choose the simplest structure that fits the goal.
129
130- **Minimal demo pattern** — for quick prototypes, workshops, or proofs of concept.
131- **Decoupled data/render pattern** — for production UX so the widget does not re-render on every tool call.
132
133Prefer the decoupled pattern for non-trivial apps:
134
135- Data tools return reusable `structuredContent`.
136- Render tools attach `_meta.ui.resourceUri` and optional `_meta["openai/outputTemplate"]`.
137- Render tool descriptions state prerequisites (for example, "Call `search` first").
138
139### 3a. Choose a Starting Point
140
141For greenfield apps, prefer these starting points in order:
142
1431. **Official OpenAI examples** — when a close example already matches the requested stack or interaction pattern.
1442. **Version-matched `@modelcontextprotocol/ext-apps` examples** — when the user needs a lower-level or more portable MCP Apps baseline.
1453. **`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.
146
147Do 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.
148
149**Load `references/upstream-example-workflow.md`** for the selection and adaptation rubric.
150
151### 3b. Use the Starter Script (Low-Dependency Fallback)
152
153Use `scripts/scaffold_node_ext_apps.mjs` only when:
154
155- The user wants a quick, greenfield Node starter
156- A vanilla HTML widget is acceptable
157- No upstream example is a better starting point
158
159**Skip it when:**
160
161- A close official example exists
162- The user already has an existing app structure
163- The user needs a non-Node stack
164- The user explicitly wants React first
165- The user only wants a plan/review instead of code
166
167Run it only after fetching current docs, then reconcile the generated files with the docs you fetched.
168
169```powershell
170node scripts/scaffold_node_ext_apps.mjs
171```
172
173The script generates a minimal `@modelcontextprotocol/ext-apps` server plus a vanilla HTML widget that uses the MCP Apps bridge by default. The generated widget keeps follow-up messaging on the standard `ui/message` bridge and only uses `window.openai` for optional host signals/extensions.
174
175After 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.
176
177### 4. Scaffold the MCP Server
178
179Generate a server that:
180
1811. 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`.
1822. Registers tools with clear names, schemas, titles, and descriptions.
1833. Returns `structuredContent` (model + widget), `content` (model narration), and `_meta` (widget-only data) intentionally.
1844. Keeps handlers idempotent or documents non-idempotent behavior explicitly.
1855. Includes tool status strings (`openai/toolInvocation/*`) when helpful in ChatGPT.
186
187Keep `structuredContent` concise. Move large or sensitive widget-only payloads to `_meta`.
188
189### 5. Scaffold the Widget UI
190
191Use the MCP Apps bridge first for portability, then add ChatGPT-specific `window.openai` APIs when they materially improve UX.
192
1931. Listen for `ui/notifications/tool-result` (JSON-RPC over `postMessage`).
1942. Render from `structuredContent`.
1953. Use `tools/call` for component-initiated tool calls.
1964. Use `ui/update-model-context` only when UI state should change what the model sees.
197
198Use `window.openai` for compatibility and extensions (file upload, modal, display mode, etc.), not as the only integration path for new apps.
199
200#### API Surface Guardrails
201
202Some 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.
203
204- Treat those wrappers as implementation details or convenience layers, not the canonical public API to teach by default.
205- For ChatGPT-facing guidance, prefer the current documented surface:
206 - `window.openai.callTool(...)`
207 - `window.openai.sendFollowUpMessage(...)`
208 - `window.openai.openExternal(...)`
209 - `window.openai.requestDisplayMode(...)`
210 - Direct globals: `window.openai.theme`, `window.openai.locale`, `window.openai.displayMode`, `window.openai.toolInput`, `window.openai.toolOutput`, `window.openai.toolResponseMetadata`, `window.openai.widgetState`
211- 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.
212
213**Load `references/window-openai-patterns.md`** for the wrapper-to-canonical mapping and for React helper extraction patterns.
214
215### 6. Add Resource Metadata and Security
216
217Set resource metadata deliberately on the widget resource/template:
218
2191. `_meta.ui.csp` with exact `connectDomains` and `resourceDomains`.
2202. `_meta.ui.domain` for app submission-ready deployments.
2213. `_meta.ui.prefersBorder` (or OpenAI compatibility alias when needed).
2224. Optional `openai/widgetDescription` to reduce redundant narration.
223
224Avoid `frameDomains` unless iframe embeds are core to the product.
225
226### 7. Enforce the Minimum Working Repo Contract
227
228Every generated repo should satisfy a small, stable contract before you consider it done.
229
230- The repo shape matches the chosen archetype.
231- The MCP server and tools are wired to a reachable `/mcp` endpoint.
232- Tools have clear descriptions, accurate annotations, and UI metadata where needed.
233- Connector-like, data-only, sync-oriented, and company-knowledge-style apps use the standard `search` and `fetch` tool shapes when relevant.
234- The widget uses the MCP Apps bridge correctly when a UI exists.
235- The repo includes enough scripts or commands for a user to run and check it locally.
236- The response explicitly says what validation was run and what was not run.
237
238**Load `references/repo-contract-and-validation.md`** for the detailed checklist and validation ladder.
239
240### 8. Validate the Local Loop
241
242Validate against the minimum working repo contract, not just "did files get created."
243
244**Low-cost checks first:**
245
2461. Static contract review.
2472. Syntax or compile checks when feasible.
2483. Local `/mcp` health check when feasible.
249
250```powershell
251# Example: check if the MCP server responds on the expected endpoint
252curl http://localhost:3000/mcp
253```
254
255**Runtime checks next:**
256
2574. Verify tool descriptors and widget rendering in MCP Inspector.
2585. Test the app in ChatGPT developer mode through HTTPS tunneling.
2596. Exercise retries and repeated tool calls to confirm idempotent behavior.
2607. Check widget updates after host events and follow-up tool calls.
261
262If you are only delivering a scaffold and are not installing dependencies, still run low-cost checks and say exactly what you did not run.
263
264### 9. Connect and Test in ChatGPT (Developer Mode)
265
266For local development, include explicit ChatGPT setup steps.
267
2681. Run the MCP server locally on `http://localhost:<port>/mcp`.
2692. Expose the local server with a public HTTPS tunnel:
270
271```powershell
272ngrok http <port>
273```
274
2753. Use the tunneled HTTPS URL plus `/mcp` path when connecting from ChatGPT.
2764. In ChatGPT, enable Developer Mode under **Settings → Apps & Connectors → Advanced settings**.
2775. In ChatGPT app settings, create a new app for the remote MCP server and paste the public MCP URL.
2786. Tell users to refresh the app after MCP tool/metadata changes so ChatGPT reloads the latest descriptors.
279
280> **Note:** Some docs/screenshots still use older "connector" terminology. Prefer current product wording ("app") while acknowledging both labels when giving step-by-step instructions.
281
282### 10. Plan Production Hosting and Deployment
283
284When the user asks to deploy or prepare for launch, generate hosting guidance for the MCP server (and widget assets if hosted separately).
285
2861. Host behind a stable public HTTPS endpoint (not a tunnel) with dependable TLS.
2872. Preserve low-latency streaming behavior on `/mcp`.
2883. Configure secrets outside the repo (environment variables / secret manager).
2894. Add logging, request latency tracking, and error visibility for tool calls.
2905. Add basic observability (CPU, memory, request volume) and a troubleshooting path.
2916. Re-test the hosted endpoint in ChatGPT Developer Mode before submission.
292
293### 11. Prepare Submission and Publish (Public Apps Only)
294
295Only include these steps when the user intends a public directory listing.
296
2971. Use `apps-sdk/deploy/submission` for the submission flow and `apps-sdk/app-submission-guidelines` for review requirements.
2982. Keep private/internal apps in Developer Mode instead of submitting.
2993. Confirm org verification and Owner-role prerequisites before submission work.
3004. Ensure the MCP server uses a public production endpoint (no localhost/testing URLs) and has submission-ready CSP configured.
3015. Prepare submission artifacts: app metadata, logo/screenshots, privacy policy URL, support contact, test prompts/responses, localization info.
3026. If auth is required, include review-safe demo credentials and test the login path end-to-end.
3037. Submit for review in the Platform dashboard, monitor review status, and publish only after approval.
304
305## Interactive State Guidance
306
307**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).
308
309Use it to choose patterns for:
310
311- State snapshots plus monotonic event tokens (`stateVersion`, `resetCount`, etc.)
312- Idempotent retry-safe handlers
313- `structuredContent` vs `_meta` partitioning
314- MCP Apps bridge-first update flows with optional `window.openai` compatibility
315- Decoupled data/render tool architecture for more complex interactive apps
316
317## Output Expectations
318
319When using this skill to scaffold code, produce output in this order unless the user asks otherwise:
320
321> For direct scaffold requests, do not stop at the plan: give the brief plan, then create the files immediately.
322
3231. Primary app archetype chosen and why
3242. Tool plan and architecture choice (minimal vs decoupled)
3253. Upstream starting point chosen (official example, ext-apps example, or local fallback scaffold) and why
3264. Doc pages/URLs used from `$openai-docs`
3275. File tree to create or modify
3286. Implementation (server + widget)
3297. Validation performed against the minimum working repo contract
3308. Local run/test instructions (including tunnel + ChatGPT Developer Mode app setup)
3319. Deployment/hosting guidance (if requested or implied)
33210. Submission-readiness checklist (for public launch requests)
33311. Risks, gaps, and follow-up improvements
334
335## Prompt Guidance
336
337Use prompts that explicitly pair this skill with `$openai-docs` so the resulting scaffold is grounded in current docs.
338
339Preferred prompt patterns:
340
341- `Use $chatgpt-apps with $openai-docs to scaffold a ChatGPT app for <use case> with a <TS/Python> MCP server and <React/vanilla> widget.`
342- `Use $chatgpt-apps with $openai-docs to adapt the closest official Apps SDK example into a ChatGPT app for <use case>.`
343- `Use $chatgpt-apps and $openai-docs to refactor this Apps SDK demo into a production-ready structure with tool annotations, CSP, and URI versioning.`
344- `Use $chatgpt-apps with $openai-docs to plan tools first, then generate the MCP server and widget code.`
345
346When responding, ask for or infer these inputs before coding:
347
348- Use case and primary user flows
349- Read-only vs mutating tools
350- Demo vs production target
351- Private/internal use vs public directory submission
352- Backend language and UI stack
353- Auth requirements
354- External API domains for CSP allowlists
355- Hosting target and local dev approach
356- Org ownership/verification readiness (for submission tasks)
357
358## Pitfalls
359
360- **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 current docs.
361- **Do not treat wrapper `app.*` helpers as the canonical public API.** They are implementation details. Map them back to `window.openai` or MCP Apps bridge primitives.
362- **Do not use `window.openai` as the only integration path for new apps.** Use the MCP Apps bridge first for portability.
363- **Do not let doc search failure block scaffolding.** If search times out or returns poor matches, fetch canonical Apps SDK pages directly by URL.
364- **Do not prefer older repo patterns over current docs when they differ.** Call out compatibility aliases explicitly.
365- **Do not skip validation.** Even when only delivering a scaffold, run low-cost checks and state exactly what was not run.
366- **Do not submit private/internal apps to the public directory.** Keep them in Developer Mode.
367- **Do not use localhost/testing URLs for submission.** Ensure the MCP server uses a public production endpoint.
368- **Do not put large or sensitive payloads in `structuredContent`.** Move them to `_meta`.
369- **Do not use `frameDomains` unless iframe embeds are core to the product.**
370- **Do not mix multiple primary archetypes.** Pick one and escalate only when the user explicitly asks for public launch.
371- **Do not forget to tell users to refresh the app** after MCP tool/metadata changes so ChatGPT reloads the latest descriptors.
372
373## Verification
374
375After generating or modifying a ChatGPT App, verify the following:
376
377### Static Checks
378
379```powershell
380# Verify file tree matches the chosen archetype
381Get-ChildItem -Recurse -Name | Select-String -Pattern "server|web|package.json"
382
383# Verify MCP server file has no syntax errors (Node.js)
384node --check server/index.ts
385# or
386npx tsc --noEmit
387```
388
389### Local MCP Health Check
390
391```powershell
392# Start the MCP server
393npm run dev
394
395# In a separate terminal, verify the /mcp endpoint responds
396curl http://localhost:3000/mcp
397```
398
399### Tool Descriptor Verification
400
401- Confirm each tool has: name, description starting with "Use this when...", input schema, accurate annotations (`readOnlyHint`, `destructiveHint`, `openWorldHint`, `idempotentHint`).
402- Confirm `structuredContent`, `content`, and `_meta` are returned intentionally per tool.
403- Confirm widget resource/template uses MIME type `text/html;profile=mcp-app` or `RESOURCE_MIME_TYPE`.
404
405### Widget Bridge Verification
406
407- Confirm the widget listens for `ui/notifications/tool-result` via `postMessage`.
408- Confirm rendering comes from `structuredContent`.
409- Confirm `tools/call` is used for component-initiated tool calls.
410- Confirm `window.openai` APIs are used only for extensions, not as the sole integration path.
411
412### CSP and Metadata Verification
413
414- Confirm `_meta.ui.csp` has exact `connectDomains` and `resourceDomains`.
415- Confirm `_meta.ui.domain` is set for submission-ready deployments.
416- Confirm no `frameDomains` unless iframe embeds are core to the product.
417
418### ChatGPT Developer Mode Verification
419
4201. Confirm the MCP server is running on `http://localhost:<port>/mcp`.
4212. Confirm ngrok tunnel is active and the HTTPS URL is reachable.
4223. Confirm the app was created in ChatGPT with the tunneled HTTPS URL + `/mcp` path.
4234. Confirm Developer Mode is enabled under **Settings → Apps & Connectors → Advanced settings**.
4245. Confirm tool calls execute and widget renders correctly in ChatGPT.
4256. Confirm repeated tool calls behave idempotently.
4267. Confirm widget updates after host events and follow-up tool calls.
427
428### Submission Readiness Verification (Public Apps Only)
429
430- [ ] Public production HTTPS endpoint (no localhost/tunnel URLs)
431- [ ] Submission-ready CSP configured
432- [ ] Org verification and Owner-role confirmed
433- [ ] App metadata, logo/screenshots, privacy policy URL, support contact prepared
434- [ ] Test prompts/responses documented
435- [ ] Localization info prepared
436- [ ] Review-safe demo credentials included (if auth required)
437- [ ] Login path tested end-to-end (if auth required)
438
439## References
440
441- `references/app-archetypes.md` — Classifying requests into supported app shapes
442- `references/apps-sdk-docs-workflow.md` — Doc queries, page targets, and code-generation checklist
443- `references/interactive-state-sync-patterns.md` — Reusable patterns for stateful or highly interactive widget apps
444- `references/repo-contract-and-validation.md` — Minimum working repo contract and lightweight validation ladder
445- `references/search-fetch-standard.md` — When and how to default to the standard `search` and `fetch` tools
446- `references/upstream-example-workflow.md` — Choosing between official examples, ext-apps examples, and the local fallback scaffold
447- `references/window-openai-patterns.md` — ChatGPT-specific extensions, wrapper API translation, and React helper patterns
448- `scripts/scaffold_node_ext_apps.mjs` — Minimal Node + `@modelcontextprotocol/ext-apps` fallback starter scaffold
449
450## Related Skills
451
452- `$openai-docs` — Fetch current OpenAI developer documentation; always pair with this skill for docs-first scaffolding
453- `mcp__openaiDeveloperDocs__search_openai_docs` — Direct docs search when `$openai-docs` is unavailable
454- `mcp__openaiDeveloperDocs__fetch_openai_doc` — Direct doc fetch when `$openai-docs` is unavailable