リファレンス

window.openai コンポーネントブリッジ

ChatGPT は、互換性のためのエイリアスと任意の ChatGPT 拡張機能を window.openai で提供しています。 新しい UI では、共通仕様に同等の機能がある場合は MCP Apps ブリッジを使用してください。 window.openai は、 ChatGPT 固有の機能にのみ使用してください。

実装手順については、ChatGPT UI の構築をご覧ください。

確認が必要なツールでは、初期状態で toolInput がないことは想定どおりの動作です。 ChatGPT は、承認が必要な引数を承認前にウィジェットの値に読み込みません。 ユーザーが呼び出しを承認すると、 ホストが ui/notifications/tool-input を通じて引数を渡します。

できること

useOpenAiGlobal ヘルパー

多くの ChatGPT UI プロジェクトでは、ビューをテストできるように、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]
  );
}

UI を閉じる操作

window.openai.requestClose() を呼び出して、現在の UI を閉じるよう ChatGPT に要求します。

別の表示モードの要求

window.openai.requestDisplayMode を使用して、インライン、ピクチャーインピクチャー、 または全画面での表示を要求します。

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

モーダルの表示

window.openai.requestModal を使用して、ホストが制御するモーダルを開きます。 同じ MCP サーバーに登録されている別の UI テンプレートの URI を指定するか、 template を省略して現在のテンプレートを開きます。

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

ファイル API

ChatGPT は、window.openai の任意の拡張機能として、 ファイルのアップロードとダウンロード用のヘルパーをサポートしています。

ChatGPT のファイルライブラリはオプション機能であり、すべてのユーザーが利用できるとは限りません。 このヘルパーが利用可能な場合、window.openai.selectFiles() から返されるファイルは、 現在のプラグインでの利用がすでに許可されています。返された fileId は、 window.openai.getFileDownloadUrl({ fileId }) で使用するか、 ファイルパラメーターを使うツール入力に指定してください。

ユーザーが選択したファイルのアップロード：

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

ユーザーが ChatGPT にアップロード済みのファイルの選択：

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

window.openai.selectFiles が利用可能かどうかを確認し、ファイルライブラリを利用できない場合は window.openai.uploadFile にフォールバックしてください。

一時ダウンロード URL のリクエスト：

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

ファイル入力の定義

ChatGPT からツールにファイルを渡せるようにするには、トップレベルの各ファイル入力を _meta["openai/fileParams"] に列挙します。列挙した各フィールドの値は、ファイルオブジェクト、 またはファイルオブジェクトの配列である必要があります。

すべてのファイルオブジェクトのスキーマで、サポートされている 4 つのプロパティをすべて宣言する必要があります：

mime_type と file_name の値は省略可能ですが、スキーマには両方の プロパティを宣言する必要があります。 ツールをスキャン のステップとプラグインの提出時には、 4 つのプロパティのいずれかが欠けている、 download_url と file_id を必須にしていない、省略可能なプロパティのいずれかを必須にしている、または download_url と file_id 以外のプロパティを必須にしているファイルスキーマは拒否されます。 省略可能なプロパティを追加で宣言することはできます。

次の完全なツール記述子は、1 つの必須ファイル入力を受け付けます：

{
  "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"]
  }
}

複数のファイルを受け付けるには、トップレベルのフィールドを配列として定義し、 items に同じファイルオブジェクトのスキーマを使用します。ツールでは、各ファイルオブジェクト内の必須プロパティとは独立して、 トップレベルのファイルフィールドを必須にできます。

実行時には、ChatGPT はスネークケースのフィールド名でファイルの値を渡します：

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

ChatGPT は常に download_url と file_id を含めますが、mime_type と file_name は省略する場合があります。 ウィジェットで新しい一時ダウンロード URL が必要な場合は、 window.openai.getFileDownloadUrl({ fileId }) の fileId の値に file_id を使用してください。

ウィジェットの状態を永続化する際、後続のターンでモデルが画像 ID を参照できるようにするには、構造化された形式（modelContent、privateContent、imageIds）を使用してください。

ホスト連携のナビゲーション

サンドボックスのランタイムは、iframe のナビゲーション履歴を ChatGPT の UI に反映します。React Router などの標準的なルーティング API を使用すると、ホスト側のナビゲーションコントロールが UI と同期されます。

React Router の BrowserRouter を使ったルーターのセットアップ：

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

プログラムによるナビゲーション：

const navigate = useNavigate();

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

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

ツール記述子のパラメーター

基本的に、ツールの記述にはこちらに記載されているフィールドを含めてください。

structuredContent を返すすべてのツールで、outputSchema を宣言してください。 クライアントが結果を検証でき、モデルが後続のツール呼び出しについて推論できるように、 スキーマにはツールが返すオブジェクトを正確に記述してください。

ツール記述子の _meta フィールド

ツール記述子には、以下の _meta フィールドを使用します。ツールを UI テンプレートに関連付ける際は、 MCP Apps 標準のキー _meta.ui.resourceUri を優先してください。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.` }],
    };
  }
);

アノテーション

ツールを「読み取り専用」として指定するには、 ツール記述子で次の ToolAnnotations フィールド を使用します。

これらのヒントが影響するのは、ChatGPT や Codex がツール呼び出しをユーザーにどう説明するかだけです。サーバー側では引き続き独自の認可ロジックを適用する必要があります。

例：

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

コンポーネントリソースの _meta フィールド

コンポーネントを配信するリソーステンプレート（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 拡張機能

新しい UI では、通常、標準の _meta.ui.csp オブジェクトの使用を推奨します。次のフィールドをサポートしています。

• connectDomains: string[]。ウィジェットが fetch/XHR 経由で通信できるドメイン
• resourceDomains: string[]。静的アセット（画像、フォント、スクリプト、スタイル）用のドメイン
• frameDomains?: string[]。iframe の埋め込みを許可するオリジンのリストです（省略可能）。デフォルトでは、ウィジェットはサブフレームを描画できません。プラグインでは、iframe ポリシーに従い、既存のエディターや管理インターフェースなど、自身のドメインのコンテンツを埋め込めます。提出時には利用理由の説明が必要です。また、iframe を使用すると、追加のレビューが必要になったり、承認までに時間がかかったりする場合があります。

ただし、_meta.ui.csp は window.openai.openExternal(...) のリンクに対する redirect_domains をサポートしていません。リダイレクト先を許可リストに登録するには、引き続き _meta["openai/widgetCSP"].redirect_domains を設定する必要があります。

ツールの結果

ツールの結果には、次のフィールドを含めることができます。主なフィールドは以下のとおりです。

会話の記録に含まれるのは 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 フィールド

操作フェーズの _meta["openai/userAgent"] と _meta["openai/userLocation"] は参考情報にすぎません。サーバーはこれらに依存して認可を判断してはならず、これらがなくても動作する必要があります。_meta["openai/userAgent"] は、サーバーを呼び出しているホストの画面を確実に識別する手段ではなく、可能な範囲で提供される任意のメタデータとして扱ってください。

例：

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