Build, scaffold, refactor, and troubleshoot ChatGPT Apps SDK applications that combine an MCP server and widget UI. Use when Codex needs to design tools, register UI resources, wire the MCP Apps bridge or ChatGPT compatibility APIs, apply Apps SDK metadata or CSP or domain settings, or produce a docs-aligned project scaffold. Prefer a docs-first workflow by invoking the openai-docs skill or OpenAI developer docs MCP tools before generating code.
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.
Use this skill to produce:
window.openai compatibility/extensions second)@modelcontextprotocol/ext-apps starter scaffold for low-dependency fallbacksUse $openai-docs first whenever building or changing a ChatGPT Apps SDK app.
$openai-docs (preferred) or call the OpenAI docs MCP server directly.apps-sdk/build/mcp-serverapps-sdk/build/chatgpt-uiapps-sdk/build/examplesapps-sdk/plan/toolsapps-sdk/referenceapps-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.apps-sdk/deployapps-sdk/deploy/submissionapps-sdk/app-submission-guidelinesIf $openai-docs is unavailable, use:
mcp__openaiDeveloperDocs__search_openai_docsmcp__openaiDeveloperDocs__fetch_openai_docRead references/apps-sdk-docs-workflow.md for suggested doc queries and a compact checklist.
Read references/app-archetypes.md to classify the request into a small number of supported app shapes before choosing examples or scaffolds.
Read references/repo-contract-and-validation.md when generating or reviewing a repo so the output stays inside a stable “working app” contract.
Read references/search-fetch-standard.md when the app is connector-like, data-only, sync-oriented, or meant to work well with company knowledge or deep research.
Read references/upstream-example-workflow.md when starting a greenfield app or when deciding whether to adapt an upstream example or use the local fallback scaffold.
Read references/window-openai-patterns.md when the task needs ChatGPT-specific widget behavior or when translating repo examples that use wrapper-specific app.* helpers.
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:
Before choosing examples, repo shape, or scaffolds, classify the request into one primary archetype and state it.
tool-onlyvanilla-widgetreact-widgetinteractive-decoupledsubmission-readyInfer the archetype unless a missing detail is truly blocking. Use the archetype to choose:
server/ + web/ layoutsearch and fetch should be the default read-only tool surfaceRead references/app-archetypes.md for the decision rubric.
For greenfield apps, prefer these starting points in order:
@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.
Pick one primary archetype before planning tools or choosing a starting point.
submission-ready only when the user asks for public launch, directory submission, or review-ready deployment.Define the tool surface area from user intents.
readOnlyHint, destructiveHint, openWorldHint; add idempotentHint when true).search and fetch tools instead of inventing custom read-only equivalents.Read references/search-fetch-standard.md when search and fetch may be relevant.
Choose the simplest structure that fits the goal.
Prefer the decoupled pattern for non-trivial apps:
structuredContent._meta.ui.resourceUri and optional _meta["openai/outputTemplate"].search first").Default to upstream examples for greenfield work when they are close to the requested app.
@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._meta.ui.*, CSP, URI versioning, and local run instructions.Read references/upstream-example-workflow.md for the selection and adaptation rubric.
Use scripts/scaffold_node_ext_apps.mjs only when the user wants a quick, greenfield Node starter and a vanilla HTML widget is acceptable, and no upstream example is a better starting point.
@modelcontextprotocol/ext-apps server plus a vanilla HTML widget that uses the MCP Apps bridge by default.ui/message bridge and only uses window.openai for optional host signals/extensions.Generate a server that:
text/html;profile=mcp-app) or the SDK constant (RESOURCE_MIME_TYPE) when using @modelcontextprotocol/ext-apps/serverstructuredContent (model + widget), content (model narration), and _meta (widget-only data) intentionallyopenai/toolInvocation/*) when helpful in ChatGPTKeep structuredContent concise. Move large or sensitive widget-only payloads to _meta.
Use the MCP Apps bridge first for portability, then add ChatGPT-specific window.openai APIs when they materially improve UX.
ui/notifications/tool-result (JSON-RPC over postMessage)structuredContenttools/call for component-initiated tool callsui/update-model-context only when UI state should change what the model seesUse window.openai for compatibility and extensions (file upload, modal, display mode, etc.), not as the only integration path for new apps.
app object (for example, @modelcontextprotocol/ext-apps/react) and expose helper names like app.sendMessage(), app.callServerTool(), app.openLink(), or host getter methods.window.openai.callTool(...), window.openai.sendFollowUpMessage(...), window.openai.openExternal(...), window.openai.requestDisplayMode(...), and direct globals like window.openai.theme, window.openai.locale, window.openai.displayMode, window.openai.toolInput, window.openai.toolOutput, window.openai.toolResponseMetadata, and window.openai.widgetState.window.openai or MCP Apps bridge primitives and call out that the wrapper is not the normative API surface.references/window-openai-patterns.md for the wrapper-to-canonical mapping and for React helper extraction patterns.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)openai/widgetDescription to reduce redundant narrationAvoid frameDomains unless iframe embeds are core to the product.
Every generated repo should satisfy a small, stable contract before you consider it done.
/mcp endpoint.search and fetch tool shapes when relevant.Read references/repo-contract-and-validation.md for the detailed checklist and validation ladder.
Validate against the minimum working repo contract, not just “did files get created.”
/mcp health check when feasibleRead references/repo-contract-and-validation.md for the validation ladder.
For local development, include explicit ChatGPT setup steps (not just code/run commands).
http://localhost:<port>/mcpngrok http <port>)/mcp path when connecting from ChatGPTNote: Some docs/screenshots still use older "connector" terminology. Prefer current product wording ("app") while acknowledging both labels when giving step-by-step instructions.
When the user asks to deploy or prepare for launch, generate hosting guidance for the MCP server (and widget assets if hosted separately).
/mcpOnly include these steps when the user intends a public directory listing.
apps-sdk/deploy/submission for the submission flow and apps-sdk/app-submission-guidelines for review requirementsRead 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:
stateVersion, resetCount, etc.)structuredContent vs _meta partitioningwindow.openai compatibilityWhen using this skill to scaffold code, produce output in this order unless the user asks otherwise:
$openai-docsreferences/app-archetypes.md for classifying requests into a small number of supported app shapesreferences/apps-sdk-docs-workflow.md for doc queries, page targets, and code-generation checklistreferences/interactive-state-sync-patterns.md for reusable patterns for stateful or highly interactive widget appsreferences/repo-contract-and-validation.md for the minimum working repo contract and lightweight validation ladderreferences/search-fetch-standard.md for when and how to default to the standard search and fetch toolsreferences/upstream-example-workflow.md for choosing between official examples, ext-apps examples, and the local fallback scaffoldreferences/window-openai-patterns.md for ChatGPT-specific extensions, wrapper API translation, and React helper patternsscripts/scaffold_node_ext_apps.mjs for a minimal Node + @modelcontextprotocol/ext-apps fallback starter scaffold