参考

MCP Apps UI 网桥

UI 集成使用基于 postMessage 的 JSON-RPC 2.0，并通过 ui/* 方法和通知进行通信。

常用消息

有关概览及 Apps SDK API 的映射指南，请参阅 ChatGPT 中的 MCP Apps 兼容性。

window.openai 组件网桥

ChatGPT 提供 window.openai 作为 Apps SDK 兼容层和一组可选的 ChatGPT 扩展。

请参阅 构建 ChatGPT UI 获取实现指南。

能力

useOpenAiGlobal 辅助工具

许多 Apps SDK 项目将 window.openai 访问封装在小的辅助函数中，以便视图保持可测试性。此示例辅助工具会监听宿主 openai:set_globals 事件，并允许 React 组件订阅单个全局值。

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

文件 API

ChatGPT 支持作为可选 window.openai 扩展的文件上传/下载辅助工具。

ChatGPT 文件库是可选的，可能并非对每个用户都可用。当辅助函数可用时，从 window.openai.selectFiles() 返回的文件已获授权给当前应用。请在 window.openai.getFileDownloadUrl({ fileId }) 或使用文件参数的工具输入中使用返回的 fileId。

工具文件引用使用蛇形命名法（snake case）字段

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

download_url 和 file_id 是必需的。mime_type 和 file_name 是可选的。当组件需要新的临时下载 URL 时，请将 file_id 用作 window.openai.getFileDownloadUrl({ fileId }) 的 fileId 值。

在持久化组件状态时，如果您希望模型在后续对话中看到图像 ID，请使用结构化形状（modelContent, privateContent, imageIds）。

工具描述符参数

需要更多关于这些字段的背景信息？请查看 MCP 服务器指南的高级部分。

默认情况下，工具描述应包含此处列出的字段。

为任何返回 structuredContent 的工具声明 outputSchema。该模式应准确描述您的工具返回的对象，以便客户端验证结果，并使模型能够推断后续工具调用。

工具描述符上的 _meta 字段

请在工具描述符上使用这些 _meta 字段。优先使用 MCP Apps 标准键 _meta.ui.resourceUri 来关联工具与 UI 模板。ChatGPT 支持特定于 OpenAI 的元数据以实现兼容性和可选扩展。

示例

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

注释

要将工具标记为“只读”，请在工具描述符上使用以下 注释

这些提示仅影响 ChatGPT 如何向用户表述工具调用；服务器必须始终强制执行自己的授权逻辑。

示例

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

需要更多关于这些字段的背景信息？请查看 MCP 服务器指南的高级部分。

组件资源 _meta 字段

关于这些资源设置的更多详细信息，请参见 MCP 服务器指南的高级部分。

在为您组件提供服务的资源模板 (registerResource) 上设置这些键。它们有助于 ChatGPT 描述和框架化渲染的 iframe，而不会将元数据泄漏给其他客户端。

ChatGPT 支持具有以下 snake_case 字段名的旧版 _meta["openai/widgetCSP"] 兼容性键

• connect_domains: string[]
• resource_domains: string[]
• frame_domains?: string[]
• redirect_domains?: string[]。针对 window.openai.openExternal 重定向目标的 ChatGPT 扩展。

标准 _meta.ui.csp 对象通常更适合新应用并支持

• connectDomains: string[]。小部件可通过 fetch/XHR 联系的域。
• resourceDomains: string[]。静态资产（图像、字体、脚本、样式）的域。
• frameDomains?: string[]。允许 iframe 嵌入的源列表（可选）。默认情况下，小部件不能渲染子框架；添加 frameDomains 表示启用 iframe 使用，并会触发更严格的应用审核。

然而，_meta.ui.csp 不支持 window.openai.openExternal(...) 链接的 redirect_domains。要将重定向目标加入白名单，您仍然必须设置 _meta["openai/widgetCSP"].redirect_domains。

工具结果

MCP 服务器指南的高级部分提供了关于调整这些响应字段的更多指导。

工具结果可以包含以下字段。值得注意的是

只有 structuredContent 和 content 会出现在对话记录中。宿主将 _meta 转发给组件，以便您可以水合 UI 而无需将数据暴露给模型。

宿主提供的工具结果元数据

示例

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

错误工具结果

要在工具结果上返回错误，请使用以下 _meta 键

客户端提供的 _meta 字段

有关这些客户端提供的提示的更广泛背景，请参阅 MCP 服务器指南的高级部分。

操作阶段的 _meta["openai/userAgent"] 和 _meta["openai/userLocation"] 仅为提示；服务器绝不应依赖它们进行授权决策，并且必须容忍它们的缺失。

示例

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