How to Build a ChatGPT App (July 2026)

TL;DR: A ChatGPT App is an MCP App that runs inside ChatGPT. You build an MCP server, define tools, attach UI resources, and let ChatGPT render the UI in a sandboxed iframe. For a fast start, run npx sunpeak new, then pnpm dev. For an existing MCP server, run npx sunpeak inspect --server <url> and test the app UI before you connect it to ChatGPT.

What Is a ChatGPT App?

A ChatGPT App is an interactive app that appears inside a ChatGPT conversation. The model can call your tools, your server can return structured data, and ChatGPT can render a UI resource tied to the tool call.

The useful part is that the UI stays in the conversation. A user can inspect a chart, approve an order, fill out a form, browse search results, or work with a dashboard without leaving the chat thread. The model still has the tool result in context, so the app can support a workflow instead of a single static response.

ChatGPT Apps are built on the MCP Apps standard, an extension to the Model Context Protocol. OpenAI’s current guidance is clear: use the MCP Apps standard keys and the standard ui/* bridge by default, then layer on ChatGPT-specific APIs only when you need ChatGPT-only capabilities like file handling, checkout, or host modals.

At a high level, the system has three parts:

1. Your MCP server declares tools and UI resources.
2. ChatGPT calls the right tool and fetches the matching UI resource.
3. Your UI runs in a sandboxed iframe and exchanges data with the host through postMessage JSON-RPC.

That same structure is why an app can often work beyond ChatGPT. If you keep the core app on MCP Apps APIs, you can test and adapt it for other MCP App hosts instead of rewriting it around one host’s private surface.

Current Official Resources

Use these as the canonical references while you build:

• OpenAI Apps SDK documentation covers ChatGPT App planning, building, deployment, testing, and submission.
• MCP Apps compatibility in ChatGPT explains how ChatGPT maps the Apps SDK to MCP Apps and when to use optional window.openai extensions.
• Connect from ChatGPT documents developer mode, connector setup, metadata refresh, and mobile testing.
• Test your integration lists the current OpenAI testing flow: unit tests, MCP Inspector checks, ChatGPT developer mode, API Playground checks, and a launch regression checklist.
• Build plugins explains how OpenAI packages apps, skills, MCP configuration, hooks, and marketplace metadata inside plugins.
• Submit plugins documents the current public review flow for app-only and app-plus-skills plugins.
• App submission guidelines cover privacy, safety, authentication, permissions, commerce limits, iframe review, and data handling requirements.
• MCP Apps overview explains the standard from the protocol side.
• MCP Apps API docs cover the App class, AppBridge, resource metadata, tool visibility, host context, and display modes.
• Extension support matrix tracks MCP extension support across clients.
• sunpeak quickstart shows how to create a new MCP App or inspect an existing MCP server.

Links matter here because this ecosystem is moving quickly. Treat blog posts, examples, and copied snippets as starting points, then check the official docs before you ship.

Build Path

1. Pick Your Starting Point

If you are building a new app, scaffold a project:

npx sunpeak new chatgpt-app
cd chatgpt-app
pnpm dev

This gives you a TypeScript project with tools, resources, simulation fixtures, a local MCP server, and a browser inspector. The app code follows MCP Apps conventions, so your first version is not locked to one host.

If you already have an MCP server, inspect it directly:

npx sunpeak inspect --server http://localhost:8000/mcp

The standalone inspector works with any MCP server. That is useful when your backend is written in Python, Go, Rust, TypeScript, or anything else that can expose an MCP endpoint.

2. Define the Tool Contract

Start with the tool, not the UI. ChatGPT needs enough metadata to decide when to call your tool, and your UI needs predictable data to render.

A good first tool contract has:

• A short, literal tool name.
• A description that says when the model should use it.
• A strict input schema.
• A result shape that separates model-readable text from UI-ready structuredContent.
• UI metadata that points to the resource URI.

Keep write tools explicit. If a tool creates, edits, deletes, purchases, sends, or submits something, label it as a write action and design for confirmation. OpenAI’s submission guidelines call out accurate action labels because hosts use those labels to apply user approvals and guardrails.

3. Attach a UI Resource

In MCP Apps, the UI is an MCP resource. The tool points to that resource through metadata, usually with a ui:// URI:

{
  "_meta": {
    "ui": {
      "resourceUri": "ui://counter/main"
    }
  }
}

The resource is an HTML document that ChatGPT renders in an iframe. Keep it self-contained, declare the external domains it needs, and avoid assuming it can reach the parent page. It cannot read ChatGPT cookies, local storage, or DOM nodes. That isolation is a feature because it keeps the host and app separated.

Your resource should handle three phases:

1. Initial render before the tool result arrives.
2. Tool input and tool result delivery from the host.
3. User interactions that may call more tools through the host bridge.

sunpeak wraps this in React hooks, so a component can read tool data and host context without writing bridge plumbing by hand. If you are working closer to the protocol, the MCP Apps SDK exposes the lower-level App and transport pieces.

4. Use the Standard Host Bridge

The bridge is the difference between a normal embedded web page and a ChatGPT App. MCP Apps use JSON-RPC over window.postMessage with ui/* methods and notifications.

The standard bridge covers the core tasks:

• Initialize the app and receive host context.
• Receive tool input.
• Receive tool results.
• Call server tools from the UI.
• Send messages back to the conversation.
• Update model-visible UI context when your app state changes.

OpenAI still supports window.openai, but their current MCP Apps compatibility guide says to build around the standard bridge when an equivalent exists. Use window.openai as an optional extension, feature-detect it first, and provide a fallback for hosts that do not support it.

Design for the Host

A ChatGPT App UI should feel like part of the conversation, not a random web page squeezed into an iframe. That mostly comes down to scope and state.

Use inline mode for small results, confirmations, previews, and short forms. Use fullscreen mode for editors, dashboards, maps, canvases, and dense data. Use picture-in-picture when the app should stay visible while the user keeps chatting, such as timers, media controls, or ongoing task monitors.

Test each display mode you declare. The host decides whether to honor a requested transition, so your app should keep working if it stays inline or opens fullscreen later than expected. The UI should also restore state after re-rendering, adapt to dark mode, and respect the container size the host provides.

For styling, prefer host CSS variables where available and use your own fallbacks. That makes the app easier to read across light mode, dark mode, mobile, desktop, and hosts with different typography.

Test Locally Before ChatGPT

Connecting to the real ChatGPT on every code change is slow because you have to rebuild, restart or redeploy, refresh metadata, open a chat, trigger the tool, and inspect the rendered iframe. Do that for final checks, not every edit.

A better development loop is:

1. Run the local MCP server.
2. Load the tool in an inspector.
3. Create simulation fixtures for common tool inputs and tool results.
4. Test display modes, themes, and viewport sizes locally.
5. Automate the cases that should never regress.

sunpeak’s inspector replicates ChatGPT and Claude host runtimes on localhost. It lets you switch host, theme, display mode, device width, tool input, tool result, and simulation state from the sidebar. It also turns those states into URLs, which means the same state can be opened manually or loaded in Playwright.

For a new sunpeak project, the default test path is:

pnpm test

For an existing MCP server, scaffold tests without moving your server into a sunpeak project:

npx sunpeak test init --server http://localhost:8000/mcp
npx sunpeak test

That generates Playwright tests against the inspector. You can add visual regression tests for UI snapshots, live tests against ChatGPT when you need real-host coverage, and evals when you need to measure whether different models call the right tools with the right arguments.

Connect to ChatGPT

When your local tests pass, connect the app to ChatGPT through developer mode.

OpenAI now nests development Apps inside Plugins. That changes the ChatGPT navigation, not your MCP App architecture. Your MCP server, tool contracts, UI resources, Apps SDK compatibility fields, and runtime tests stay the same.

First, expose your MCP endpoint over HTTPS:

ngrok http 8000

Then use the tunnel URL with the /mcp path, for example:

https://abc123.ngrok.app/mcp

In ChatGPT:

Developer mode is required to add a custom app. If it is not enabled yet, open the user component in the bottom-left corner, then go to Settings > Security and login > Developer mode. This is a one-time setup path. After Developer mode is enabled:

1. Open Plugins from the ChatGPT sidebar.
2. Select an existing development app, or use the + button to add one.
3. If adding an app, complete the form with the name, MCP connection, description, icon, and other requested metadata.
4. Open a new chat, enable the development app, and run your test prompts.

When you change tool names, descriptions, schemas, or resource metadata, refresh the development app from the Plugins page. Public app updates go through a new plugin review instead of the developer-mode refresh flow.

Test on mobile before launch if the UI has custom controls. ChatGPT can make the connector available on mobile after you link it on web, and small layout bugs are easier to fix before review.

Deployment and Plugin Submission Checklist

For production, host the MCP server behind a stable HTTPS endpoint. The /mcp route should respond quickly, support streaming where your server needs it, return clear errors, and emit logs you can use to debug failed tool calls.

OpenAI now publishes ChatGPT Apps as plugins. An app-only plugin is still backed by the same MCP App or Apps SDK implementation, so you do not need to rewrite the app or add skills. In the OpenAI Platform plugin portal, select Create plugin, then choose With MCP.

Before submitting the plugin that contains your app:

• Complete individual or business verification for the name you plan to publish under.
• Make sure each submitter has Apps Management: Write access in the OpenAI Platform organization.
• Use a real public MCP endpoint, not a local or testing URL.
• Verify control of the MCP server domain through the portal’s /.well-known/openai-apps-challenge flow.
• Define a strict content security policy with the exact domains your UI fetches from.
• Prepare the plugin name, short and long descriptions, logo, category, website, support URL, privacy policy URL, and terms URL.
• Set accurate readOnlyHint, openWorldHint, and destructiveHint values on every tool.
• Add starter prompts, exactly five positive test cases, and exactly three negative test cases.
• Select the countries or regions where the plugin is ready to operate and be supported.
• Provide review credentials for authenticated apps, with sample data and no MFA, SMS, email confirmation, or private-network requirement.
• Write release notes that describe the plugin, whether it is new or updated, and anything reviewers need to know.
• Remove unused prototype tools so discovery stays clean.
• Verify structured content matches every declared output schema.
• Test negative prompts so the model does not select your app when it should not.

Submit the MCP server URL directly. The plugin portal does not accept an existing plugin_asdk_app... ID as the public app submission. After OpenAI approves the plugin, you choose when to publish it. Published apps and skills appear together in the universal plugin directory, because OpenAI no longer has a separate Apps Directory.

Building for More Than ChatGPT

The safest long-term path is to keep your core app standard-first:

• Use _meta.ui.resourceUri for tool-to-UI linkage.
• Use the ui/* bridge for standard host communication.
• Keep tool contracts portable.
• Feature-detect host-specific APIs.
• Test themes, display modes, and host context changes.

Then add ChatGPT-specific behavior only where it improves the ChatGPT experience. For example, file handling or host modals can make sense in ChatGPT, but they should not break the app when those APIs are absent.

This also gives you a clearer test plan. Your local inspector and automated tests cover the portable MCP App behavior. Live ChatGPT tests cover the ChatGPT-specific path. If you later support another host, you can add host-specific cases without rewriting the app.

Start Building

If you are starting from zero, run npx sunpeak new and build the first tool plus UI resource. If you already have an MCP server, run npx sunpeak inspect --server <url> and see what your app looks like in a replicated host runtime.

Either way, the goal is the same: build the ChatGPT App as a real MCP App, test it locally with deterministic states, then use ChatGPT developer mode for final live checks. That keeps the day-to-day loop fast while still giving you confidence before submission.