API imperativa

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky
François Beaufort
François Beaufort
GitHub

Publicado em: 18 de maio de 2026. Última atualização: 2 de junho de 2026

Explicação Web Extensões Status do Chrome Intenção
GitHub Teste para desenvolvedores Período de teste para desenvolvedores Ver Intenção de experimentar

É possível usar a API imperativa do WebMCP para definir vários tipos de ferramentas com JavaScript padrão. Suas ferramentas podem executar diferentes funções, como entrada de formulário, navegação no site e gerenciamento de estado.

Antes de usar essa API, leia sobre exemplos de casos de uso.

Fornecer contexto do modelo

Use a interface modelContext para registrar ferramentas. O registro de ferramentas exige um nome, uma descrição e um esquema de entrada com propriedades relevantes.

Use registertool para adicionar uma única ferramenta ao contexto do modelo.

WebMCPza Maker

document.modelContext.registerTool({
  name: 'toggle_layer',
  description: 'Control pizza layers (sauce, cheese). Use "add", "remove", or "toggle".',
  inputSchema: {
    type: 'object',
    properties: {
      layer: { type: 'string', enum: ['sauce-layer', 'cheese-layer'] },
      action: { type: 'string', enum: ['add', 'remove', 'toggle'] },
    },
    required: ['layer'],
  },
  execute: async ({ layer, action }) => {
    await toggleLayer(layer, action);
    return `Performed ${action || 'toggle'} on layer: ${layer}`;
  },
});

Verificar o status do pedido

document.modelContext.registerTool({
  name: 'get_order_status',
  description: 'Search orders in a given timeframe. Returns order number, shipping status and location',
  inputSchema: {
    "type": "object",
    "properties": {
      "timeframe": { "type": "string", "oneOf": [
        { "type": "string", "const": "today", "title": "Today" },
        { "type": "string", "const": "yesterday", "title": "Yesterday" },
        { "type": "string", "const": "last_7_days", "title": "Last 7 Days" },
        { "type": "string", "const": "last_30_days", "title": "Last 30 Days" },
        { "type": "string", "const": "last_6_months", "title": "Last 6 Months" }],
      "enum": [ "today", "yesterday", "last_7_days", "last_30_days", "last_6_months" ],
      "description": "Timeframe for the order lookup." }
    },
    "required": [ "timeframe" ]
  },
  execute: async ({ timeframe }) => {
    // Add your API or database logic here to fetch and return the order data as a string.
  },
});

É possível remover uma ferramenta com AbortSignal, quando transmitida como um parâmetro opcional.

const addTodoTool = {
  name: "addTodo",
  description: "Add a new item to the to-do list",
  inputSchema: {
    type: "object",
    properties: { text: { type: "string" } },
  },
  execute: async ({ text }) => {
    // You should handle the persistence logic here (omitted for demo)
    return `Added to-do: ${text}`;
  },
  annotations: {
    readOnlyHint: false,
    untrustedContentHint: true
  },
};
const controller = new AbortController();
document.modelContext.registerTool(addTodoTool, { signal: controller.signal });

// Unregister the tool later...
controller.abort();

Descubra as ferramentas

Para ver as ferramentas disponíveis, use document.modelContext.getTools(). Esse método assíncrono retorna uma lista de ferramentas que o documento de chamada está autorizado a acessar.

const [tool] = await document.modelContext.getTools();
console.log(tool);

// {
//   annotations: { readOnlyHint: false, untrustedContentHint: true },
//   description: "Add a new item to the to-do list",
//   inputSchema: '{"type":"object","properties":{"text":{"type":"string"}}}',
//   name: "addTodo",
//   origin: "https://example.com",
//   window: Window {window: Window, self: Window, ...},
// }

Por padrão, getTools() retorna apenas ferramentas de mesma origem registradas pelo documento de chamada ou outros documentos de mesma origem na árvore de frames. Para recuperar ferramentas de origem cruzada, liste explicitamente as origens delas na opção fromOrigins. Essa matriz só aceita origens seguras.

As ferramentas de documentos de origem cruzada só são incluídas se:

  1. A origem da hospedagem está listada na opção fromOrigins.
  2. A ferramenta foi exposta à sua origem.
// https://example.com

// Get same-origin tools only
const sameOriginTools = await document.modelContext.getTools();

// Get same-origin tools plus tools from specific cross-origin documents
const allTools = await document.modelContext.getTools({
  fromOrigins: ['https://partner.org']
});

Confira a demonstração do agente de página do WebMCP para ver um exemplo de como recuperar ferramentas de um iframe e executá-las em uma interface de chat baseada na Web.

Executar ferramenta

Para executar manualmente uma ferramenta descoberta em getTools(), chame document.modelContext.executeTool() com argumentos de entrada como uma string JSON válida. Esse método assíncrono retorna o resultado da execução da ferramenta ou nulo quando uma navegação é acionada.

const result = await document.modelContext.executeTool(tool, '{"text": "Buy milk"}');
console.log(result);

// 'Added to-do: Buy milk'

É possível cancelar uma execução de ferramenta pendente com AbortSignal, quando transmitido como um parâmetro opcional.

const controller = new AbortController();
document.modelContext.executeTool(tool, '{"text": "Buy milk"}', {
  signal: controller.signal,
});

// Cancel tool execution later...
controller.abort();

Eventos

Os frames podem detectar o evento toolchange em document.modelContext para receber uma notificação quando a lista de ferramentas disponíveis mudar.

document.modelContext.addEventListener("toolchange", (event) => {
  // Tools have changed.
});

iframes entre origens

O WebMCP é compatível com iframes de origem cruzada que usam políticas de permissão e controle de origem explícito.

Política de permissões

O registro de ferramentas fica desativado por padrão em iframes de origem cruzada. Uma página precisa delegar acesso usando a tools política de permissões:

<iframe src="https://example.com" allow="tools"></iframe>

Exposição de origem

Por padrão, as ferramentas não estão disponíveis para documentos de origens diferentes. É possível usar a matriz exposedTo em registerTool para listar origens específicas que podem visualizar e executar uma ferramenta. Essa matriz só aceita origens seguras.

// https://partner.org

document.modelContext.registerTool({
  name: 'my_shared_tool',
  description: 'Shared across origins',
  // ...
}, {
  exposedTo: ['https://example.com']
});

Engajamento e como compartilhar feedback

O WebMCP está em discussão e sujeito a mudanças no futuro. Se você testar essa API e tiver feedback, envie sua opinião.