Reference

window.openai component bridge

See build a ChatGPT UI.

File APIs

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

Tool descriptor parameters

Need more background on these fields? Check the Advanced section of the MCP server guide.

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

_meta fields on tool descriptor

We have also require the following _meta fields on the tool descriptor:

Example:

server.registerTool(
  "search",
  {
    title: "Public Search",
    description: "Search public documents.",
    inputSchema: {
      type: "object",
      properties: { q: { type: "string" } },
      required: ["q"],
    },
    securitySchemes: [
      { type: "noauth" },
      { type: "oauth2", scopes: ["search.read"] },
    ],
    _meta: {
      securitySchemes: [
        { type: "noauth" },
        { type: "oauth2", scopes: ["search.read"] },
      ],
      "openai/outputTemplate": "ui://widget/story.html",
      "openai/toolInvocation/invoking": "Searching…",
      "openai/toolInvocation/invoked": "Results ready",
    },
  },
  async ({ q }) => performSearch(q)
);

Annotations

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

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

Example:

server.registerTool(
  "list_saved_recipes",
  {
    title: "List saved recipes",
    description: "Returns the user’s saved recipes without modifying them.",
    inputSchema: {
      type: "object",
      properties: {},
      additionalProperties: false,
    },
    annotations: { readOnlyHint: true },
  },
  async () => fetchSavedRecipes()
);

Need more background on these fields? Check the Advanced section of the MCP server guide.

Component resource _meta fields

Additional detail on these resource settings lives in the Advanced section of the MCP server guide.

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.

The openai/widgetCSP object supports:

• connect_domains: string[] – domains the widget may contact via fetch/XHR.
• resource_domains: string[] – domains for static assets (images, fonts, scripts, styles).
• frame_domains?: string[] – optional list of origins allowed for iframe embeds. By default, widgets cannot render subframes; adding frame_domains opts in to iframe usage and triggers stricter app review.
• redirect_domains?: string[] – optional list of origins that can receive openExternal redirects without the safe-link modal. When the destination matches, ChatGPT appends a redirectUrl query parameter pointing back to the current conversation.

Tool results

The Advanced section of the MCP server guide provides more guidance on shaping these response fields.

Tool results can contain the following fields. Notably:

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

Host-provided tool result metadata:

Example:

server.registerTool(
  "get_zoo_animals",
  {
    title: "get_zoo_animals",
    inputSchema: { count: z.number().int().min(1).max(20).optional() },
    _meta: { "openai/outputTemplate": "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

See the Advanced section of the MCP server guide for broader context on these client-supplied hints.

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.

Example:

server.registerTool(
  "recommend_cafe",
  {
    title: "Recommend a cafe",
    inputSchema: { type: "object" },
  },
  async (_args, { _meta }) => {
    const locale = _meta?.["openai/locale"] ?? "en";
    const location = _meta?.["openai/userLocation"]?.city;

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