name	chatgpt-apps-sdk-docs
description	Concise reference and workflow for the ChatGPT Apps SDK (MCP servers, widget UI, auth, state, deployment, submission, UX/UI). Use when answering questions about building, testing, deploying, or submitting ChatGPT apps/connectors, or when summarizing Apps SDK concepts and requirements.

ChatGPT Apps SDK Docs

Overview

Use this skill to answer Apps SDK questions quickly and consistently using the bundled references. Keep responses grounded in the documented flows, schemas, and constraints.

Quick Workflow

Identify the topic area (plan, build, UI, auth, state, deploy, submit, UX/UI, reference APIs, Cloudflare/runtime ops, or mcp-use workflow).
Open the smallest matching file set in references/ (usually one primary file, optionally one secondary file) and pull only the needed details.
If the user asks for the latest changes or requests verification, check the official OpenAI docs before answering.

Intent Routing (MANDATORY)

User intent	Primary reference	Optional secondary reference
Initial setup / local dev / connecting app	`references/quickstart.md`	`references/deploy.md`
Tool/server implementation	`references/build-mcp-server.md`	`references/reference-window-openai.md`
ChatGPT UI bridge / widget behavior	`references/build-chatgpt-ui.md`	`references/reference-window-openai.md`
mcp-use widget scaffolding / React widget workflow	`references/mcp-use-chatgpt-app-builder.md`	`references/quickstart.md`
Cloudflare Workers or transport-specific runtime/debug issues	`references/openai-apps-mcp-operational-playbook.md`	`references/troubleshooting.md`
Auth / OAuth / account linking	`references/auth.md`	`references/security-privacy.md`
State strategy questions	`references/state-management.md`	`references/planning.md`
UX and UI guidance	`references/ux-ui-guidelines.md`	`references/optimize-metadata.md`
Submission / policy readiness	`references/app-submission-guidelines.md`	`references/security-privacy.md`

Do NOT Load (unless explicitly needed)

Do not load all reference files by default.
Do not load monetization docs unless checkout/pricing is part of the request.
Do not load submission/policy docs for pure implementation questions.
Do not load Cloudflare/runtime playbook unless the user is debugging hosting/runtime behavior.
Do not load mcp-use workflow notes unless the user asks about mcp-use, templates, or auto-registered widgets.

NEVER Do

Never invent APIs, tool metadata fields, or SDK behavior not present in the references.
Never claim “latest” without verifying against official docs and stating the date checked.
Never answer from memory when a mapped local reference exists.
Never omit file-path citations for non-trivial answers.

Fallback Rules

If no direct topic match exists, start with references/planning.md and one closest technical file.
If two references conflict, prefer the most specific reference for the asked feature and explicitly note the conflict.
If requested detail is absent in references, say it is absent and point to the nearest related file.
For latest/policy-sensitive requests, verify with official OpenAI docs and include the verification date.

Documentation Map

references/quickstart.md: End-to-end quickstart, local dev, MCP inspector, add app to ChatGPT.
references/planning.md: Use cases, tool design, component planning.
references/build-mcp-server.md: MCP server setup, resources, tools, metadata, CSP, annotations, file params, search/fetch.
references/build-chatgpt-ui.md: window.openai bridge, widget APIs, state, localization, bundling.
references/mcp-use-chatgpt-app-builder.md: mcp-use template workflow, widget folder conventions, useWidget lifecycle, dual-protocol metadata.
references/auth.md: OAuth 2.1 requirements, protected resource metadata, DCR, linking UI.
references/state-management.md: Authoritative vs UI vs durable state patterns.
references/monetization.md: External checkout vs Instant Checkout (beta), requestCheckout flow.
references/deploy.md: Local dev, hosting options, connect, testing, submission.
references/ux-ui-guidelines.md: UX principles, UI guidelines, display modes, visual rules.
references/security-privacy.md: Security, privacy, CSP, prompt injection guidance.
references/optimize-metadata.md: Metadata tuning and golden prompts.
references/app-submission-guidelines.md: App submission requirements and policy highlights.
references/reference-window-openai.md: window.openai API and tool/resource metadata reference.
references/openai-apps-mcp-operational-playbook.md: Cloudflare + MCP operational checklist and high-frequency failure patterns.
references/troubleshooting.md: Common failure modes and fixes.

Notes

Prefer the bundled references for answers; they are the baseline.
When the user needs the latest policy details or release changes, verify with official OpenAI docs and call out the date you checked.
Keep answers concise and action oriented; include code snippets only when asked or when it removes ambiguity.

ChatGPT Apps SDK Docs

Overview

Use this skill to answer Apps SDK questions quickly and consistently using the bundled references. Keep responses grounded in the documented flows, schemas, and constraints.

Quick Workflow

Identify the topic area (plan, build, UI, auth, state, deploy, submit, UX/UI, reference APIs, Cloudflare/runtime ops, or mcp-use workflow).

Open the smallest matching file set in references/ (usually one primary file, optionally one secondary file) and pull only the needed details.

If the user asks for the latest changes or requests verification, check the official OpenAI docs before answering.

Intent Routing (MANDATORY)

User intent

Primary reference

Optional secondary reference

Initial setup / local dev / connecting app

references/quickstart.md

references/deploy.md

Tool/server implementation

references/build-mcp-server.md

references/reference-window-openai.md

ChatGPT UI bridge / widget behavior

references/build-chatgpt-ui.md

references/reference-window-openai.md

mcp-use widget scaffolding / React widget workflow

references/mcp-use-chatgpt-app-builder.md

references/quickstart.md

Cloudflare Workers or transport-specific runtime/debug issues

references/openai-apps-mcp-operational-playbook.md

references/troubleshooting.md

Auth / OAuth / account linking

references/auth.md

references/security-privacy.md

State strategy questions

references/state-management.md

references/planning.md

UX and UI guidance

references/ux-ui-guidelines.md

references/optimize-metadata.md

Submission / policy readiness

references/app-submission-guidelines.md

references/security-privacy.md

Do NOT Load (unless explicitly needed)

Do not load all reference files by default.

Do not load monetization docs unless checkout/pricing is part of the request.

Do not load submission/policy docs for pure implementation questions.

Do not load Cloudflare/runtime playbook unless the user is debugging hosting/runtime behavior.

Do not load mcp-use workflow notes unless the user asks about mcp-use, templates, or auto-registered widgets.

NEVER Do

Never invent APIs, tool metadata fields, or SDK behavior not present in the references.

Never claim “latest” without verifying against official docs and stating the date checked.

Never answer from memory when a mapped local reference exists.

Never omit file-path citations for non-trivial answers.

Fallback Rules

If no direct topic match exists, start with references/planning.md and one closest technical file.

If two references conflict, prefer the most specific reference for the asked feature and explicitly note the conflict.

If requested detail is absent in references, say it is absent and point to the nearest related file.

For latest/policy-sensitive requests, verify with official OpenAI docs and include the verification date.

Documentation Map

references/quickstart.md: End-to-end quickstart, local dev, MCP inspector, add app to ChatGPT.

references/planning.md: Use cases, tool design, component planning.

references/build-mcp-server.md: MCP server setup, resources, tools, metadata, CSP, annotations, file params, search/fetch.

references/build-chatgpt-ui.md: window.openai bridge, widget APIs, state, localization, bundling.

references/mcp-use-chatgpt-app-builder.md: mcp-use template workflow, widget folder conventions, useWidget lifecycle, dual-protocol metadata.

references/auth.md: OAuth 2.1 requirements, protected resource metadata, DCR, linking UI.

references/state-management.md: Authoritative vs UI vs durable state patterns.

references/monetization.md: External checkout vs Instant Checkout (beta), requestCheckout flow.

references/deploy.md: Local dev, hosting options, connect, testing, submission.

references/ux-ui-guidelines.md: UX principles, UI guidelines, display modes, visual rules.

references/security-privacy.md: Security, privacy, CSP, prompt injection guidance.

references/optimize-metadata.md: Metadata tuning and golden prompts.

references/app-submission-guidelines.md: App submission requirements and policy highlights.

references/reference-window-openai.md: window.openai API and tool/resource metadata reference.

references/openai-apps-mcp-operational-playbook.md: Cloudflare + MCP operational checklist and high-frequency failure patterns.

references/troubleshooting.md: Common failure modes and fixes.

Notes

Prefer the bundled references for answers; they are the baseline.

When the user needs the latest policy details or release changes, verify with official OpenAI docs and call out the date you checked.

Keep answers concise and action oriented; include code snippets only when asked or when it removes ambiguity.

chatgpt-apps-sdk-docs