ChatGPT Plugin Extensions: add native UI to an MCP-backed plugin

An MCP-backed plugin exposes operations through its server. The UI gives a person a useful place to inspect or change the result; it does not replace the tool implementation or its authorization. For example, a document tool can return a readable record while a panel shows the same record as an editor. That example is an AgentSkillsHub design suggestion, not a tested integration.

OpenAI’s UI guide makes custom UI optional. It uses an iframe and the MCP Apps JSON-RPC bridge over postMessage. Link selected tools to resources with _meta.ui.resourceUri; implement the shared UI bridge first, then feature-detect OpenAI-specific additions. Keep a model-readable result for clients without component rendering.

Skills supply workflow instructions, MCP tools access data or actions, and the plugin package groups those pieces. See our MCP and agent skills guide for that conceptual separation. A package shared with Codex does not imply that every ChatGPT UI extension renders in Codex.

Read the two sources together. The Extensions page says web extensions for Free and Go are coming soon and composer content mentions are desktop-only. The protocol platform table describes expected support at DevDay launch, not a verified rollout for your account. Its Web means Work browser, excluding classic ChatGPT.

The table records those documented targets as of 2026-09-30. “Expected” is not an account-level availability claim. OpenAI shows Canva sidebar, Figma composer mentions and Adobe file-handler examples; these examples do not establish universal access. For rows without a separate rollout statement, actual availability in your account remains UNKNOWN until tested.

A global entrypoint opens an app from global navigation. Use it for a library or workspace that users revisit. A thread entrypoint opens a distinct app instance beside each conversation; use it for a review queue or document relevant to that chat. These task choices are editorial recommendations.

Register entrypoints in the tool’s _meta["openai/ui"].entrypoints, alongside _meta.ui.resourceUri. Both global and thread entrypoints receive an empty argument object when opened; do not require an identifier that only a prior model tool call could supply. Give a panel a descriptive title that differs from the plugin name. Follow the SDK registration examples for complete server and resource wiring.

Minimal metadata fragment for an original review-board design; not a complete server or a tested example:

{
  "ui": { "resourceUri": "ui://review/board" },
  "openai/ui": { "entrypoints": [{ "type": "thread" }] }
}

Use global instead of thread when the task belongs in the sidebar. This metadata must be attached to a registered tool with a real UI resource.

Structured settings render product preferences on the plugin detail page. A units preference or default project is a better fit than an entire embedded account-management screen. The settings contract advertises readTool and updateTool under openai/settings; the read tool supplies schema, values and layout, and the update tool applies changes. The SDK exposes a settings registration helper.

For protocol 2026-07-28 or newer, advertise the settings extension through server/discover. Older protocol variants have their own initialize path in the spec. Enforce account ownership on reads and updates; a native setting control does not create permission.

A file entrypoint opens a custom view for matching extensions and receives a file resource URI. Use MCP resource reads, subscriptions for updates, and the extension’s openai/resources/write contract when implementing editing. The UI is not given a raw filesystem path. The host can attach the opened path to server tool-call metadata; that is a separate boundary, not unrestricted browser filesystem access.

There is a source discrepancy worth checking before implementation: the overview’s example uses stl, while the normative file-entrypoint section requires a leading dot, such as .stl. Follow the spec and verify with the current SDK/client. This guide avoids offering an untested file registration snippet.

The platform table lists file entrypoints and file resources as desktop-only. Test read, change notification, save and rejected writes on an authorized disposable file. Do not infer web or mobile support from the existence of the SDK.

The extension display-mode contract defines inline and fullscreen resource modes. Advertise availableDisplayModes and, optionally, preferredDisplayMode under resource openai/ui metadata. A preference is a hint the host may decline. The broader UI design guide also discusses picture-in-picture; do not assume that design pattern is an accepted value in this extension field.

Deep links target an item inside a global entrypoint. The host passes the app-relative destination as openai/deepLink during initialization and subsequent context changes. Validate the destination and the user’s access to the record; a link must not bypass authorization. The platform table excludes Android deep-link support.

The current overview also lists Model-App Context, Composer mentions and Rich forms. Model context synchronizes the app’s current context with the chat; content search mentions help users select records in the desktop composer. This is distinct from simply invoking a plugin with @ in Work’s quickstart. Rich forms collect structured input; OpenAI-registered MCP servers require MRTR, while the SDK’s legacy elicitInput example is for direct connections. The specification additionally covers message extensions, onboarding and desktop file-opening/resource APIs.

1. Establish a useful tool-only result and authorize each request using the MCP server guide.
2. Build one MCP Apps component and serve its resource; associate the tool using _meta.ui.resourceUri. Keep the tool’s non-UI result intact.
3. Use the TypeScript SDK: @openai/mcp-extensions/server for server registration and @openai/mcp-extensions/app for the component. It extends the MCP and MCP Apps SDKs; it does not replace either protocol.
4. Register result handlers before connecting the app. Wait for initialization, then check whether the needed extension is exposed. Unsupported extension helpers may remain undefined.
5. Add one entrypoint or setting contract, declare the required CSP origins, and adapt to host theme and size. Check loading, empty and error states, keyboard operation, focus and contrast against the UI guidelines.
6. Test the capability in the intended client before packaging it. An SDK example compiling is not evidence of account rollout.

This sequence is an AgentSkillsHub implementation checklist synthesized from the linked documents. We did not build or connect the review-board example.

The current connection guide starts with a public HTTPS endpoint or Secure MCP Tunnel for development. Enable Settings → Security and login → Developer mode, subject to account/workspace policy. In ChatGPT Plugins, choose the plus button, configure the connection, then inspect the discovered tools and authentication.

Start a new chat and test tool selection, readable results, the intended entrypoint and the optional component. Check authorized and unauthorized operations, state restoration and console errors. After changing UI resources or metadata, restart/deploy your development server, Refresh the developer connection and retest in a new conversation. Test the complete packaged plugin separately.

If the panel is missing, check the client’s support, metadata refresh, registered resource URI and whether the tool accepts entrypoint arguments. If a frame is blank, inspect resource responses, bridge initialization and CSP errors. These are diagnostic checks, not evidence that we reproduced those failures.

Private data and writes need server-side authentication and authorization. Follow OAuth and MCP discovery; validate the account, token scope and resource access for every operation. Never place credentials in the component’s props or model-visible data. Tool annotations describe behavior; they are not permission grants.

The UI security guide describes isolated iframes and strict CSP. Declare specific network/resource origins and frameDomains only when needed. An embedded page uses its own CSP: the parent widget’s connect/resource allowlists do not constrain that page’s network requests. Review the embedded experience too. Do not depend on privileged browser APIs such as native clipboard or window.confirm being available.

Treat document text and model context as untrusted content. UI actions must not silently broaden permissions or hide irreversible effects. Use our MCP server security checklist for a broader authorization review.

Our editorial distinction: UI extensions provide surfaces for a person to inspect and act; MCP Events carry external changes into an existing, user-directed ChatGPT workflow. They can be combined; this is not an official either/or taxonomy. Events do not require UI.

Once tested, package the plugin. The portable format uses root plugin.json, skills/ and mcp.json as applicable; @plugin-creator currently scaffolds a supported Codex compatibility layout. UI/auth remain in the MCP integration. The submission guide accepts skills-only, MCP-only or combined plugins for the directory shared by ChatGPT and Codex. If a previously skills-only public plugin now needs an MCP server, the current submission guide says adding one to that existing plugin is not supported; check that constraint before planning the upgrade. Submitted does not mean Published: after approval, the developer chooses when to publish. No submission was made for this guide.