Reference

window.openai component bridge

ChatGPT provides window.openai for compatibility aliases and optional ChatGPT extensions. New UI should use the MCP Apps bridge whenever the shared specification provides an equivalent, then use window.openai only for ChatGPT-specific capabilities.

See build a ChatGPT UI for implementation walkthroughs.

If your tool requires confirmation, treat missing initial toolInput as expected. ChatGPT does not load approval-gated arguments into widget values before approval; instead, the host delivers them through ui/notifications/tool-input once the user approves the call.

Capabilities

useOpenAiGlobal helper

Many ChatGPT UI projects wrap window.openai access in small helper functions so views remain testable. This example helper listens for host openai:set_globals events and lets React components subscribe to a single global value:

export function useOpenAiGlobal<K extends keyof WebplusGlobals>(
  key: K
): WebplusGlobals[K] {
  return useSyncExternalStore(
    (onChange) => {
      const handleSetGlobal = (event: SetGlobalsEvent) => {
        const value = event.detail.globals[key];
        if (value === undefined) {
          return;
        }

        onChange();
      };

      window.addEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal, {
        passive: true,
      });

      return () => {
        window.removeEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal);
      };
    },
    () => window.openai[key]
  );
}

Close the UI

Call window.openai.requestClose() to ask ChatGPT to close the current UI.

Request another presentation mode

Use window.openai.requestDisplayMode to request inline, picture-in-picture, or fullscreen presentation:

await window.openai?.requestDisplayMode({ mode: "fullscreen" });
// On mobile, picture-in-picture may be presented as fullscreen.

Open a modal

Use window.openai.requestModal to open a host-controlled modal. Provide the URI of another UI template registered by the same MCP server, or omit template to open the current template:

await window.openai.requestModal({
  template: "ui://widget/checkout.html",
});

File APIs

ChatGPT supports file upload/download helpers as optional window.openai extensions.

The ChatGPT file library is optional and may not be available to every user. Files returned from window.openai.selectFiles() are already authorized for the current plugin when the helper is available. Use the returned fileId with window.openai.getFileDownloadUrl({ fileId }) or in a tool input that uses file params.

Upload a user-selected file:

const { fileId } = await window.openai.uploadFile(file, {
  library: true,
});

Select files that the user already uploaded to ChatGPT:

if (window.openai?.selectFiles) {
  const files = await window.openai.selectFiles();
  // [{ fileId, fileName, mimeType }]
}

Feature-detect window.openai.selectFiles and fall back to window.openai.uploadFile when the file library is unavailable.

Request a temporary download URL:

const { downloadUrl } = await window.openai.getFileDownloadUrl({ fileId });

Define file inputs

To let ChatGPT pass files to a tool, list each top-level file input in _meta["openai/fileParams"]. Each listed field must resolve to a file object or an array of file objects.

Every file object schema must declare all four supported properties:

mime_type and file_name are optional values, but you must declare their properties in the schema. The Scan Tools step and plugin submission reject a file schema that omits any of the four properties, does not require download_url and file_id, marks either optional property as required, or requires a property other than download_url or file_id. You can declare extra optional properties.

This complete tool descriptor accepts one required file input:

{
  "name": "analyze_file",
  "title": "Analyze file",
  "description": "Analyzes a user-provided file without modifying it.",
  "inputSchema": {
    "type": "object",
    "$defs": {
      "OpenAIFile": {
        "type": "object",
        "properties": {
          "download_url": { "type": "string" },
          "file_id": { "type": "string" },
          "mime_type": { "type": "string" },
          "file_name": { "type": "string" }
        },
        "required": ["download_url", "file_id"],
        "additionalProperties": false
      }
    },
    "properties": {
      "file": { "$ref": "#/$defs/OpenAIFile" }
    },
    "required": ["file"]
  },
  "annotations": {
    "readOnlyHint": true,
    "openWorldHint": false,
    "destructiveHint": false
  },
  "_meta": {
    "openai/fileParams": ["file"]
  }
}

To accept more than one file, define the top-level field as an array and use the same file object schema in items. The tool can require the top-level file field independently of the properties required inside each file object.

At runtime, ChatGPT passes file values with snake case fields:

{
  "download_url": "https://...",
  "file_id": "file_...",
  "mime_type": "image/png",
  "file_name": "input.png"
}

ChatGPT always includes download_url and file_id; it may omit mime_type and file_name. Use file_id as the fileId value for window.openai.getFileDownloadUrl({ fileId }) when a widget needs a fresh temporary download URL.

When persisting widget state, use the structured shape (modelContent, privateContent, imageIds) if you want the model to see image IDs during follow-up turns.

Host-backed navigation

The sandbox runtime mirrors navigation history from the iframe into ChatGPT’s UI. Use standard routing APIs, such as React Router, and the host keeps its navigation controls in sync with your UI.

Router setup with React Router’s BrowserRouter:

export default function PizzaListRouter() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<PizzaListPlugin />}>
          <Route path="place/:placeId" element={<PizzaListPlugin />} />
        </Route>
      </Routes>
    </BrowserRouter>
  );
}

Programmatic navigation:

const navigate = useNavigate();

function openDetails(placeId: string) {
  navigate(`place/${placeId}`, { replace: false });
}

function closeDetails() {
  navigate("..", { replace: true });
}

Tool descriptor parameters

By default, a tool description should include the fields listed here.

Declare outputSchema for any tool that returns structuredContent. The schema should describe the exact object your tool returns so clients can validate results and the model can reason about follow-up tool calls.

_meta fields on tool descriptor

Use these _meta fields on the tool descriptor. Prefer the MCP Apps standard key _meta.ui.resourceUri for linking a tool to a UI template. ChatGPT supports OpenAI-specific metadata for compatibility and optional extensions.

Example:

import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
import { z } from "zod";

registerAppTool(
  server,
  "search",
  {
    title: "Public Search",
    description: "Search public documents.",
    inputSchema: { q: z.string() },
    outputSchema: {
      results: z.array(
        z.object({
          id: z.string(),
          title: z.string(),
          url: z.string(),
        })
      ),
    },
    securitySchemes: [
      { type: "noauth" },
      { type: "oauth2", scopes: ["search.read"] },
    ],
    _meta: {
      securitySchemes: [
        { type: "noauth" },
        { type: "oauth2", scopes: ["search.read"] },
      ],
      ui: { resourceUri: "ui://widget/story.html" },
      // Optional compatibility alias (ChatGPT only):
      // "openai/outputTemplate": "ui://widget/story.html",
      "openai/toolInvocation/invoking": "Searching…",
      "openai/toolInvocation/invoked": "Results ready",
    },
  },
  async ({ q }) => {
    const results = await performSearch(q);

    return {
      structuredContent: { results },
      content: [{ type: "text", text: `Found ${results.length} results.` }],
    };
  }
);

Annotations

To label a tool as “read-only,” use the following ToolAnnotations fields on the tool descriptor:

These hints only influence how ChatGPT or Codex frames the tool call to the user; servers must still enforce their own authorization logic.

Example:

import { z } from "zod";

server.registerTool(
  "list_saved_recipes",
  {
    title: "List saved recipes",
    description: "Returns the user’s saved recipes without modifying them.",
    inputSchema: {},
    outputSchema: {
      recipes: z.array(
        z.object({
          id: z.string(),
          title: z.string(),
        })
      ),
    },
    annotations: { readOnlyHint: true },
  },
  async () => ({
    structuredContent: { recipes: await fetchSavedRecipes() },
  })
);

Component resource _meta fields

Set these keys on the resource template that serves your component (registerResource). They help ChatGPT describe and frame the rendered iframe without leaking metadata to other clients.

ChatGPT supports the legacy _meta["openai/widgetCSP"] compatibility key with the following snake_case field names:

• connect_domains: string[]
• resource_domains: string[]
• frame_domains?: string[]
• redirect_domains?: string[]. ChatGPT extension for window.openai.openExternal redirect targets.

The standard _meta.ui.csp object is generally preferred for new UI and supports:

• connectDomains: string[]. Domains the widget may contact via fetch/XHR.
• resourceDomains: string[]. Domains for static assets (images, fonts, scripts, styles).
• frameDomains?: string[]. Optional list of origins allowed for iframe embeds. By default, widgets can’t render subframes; adding frameDomains opts in to iframe usage and triggers stricter plugin review.

However, _meta.ui.csp does not support redirect_domains for window.openai.openExternal(...) links. To allowlist redirect targets, you must still set _meta["openai/widgetCSP"].redirect_domains.

Tool results

Tool results can contain the following fields. Notably:

Only structuredContent and content appear in the conversation transcript. The host forwards _meta to the component so you can hydrate UI without exposing the data to the model.

Host-provided tool result metadata:

Example:

import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
import { z } from "zod";

registerAppTool(
  server,
  "get_zoo_animals",
  {
    title: "get_zoo_animals",
    inputSchema: { count: z.number().int().min(1).max(20).optional() },
    outputSchema: {
      animals: z.array(
        z.object({
          id: z.string(),
          name: z.string(),
          species: z.string(),
        })
      ),
    },
    _meta: { ui: { resourceUri: "ui://widget/widget.html" } },
  },
  async ({ count = 10 }) => {
    const animals = generateZooAnimals(count);

    return {
      structuredContent: { animals },
      content: [{ type: "text", text: `Here are ${animals.length} animals.` }],
      _meta: {
        allAnimalsById: Object.fromEntries(
          animals.map((animal) => [animal.id, animal])
        ),
      },
    };
  }
);

Error tool result

To return an error on the tool result, use the following _meta key:

_meta fields the client provides

Operation-phase _meta["openai/userAgent"] and _meta["openai/userLocation"] are hints only; servers should never rely on them for authorization decisions and must tolerate their absence. Treat _meta["openai/userAgent"] as optional, best-effort metadata rather than a stable way to detect which host surface is calling your server.

Example:

import { z } from "zod";

server.registerTool(
  "recommend_cafe",
  {
    title: "Recommend a cafe",
    inputSchema: {},
    outputSchema: {
      cafes: z.array(
        z.object({
          name: z.string(),
          address: z.string(),
        })
      ),
    },
  },
  async (_args, { _meta }) => {
    const locale = _meta?.["openai/locale"] ?? "en";
    const location = _meta?.["openai/userLocation"]?.city;
    const cafes = await findNearbyCafes(location);

    return {
      content: [{ type: "text", text: formatIntro(locale, location) }],
      structuredContent: { cafes },
    };
  }
);