Referência

Comunicação de componentes com window.openai

O ChatGPT disponibiliza window.openai para aliases de compatibilidade e extensões opcionais do ChatGPT. Ao criar uma interface, use a ponte de comunicação do MCP Apps sempre que a especificação compartilhada oferecer um recurso equivalente. Use window.openai apenas para recursos específicos do ChatGPT.

Consulte Como criar uma interface para o ChatGPT para ver exemplos de implementação passo a passo.

Se a ferramenta exigir confirmação, é normal que toolInput esteja ausente inicialmente. Antes da aprovação, o ChatGPT não carrega nos valores do widget os argumentos que dependem dela. Assim que o usuário aprova a chamada, o host envia esses argumentos por meio de ui/notifications/tool-input.

Recursos

Função auxiliar useOpenAiGlobal

Muitos projetos de interface para o ChatGPT usam pequenas funções auxiliares para acessar window.openai, o que facilita testar as telas. Neste exemplo, a função auxiliar escuta os eventos openai:set_globals do host e permite que componentes React acompanhem as mudanças de um único valor global:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40import { useSyncExternalStore } from "react";

type WebplusGlobals = {
  widgetState: { selectedId?: string | null; [key: string]: unknown } | null;
  toolInput: Record<string, unknown>;
  toolOutput: Record<string, unknown> | null;
  theme: "light" | "dark";
};
const SET_GLOBALS_EVENT_TYPE = "openai:set_globals";

export function useOpenAiGlobal<K extends keyof WebplusGlobals>(
  key: K
): WebplusGlobals[K] {
  return useSyncExternalStore(
    (onChange) => {
      const handleSetGlobal = (event: Event) => {
        if (!(event instanceof CustomEvent)) return;
        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);
      };
    },
    () => {
      const globals = (window as Window & { openai?: WebplusGlobals }).openai;
      if (!globals) throw new Error("This hook requires a ChatGPT app host.");
      return globals[key];
    }
  );
}

Fechar a interface

Chame window.openai.requestClose() para solicitar ao ChatGPT que feche a interface atual.

Solicitar outro modo de exibição

Use window.openai.requestDisplayMode para solicitar a exibição na própria conversa, em picture-in-picture ou em tela cheia:

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

Abrir uma janela modal

Use window.openai.requestModal para abrir uma janela modal controlada pelo host. Informe o URI de outro template de interface registrado pelo mesmo servidor MCP ou omita template para abrir o template atual:

1
2
3await window.openai.requestModal({
  template: "ui://widget/details.html",
});

APIs de arquivos

O ChatGPT oferece funções auxiliares de upload e download de arquivos como extensões opcionais de window.openai.

A biblioteca de arquivos do ChatGPT é opcional e pode não estar disponível para todos os usuários. Quando a função window.openai.selectFiles() está disponível, os arquivos que ela retorna já estão autorizados para o plugin atual. Use o fileId retornado com window.openai.getFileDownloadUrl({ fileId }) ou na entrada de uma ferramenta que aceite parâmetros de arquivo.

Envie um arquivo selecionado pelo usuário:

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

Selecione arquivos que o usuário já enviou ao ChatGPT:

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

Verifique se window.openai.selectFiles está disponível e use window.openai.uploadFile quando a biblioteca de arquivos estiver indisponível.

Solicite uma URL temporária de download:

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

Definir entradas de arquivo

Para que o ChatGPT possa passar arquivos a uma ferramenta, liste cada campo de entrada de arquivo de nível superior em _meta["openai/fileParams"]. O valor de cada campo listado deve ser um objeto de arquivo ou um array de objetos de arquivo.

O schema de cada objeto de arquivo deve declarar as quatro propriedades compatíveis:

Os valores de mime_type e file_name são opcionais, mas você deve declarar essas propriedades no schema. Tanto a etapa Verificar ferramentas quanto o processo de envio do plugin rejeitam um schema de arquivo que omita qualquer uma das quatro propriedades, deixe de marcar como obrigatório algum dos campos download_url e file_id, marque qualquer uma das propriedades opcionais como obrigatória ou exija alguma propriedade além de download_url ou file_id. Você pode declarar outras propriedades opcionais.

Este descritor completo de ferramenta aceita uma entrada de arquivo obrigatória:

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

Para aceitar mais de um arquivo, defina o campo de nível superior como um array e use o mesmo schema de objeto de arquivo em items. A ferramenta pode exigir o campo de arquivo de nível superior independentemente das propriedades obrigatórias de cada objeto de arquivo.

Durante a execução, o ChatGPT passa os valores de arquivo com nomes de campo em snake case:

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

O ChatGPT sempre inclui download_url e file_id, mas pode omitir mime_type e file_name. Use file_id como valor de fileId em window.openai.getFileDownloadUrl({ fileId }) quando o widget precisar de uma nova URL temporária de download.

Ao persistir o estado do widget, use o formato estruturado (modelContent, privateContent, imageIds) se quiser que o modelo tenha acesso aos IDs das imagens nas próximas interações.

Navegação integrada ao host

O ambiente de execução da sandbox replica o histórico de navegação do iframe na interface do ChatGPT. Use APIs de roteamento padrão, como o React Router, e o host manterá seus controles de navegação sincronizados com a interface do componente.

Configuração do roteador com BrowserRouter do React Router:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28import {
  BrowserRouter,
  Routes,
  Route,
  Link,
  useParams,
} from "react-router-dom";
function PizzaListPlugin() {
  const { placeId } = useParams();
  return (
    <main>
      <Link to="/place/pizzeria">Example Pizzeria</Link>
      <p>{placeId ?? "Choose a place"}</p>
    </main>
  );
}

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

Navegação por código:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24import { createElement } from "react";
import { BrowserRouter, useNavigate } from "react-router-dom";
function NavigationExample() {
  const navigate = useNavigate();

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

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

  return createElement(
    "div",
    null,
    createElement(
      "button",
      { onClick: () => openDetails("pizzeria") },
      "Open details"
    ),
    createElement("button", { onClick: closeDetails }, "Close details")
  );
}

Parâmetros do descritor de ferramenta

Por padrão, a descrição de uma ferramenta deve incluir os campos listados na especificação MCP.

Declare outputSchema para toda ferramenta que retorne structuredContent. O schema deve descrever exatamente o objeto que a ferramenta retorna para que os clientes possam validar os resultados e o modelo possa avaliar as próximas chamadas de ferramenta.

Campos _meta do descritor de ferramenta

Use estes campos _meta no descritor da ferramenta. Para associar uma ferramenta a um template de interface, prefira a chave padrão _meta.ui.resourceUri do MCP Apps. O ChatGPT aceita metadados específicos da OpenAI para garantir compatibilidade e oferecer extensões opcionais.

Exemplo:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer({ name: "docs-example", version: "1.0.0" });

// Local example data; replace this with your application data.
async function performSearch(query: string) {
  const documents = [
    {
      id: "intro",
      title: "Introduction to Acme",
      url: "https://example.com/intro",
    },
  ];
  return documents.filter((document) =>
    document.title.toLowerCase().includes(query.toLowerCase())
  );
}

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

Anotações

Para identificar uma ferramenta como “somente leitura”, use os seguintes campos de ToolAnnotations no descritor da ferramenta:

Essas indicações influenciam apenas a forma como o ChatGPT ou o Codex apresenta a chamada da ferramenta ao usuário. Os servidores devem aplicar sua própria lógica de autorização.

Exemplo:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer({ name: "docs-example", version: "1.0.0" });

// Local example data; replace this with your application data.
async function fetchSavedRecipes() {
  return [{ id: "pasta", title: "Tomato pasta" }];
}

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 () => ({
    content: [],
    structuredContent: { recipes: await fetchSavedRecipes() },
  })
);

Campos _meta do recurso do componente

Defina estas chaves no template de recurso que disponibiliza o componente (registerResource). Elas ajudam o ChatGPT a descrever o iframe renderizado e a definir como exibi-lo sem expor metadados a outros clientes.

O ChatGPT aceita a chave legada de compatibilidade _meta["openai/widgetCSP"] com os seguintes nomes de campo em snake_case:

• connect_domains: string[]
• resource_domains: string[]
• frame_domains?: string[]
• redirect_domains?: string[]. Extensão do ChatGPT para destinos de redirecionamento de window.openai.openExternal.

Em geral, prefira o objeto padrão _meta.ui.csp para novas interfaces. Ele aceita os seguintes campos:

• connectDomains: string[]. Domínios que o widget pode acessar via fetch/XHR.
• resourceDomains: string[]. Domínios de recursos estáticos, como imagens, fontes, scripts e estilos.
• frameDomains?: string[]. Lista opcional de origens permitidas para conteúdo incorporado em iframes. Por padrão, os widgets não podem renderizar frames aninhados. Os plugins podem incorporar conteúdo do próprio domínio, inclusive editores e interfaces de administração existentes, de acordo com a política de iframes. É preciso apresentar uma justificativa no envio. O uso de iframes pode exigir uma análise adicional ou atrasar a aprovação.

No entanto, _meta.ui.csp não aceita redirect_domains para links de window.openai.openExternal(...). Para permitir destinos de redirecionamento específicos, ainda é necessário definir _meta["openai/widgetCSP"].redirect_domains.

Declarar os modos de exibição antes de carregar a interface

Defina _meta["openai/ui"].availableDisplayModes no conteúdo do recurso retornado pelo servidor. Se o componente só funcionar em tela cheia, essa declaração permite que o ChatGPT o abra imediatamente nesse modo, sem exibir primeiro um indicador de carregamento na conversa.

Retorne este objeto no array contents do recurso e atribua a html o HTML do componente:

const resource = {
  uri: "ui://widget/viewer.html",
  mimeType: "text/html;profile=mcp-app",
  text: html,
  _meta: {
    "openai/ui": {
      availableDisplayModes: ["fullscreen"],
    },
  },
};

Liste todos os modos que o componente aceita, por exemplo, ["inline", "fullscreen"]. Continue declarando availableDisplayModes também durante a inicialização do MCP Apps. A declaração no servidor complementa esse fluxo, que também aceita modos de exibição dinâmicos.

Resultados de ferramentas

Os resultados de ferramentas podem conter os campos definidos na especificação MCP. Entre eles estão os seguintes:

Apenas structuredContent e content aparecem na transcrição da conversa. O host encaminha _meta ao componente para que você possa preencher a interface sem expor os dados ao modelo.

Metadados que o host fornece no resultado da ferramenta:

Exemplo:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer({ name: "docs-example", version: "1.0.0" });

// Local example data; replace this with your application data.
function generateZooAnimals(count: number) {
  return Array.from({ length: count }, (_, index) => ({
    id: `animal-${index + 1}`,
    name: `Penguin ${index + 1}`,
    species: "Penguin",
  }));
}

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

Resultado de ferramenta com erro

Para retornar um erro no resultado da ferramenta, use a seguinte chave de _meta:

Campos _meta fornecidos pelo cliente

Durante a operação, _meta["openai/userAgent"] e _meta["openai/userLocation"] servem apenas como indicações. Os servidores nunca devem se basear nesses campos para tomar decisões de autorização e devem funcionar mesmo na ausência deles. Trate _meta["openai/userAgent"] como um metadado opcional, fornecido quando possível. Ele não identifica de forma confiável a interface do host que está chamando o servidor.

Exemplo:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer({ name: "docs-example", version: "1.0.0" });

// Local example data; replace this with your application data.
async function findNearbyCafes(city: unknown) {
  return city === "San Francisco"
    ? [{ name: "Example Cafe", address: "123 Example Street, San Francisco" }]
    : [];
}

function formatIntro(locale: unknown, city: unknown) {
  const location = typeof city === "string" ? city : "your area";
  return locale === "es" ? `Cafés en ${location}` : `Cafes in ${location}`;
}

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 userLocation = _meta?.["openai/userLocation"];
    const location =
      typeof userLocation === "object" &&
      userLocation !== null &&
      "city" in userLocation
        ? userLocation.city
        : undefined;
    const cafes = await findNearbyCafes(location);

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