Reference

MCP Apps UI bridge

UI integrations use JSON-RPC 2.0 over postMessage with ui/* methods and notifications.

Common messages:

For an overview and a mapping guide from Apps SDK APIs, see MCP Apps compatibility in ChatGPT.

window.openai component bridge

ChatGPT provides window.openai as an Apps SDK compatibility layer and a set of optional ChatGPT extensions.

See build a ChatGPT UI for implementation walkthroughs.

Capabilities

File APIs

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

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

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";

registerAppTool(
  server,
  "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"] },
      ],
      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 }) => 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 standard _meta.ui.csp object 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 cannot render subframes; adding frameDomains opts in to iframe usage and triggers stricter app review.

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

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

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:

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

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

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),
    };
  }
);