Tutorial WebMCP: como criar sites prontos para agentes com o novo padrão do Chrome

Hoje, agentes de IA navegam na web como um turista lendo um cardápio em outro idioma: forçando a vista nos pixels, tentando adivinhar o que cada botão faz e torcendo para o layout não mudar no meio do clique. Google e Microsoft decidiram que valia a pena resolver isso do jeito certo.

Em fevereiro de 2026, o Chrome 146 lançou uma prévia do WebMCP, um padrão da web proposto que permite que sites digam aos agentes exatamente o que eles podem fazer e como fazer isso. 

Chega de screen-scraping. 

Chega de engenharia reversa do DOM.

Neste tutorial, vou te mostrar o que o WebMCP realmente é, como configurar seu ambiente e, em seguida, criar integrações funcionais usando as abordagens baseadas em HTML e em JavaScript. 

Também vou cobrir dicas de segurança para lidar com invocações de agentes e como testar tudo com as ferramentas de depuração do Chrome.

O que é WebMCP?

WebMCP (Web Model Context Protocol) é um novo padrão de navegador que permite que sites declarem suas capacidades como ferramentas estruturadas que agentes de IA podem chamar diretamente. Em vez de obrigar uma IA a "ler" e clicar por uma interface visual, o WebMCP transforma a própria página em uma API limpa, no cliente.

Pense no que acontece quando um agente tenta reservar um voo em um site de viagens hoje. Ele precisa descobrir qual campo espera a cidade de origem, adivinhar se a data está em MM/DD ou YYYY-MM-DD, localizar o botão de busca e torcer para a página não recarregar com um layout que ele nunca viu. Se o site pudesse publicar uma ferramenta chamada searchFlights com parâmetros tipados para origem, destino, datas e número de passageiros, toda essa adivinhação desapareceria.

O WebMCP torna isso possível. Um site registra ferramentas por meio de uma API do navegador chamada navigator.modelContext, em que cada ferramenta vem com um nome, uma descrição em linguagem natural e um schema JSON para entradas e saídas. O agente descobre essas ferramentas, envia parâmetros que batem com o schema e recebe dados estruturados como resposta.

Engenheiros do Google e da Microsoft elaboraram a especificação juntos no grupo comunitário W3C Web Machine Learning. A arquitetura é totalmente no cliente, o que a diferencia de implantações MCP típicas, onde um servidor backend separado executa as ferramentas. Enquanto o MCP padrão conecta agentes a servidores backend via JSON-RPC, o WebMCP mantém tudo na aba do navegador. 

As ferramentas executam no JavaScript da página; elas compartilham a sessão que o usuário já tem, e o navegador media o que o agente pode ou não fazer. Se você já trabalhou com servidores MCP (por exemplo, no nosso tutorial MCP Model Context Protocol), os conceitos de registro de ferramentas vão soar familiares, mas o modelo de implantação é bem diferente.

Principais recursos e capacidades do WebMCP

Duas APIs estão disponíveis, e servem a propósitos distintos:

• A API declarativa funciona por anotações em HTML. Você adiciona os atributos toolname e tooldescription a um elemento <form> e, opcionalmente, toolparamdescription em campos individuais; o navegador gera um schema JSON a partir da estrutura do formulário. Sites que já têm formulários bem construídos precisam de pouquíssimas mudanças para ficarem acessíveis a agentes.
• A API imperativa te dá controle programático total. Você chama navigator.modelContext.registerTool() e define nome, descrição, schema de entrada e um callback execute. É o caminho para o que for dinâmico demais para um formulário simples: fluxos multi-etapas, chamadas de API, resultados computados e regras de validação customizadas.

Ambas as APIs permitem registro dinâmico, ou seja, ferramentas podem aparecer e desaparecer conforme o estado da página muda. Antes do login, você pode expor apenas uma ferramenta login. Após a autenticação, as ferramentas específicas da conta são registradas.

• Schemas JSON em cada ferramenta especificam tipos, enums, campos obrigatórios e descrições de parâmetros. Essa estrutura impede que agentes inventem valores ou coloquem dados nos campos errados.
• Pseudo-classes CSS dão feedback visual durante interações com agentes. O Chrome aplica :tool-form-active a qualquer formulário que um agente esteja preenchendo e :tool-submit-active ao botão de envio desse formulário. A pessoa na tela vê exatamente qual formulário o agente está usando.

Ainda não há um mecanismo de descoberta embutido. Um agente precisa visitar sua página para aprender quais ferramentas você oferece. O time do Chrome já discutiu a ideia de um arquivo manifesto .well-known/webmcp para descoberta prévia, mas nada foi especificado nessa linha.

Como o WebMCP ainda está em prévia, espere arestas e mudanças contínuas, especialmente porque a especificação já evoluiu entre versões, incluindo a remoção dos métodos provideContext e clearContext em março de 2026. 

A descoberta de ferramentas fica limitada às páginas que você já visitou, e preocupações de segurança como prompt injection e exfiltração de dados via encadeamento de ferramentas são reconhecidas na especificação, mas ainda não totalmente resolvidas. Antes de começar, confira o changelog na documentação do Chrome, pois a API pode ter mudado desde que este tutorial foi escrito.

Pré-requisitos e configuração do ambiente WebMCP

Acertar o ambiente leva alguns minutos, mas a versão errada do Chrome pode te fazer perder bem mais tempo.

É necessário o Chrome Canary versão 146.0.7672.0 ou superior. As versões Stable, Beta e Dev do Chrome não trazem a flag do WebMCP. Vários desenvolvedores nos fóruns do Chrome relataram instalar a versão errada e ficar procurando a flag que não aparecia. Baixe especificamente pela página do Canary.

Página de download do Chrome Canary

Além do navegador, você precisa conhecer formulários HTML e manipulação de eventos em JavaScript. Se quiser um refresco, o curso Introduction to JavaScript da DataCamp cobre os fundamentos. 

A extensão Model Context Tool Inspector não é obrigatória, mas vale instalar. Ela lista todas as ferramentas registradas na página atual, permite executá-las manualmente com parâmetros digitados por você e tem suporte ao Gemini para testar a invocação via linguagem natural.

Ativando a flag experimental do WebMCP

Com o Chrome Canary instalado:

1. Acesse chrome://flags/#enable-webmcp-testing na barra de endereços.
2. Defina a flag "WebMCP for testing" como Enabled.
3. Clique em Relaunch no fim da página.

A página chrome://flags com a flag do WebMCP destacada e definida como Enabled

Depois de reiniciar, abra o DevTools (F12), vá até o Console e rode:

console.log(navigator.modelContext);

Console do DevTools mostrando o objeto navigator.modelContext.

Se aparecer um objeto na saída (e não undefined), a API está disponível. A partir daí, você pode instalar a extensão Model Context Tool Inspector e abrir o demo de viagens do Google para ver o registro de ferramentas funcionando em uma página real. 

Lá, basta abrir a extensão e você deve ver algo como isto:

Checando a ferramenta searchFlights usando a extensão Model Context Tool Inspector do Chrome com o site demo Flight Search do Google. 

Como dá para ver, a extensão detecta a ferramenta searchFlights e expõe seu schema de entrada, dando ao modelo uma noção muito mais clara de como interagir com a página.

Criando sua primeira integração WebMCP

Existem duas formas de construir sua primeira integração WebMCP, e descrevemos ambas nas seções abaixo:

A abordagem declarativa (HTML)

A maneira mais simples de registrar uma ferramenta WebMCP é anotar um formulário que já existe na sua página. Aqui vai um formulário padrão de busca de produtos, sem anotações WebMCP:

<form action="/search" method="GET">
  <label for="query">Search term</label>
  <input type="text" name="query" id="query" required>

  <label for="category">Category</label>
  <select name="category" id="category">
    <option value="all">All categories</option>
    <option value="electronics">Electronics</option>
    <option value="books">Books</option>
    <option value="clothing">Clothing</option>
  </select>

  <button type="submit">Search</button>
</form>

Quatro atributos transformam isso em uma ferramenta acionável por agentes. toolname e tooldescription vão na tag <form>. Em campos individuais, toolparamtitle e toolparamdescription substituem rótulos padrão quando eles não são claros o suficiente para um agente entender:

<form toolname="search_products"
      tooldescription="Search the product catalog by keyword and optional category filter"
      action="/search" method="GET">

  <label for="query">Search term</label>
  <input type="text" name="query" id="query" required
         toolparamdescription="The keyword or phrase to search for in product titles and descriptions">

  <label for="category">Category</label>
  <select name="category" id="category"
          toolparamtitle="Product Category"
          toolparamdescription="Filter results to a specific product category. Use 'all' for no filter.">
    <option value="all">All categories</option>
    <option value="electronics">Electronics</option>
    <option value="books">Books</option>
    <option value="clothing">Clothing</option>
  </select>

  <button type="submit">Search</button>
</form>

O que o navegador faz com esses atributos é gerar internamente um schema JSON. O nome da ferramenta, os tipos de parâmetros, os valores enum das opções do <select> e os marcadores de obrigatório do HTML são aproveitados sem configuração extra.

Para testar, crie um arquivo .html simples no seu computador com qualquer editor de texto, cole o código acima e abra no Chrome usando file:///{seu_arquivo.html}; para a extensão funcionar com arquivo local, abra as configurações da extensão, vá em Detalhes e habilite o acesso a URLs de arquivos, como mostra a imagem abaixo.

Permitindo que a extensão acesse arquivos locais.

Caso contrário, seu navegador não conseguirá interagir com o HTML local. Feito isso, ao abrir o arquivo no Chrome e checar a extensão do WebMCP, você deve ver algo como a captura abaixo. 

A extensão exibindo o schema gerado para a ferramenta search_products após as anotações.

E o que acontece quando um agente chama essa ferramenta? 

O Chrome foca o formulário, preenche os campos com os valores enviados pelo agente e para por aí. A pessoa ainda precisa clicar em Enviar. Esse padrão é proposital: o humano deve confirmar a ação antes de ela acontecer.

Adicionar o atributo toolautosubmit na tag do formulário remove essa etapa de confirmação. Isso faz sentido para operações só de leitura, como buscas. Para qualquer coisa que modifique dados, gere compras ou mude configurações da conta, deixe desativado.

Também dá para interceptar o envio e retornar um resultado estruturado ao agente. O método respondWith() no evento de submit recebe uma promise, e o valor resolvido vira a saída da ferramenta:

<form toolname="search_products"
      tooldescription="Search the product catalog"
      toolautosubmit
      action="/search">
  <input type="text" name="query" required>
  <button type="submit">Search</button>
</form>

<script>
  document.querySelector("form").addEventListener("submit", (e) => {
    e.preventDefault();

    const query = new FormData(e.target).get("query");

    if (!query || query.trim().length === 0) {
      if (e.agentInvoked) {
        e.respondWith(Promise.resolve({
          error: "Search query cannot be empty. Please provide a keyword."
        }));
      }
      return;
    }

    const results = performSearch(query);

    if (e.agentInvoked) {
      e.respondWith(Promise.resolve({
        content: [{ type: "text", text: JSON.stringify(results) }]
      }));
    }
  });
</script>

A booleana agentInvoked no evento de submit é true quando um agente acionou o envio e false para um clique humano normal. Você pode usá-la para alternar entre a formatação de resposta para agentes e o tratamento comum do formulário.

Quando não há toolparamdescription em um campo, o navegador puxa a descrição do elemento <label> associado, ou, na falta dele, do atributo aria-description. Ou seja, um HTML acessível já fornece descrições razoáveis sem esforço extra.

Uma peculiaridade atual: para um grupo de <input type="radio">, toolparamdescription deve ir no primeiro botão do grupo e se aplica ao parâmetro inteiro.

A abordagem imperativa (JavaScript)

Formulários cobrem muita coisa, mas algumas ferramentas precisam trabalhar com estado da aplicação, fazer chamadas a APIs ou retornar resultados computados que não se encaixam em um envio de formulário tradicional. Aqui vai uma ferramenta básica que adiciona itens a uma to-do list:

window.navigator.modelContext.registerTool({
  name: "addTodo",
  description: "Add a new item to the user's to-do list. Use when the user asks to create, add, or remember a task.",
  inputSchema: {
    type: "object",
    properties: {
      text: {
        type: "string",
        description: "The task description"
      },
      priority: {
        type: "string",
        enum: ["low", "medium", "high"],
        description: "Task priority level. Default to 'medium' if not specified by the user."
      }
    },
    required: ["text"]
  },
  execute: ({ text, priority = "medium" }) => {
    const newItem = { id: Date.now(), text, priority, done: false };
    todoApp.addItem(newItem);
    todoApp.renderList();

    return {
      content: [{
        type: "text",
        text: Added task: "${text}" with ${priority} priority. The to-do list now has ${todoApp.getCount()} items.
      }]
    };
  }
});

O callback execute recebe os parâmetros enviados pelo agente (que devem corresponder ao inputSchema), roda sua lógica de aplicação e retorna um array content. 

Um detalhe importante: atualize a UI antes de retornar. 

Agentes às vezes checam como a página ficou após a chamada de uma ferramenta para verificar se funcionou; se a UI ainda não mudou, o agente pode assumir que a chamada falhou. Você pode registrar e cancelar o registro de ferramentas conforme o estado da página evolui:

function onUserLogin(user) {
  navigator.modelContext.registerTool({
    name: "viewOrderHistory",
    description: "Show the user's past orders with dates and totals",
    inputSchema: {
      type: "object",
      properties: {
        limit: {
          type: "number",
          description: "Maximum number of orders to return. Defaults to 10."
        }
      }
    },
    execute: async ({ limit = 10 }) => {
      const orders = await fetchOrders(user.id, limit);
      return {
        content: [{ type: "text", text: JSON.stringify(orders) }]
      };
    }
  });
}

function onUserLogout() {
  navigator.modelContext.unregisterTool("viewOrderHistory");
}

Um cenário mais realista: uma página de reservas de restaurante que checa disponibilidade de mesas. Este exemplo também mostra validação no código, recomendada pela documentação do Chrome, pois restrições do schema ajudam os agentes, mas nem todos as impõem.

navigator.modelContext.registerTool({
  name: "checkAvailability",
  description: "Check table availability for a given date and party size at this restaurant. Returns available time slots.",
  inputSchema: {
    type: "object",
    properties: {
      date: {
        type: "string",
        description: "The desired reservation date in YYYY-MM-DD format"
      },
      partySize: {
        type: "number",
        description: "Number of guests, between 1 and 12"
      }
    },
    required: ["date", "partySize"]
  },
  execute: async ({ date, partySize }) => {
    if (partySize < 1 || partySize > 12) {
      return {
        content: [{
          type: "text",
          text: "Party size must be between 1 and 12. For larger groups, please call the restaurant directly at (555) 123-4567."
        }]
      };
    }

    const parsedDate = new Date(date);
    if (isNaN(parsedDate.getTime()) || parsedDate < new Date()) {
      return {
        content: [{
          type: "text",
          text: "Please provide a valid future date in YYYY-MM-DD format."
        }]
      };
    }

    const slots = await api.getAvailableSlots(date, partySize);
    renderAvailabilityCalendar(date, slots);

    return {
      content: [{
        type: "text",
        text: JSON.stringify({
          date,
          partySize,
          availableSlots: slots.map(s => s.time),
          message: slots.length > 0
            ? Found ${slots.length} available time slots.
            : "No availability for this date. Try a different date or smaller party."
        })
      }]
    };
  }
});

Alguns pontos da documentação do Chrome merecem destaque. Aceite entradas brutas do usuário sempre que possível. Se alguém disser "11:00 a 15:00", sua ferramenta deve aceitar essas strings diretamente, em vez de exigir conversões para formatos internos como minutos desde a meia-noite. 

Valide no código, não só no schema, porque a aplicação de schema varia entre agentes. E só retorne depois que a UI for atualizada, já que os agentes podem olhar a página para confirmar se a operação ocorreu.

Para ferramentas MCP no servidor que complementem uma implementação WebMCP no cliente, nosso guia sobre construir servidores MCP com FastMCP cobre a configuração em detalhe.

Lidando com invocação de agentes e segurança no WebMCP

A especificação do WebMCP parte do princípio de que há um humano acompanhando. Os autores no Google e na Microsoft projetaram para fluxos cooperativos, não operação autônoma. Os mecanismos abaixo refletem essa filosofia.

Detectando IA versus humanos

Uma nova propriedade booleana chamada agentInvoked aparece na interface SubmitEvent. Quando um agente dispara o envio do formulário, ela é true. Quando uma pessoa clica em Enviar normalmente, é false.

document.querySelector("form").addEventListener("submit", (e) => {
  if (e.agentInvoked) {
    console.log("AI agent submitted the form");
    if (!isWithinAgentRateLimit()) {
      e.preventDefault();
      e.respondWith(Promise.resolve({
        error: "Too many requests. Please wait before trying again."
      }));
      return;
    }
  }
});

Além de envios de formulário, há dois eventos em nível de janela que rastreiam atividade de agentes. toolactivated dispara depois que um agente invoca uma ferramenta e o Chrome pré-preenche os campos do formulário associado. toolcancel dispara se o usuário cancelar a operação ou resetar o formulário. 

Nenhum dos eventos é cancelável, mas ambos trazem a propriedade toolName, para você saber qual ferramenta esteve envolvida.

window.addEventListener("toolactivated", ({ toolName }) => {
  showAgentActivityBanner(toolName);
});

window.addEventListener("toolcancel", ({ toolName }) => {
  hideAgentActivityBanner();
});

Aplicando permissões com humano no loop

Com ferramentas declarativas, o padrão é o humano clicar em Enviar após o agente preencher os campos. Esse padrão deve permanecer para tudo que tenha consequências reais.

O atributo toolautosubmit remove essa etapa. Ele pertence a ferramentas de leitura ou baixo risco: buscas, consultas de disponibilidade, verificações de status. 

Tudo que cria, modifica ou exclui dados deve exigir um clique manual.

Você pode estilizar o estado de interação do agente com pseudo-classes CSS:

form:tool-form-active {
  border: 2px solid #2563eb;
  background-color: #eff6ff;
  font-style:normal;font-variant:normal;text-decoration:none;vertical-align:baseline;white-space:pre;white-space:pre-wrap;">1rem;
  border-radius: 8px;
}

form:tool-form-active::before {
  content: "AI agent is filling this form";
  display: block;
  font-size: 0.875rem;
  color: #2563eb;
  font-weight: 600;
  font-style:normal;font-variant:normal;text-decoration:none;vertical-align:baseline;white-space:pre;white-space:pre-wrap;">0.5rem;
}

Um formulário com o estilo :tool-form-active aplicado, mostrando a borda azul e o rótulo "AI agent is filling this form".

Ferramentas imperativas apresentam outro desafio. Não há formulário nem botão de envio; a execução roda imediatamente quando o agente chama a ferramenta. 

Para qualquer operação que não deve acontecer sem aprovação humana, você precisa embutir a confirmação na própria ferramenta:

navigator.modelContext.registerTool({
  name: "deleteAccount",
  description: "Permanently delete the user's account and all associated data. Cannot be undone.",
  inputSchema: {
    type: "object",
    properties: {
      confirmPhrase: {
        type: "string",
        description: "The user must type 'DELETE MY ACCOUNT' to confirm."
      }
    },
    required: ["confirmPhrase"]
  },
  execute: ({ confirmPhrase }) => {
    if (confirmPhrase !== "DELETE MY ACCOUNT") {
      return {
        content: [{
          type: "text",
          text: "Confirmation phrase does not match. Ask the user to confirm explicitly."
        }]
      };
    }

    return new Promise((resolve) => {
      showConfirmationModal("Are you sure?", {
        onConfirm: async () => {
          await api.deleteAccount();
          resolve({ content: [{ type: "text", text: "Account deleted." }] });
        },
        onCancel: () => {
          resolve({ content: [{ type: "text", text: "Deletion cancelled by user." }] });
        }
      });
    });
  }
});

O padrão no ecossistema MCP é consistente: o agente expressa a intenção, o humano confirma a execução. Para uma visão mais ampla de como isso funciona em diferentes implementações MCP, veja nosso panorama de top MCP servers and clients.

Testando sua implementação WebMCP

Depois que sua primeira integração WebMCP estiver rodando, é hora de testar. 

Usando o simulador de agente do Chrome DevTools

Após instalar a extensão Model Context Tool Inspector, um pequeno badge no ícone mostra quantas ferramentas a página atual registrou. Abrindo o pop-up, você vê cada ferramenta com nome, descrição e schema de entrada. Se uma ferramenta que você registrou não aparecer, o registro não funcionou corretamente.

O painel da extensão mostrando várias ferramentas registradas com seus schemas expandidos.

Para testar o simulador de agente, vamos voltar ao site demo Flight Search do Google. Agora dá para testar como executar o app manualmente ou usando linguagem natural. 

Abordagem de execução manual

A execução manual remove o elemento não determinístico do teste com agentes. Selecione uma ferramenta no dropdown do painel da extensão, digite um objeto JSON em "Input Arguments" e clique em "Execute Tool". A extensão chama a ferramenta diretamente com os parâmetros fornecidos.

A extensão com a ferramenta searchFlights selecionada, parâmetros JSON preenchidos e o botão Execute Tool visível.

Isso é útil para isolar problemas. Quando uma ferramenta funciona com parâmetros escritos à mão, mas falha quando o agente chama, o problema está na descrição ou no schema, e não na função execute. Por exemplo, usando o demo do Google:

{
  "origin": "LON",
  "destination": "NYC",
  "tripType": "round-trip",
  "outboundDate": "2026-06-10",
  "inboundDate": "2026-06-17",
  "passengers": 2
}

A página do demo de viagens mostrando resultados após a execução manual.

Teste em linguagem natural

O teste em linguagem natural usa a API do Gemini. Cole uma chave do AI Studio nas configurações da extensão e digite um prompt como 

Search for round-trip flights from London to New York leaving June 10th, returning June 17th, for 2 passengers.

A extensão envia o prompt para o Gemini 2.5 Flash junto com as definições das suas ferramentas, e o modelo decide qual ferramenta invocar e quais parâmetros passar.

Campo de entrada em linguagem natural da extensão com um prompt e a resposta de invocação da ferramenta logo abaixo.

Se o agente escolher a ferramenta errada ou mapear parâmetros de forma incorreta, provavelmente suas descrições precisam ser mais específicas. Boas descrições explicam o que a ferramenta faz em termos positivos ("use isto para checar disponibilidade de voos"), e não o que ela não faz.

Uma sequência prática de testes:

1. Verifique se as ferramentas aparecem na extensão após o carregamento da página.
2. Execute cada ferramenta manualmente com os parâmetros corretos. Confirme se a lógica execute funciona e se a UI atualiza como esperado.
3. Execute com parâmetros ruins. Cheque se sua validação captura os erros e se as mensagens são claras o suficiente para o agente se autocorrigir.
4. Teste com linguagem natural. Veja se o agente escolhe a ferramenta certa e mapeia as palavras do usuário corretamente para o schema.
5. Teste casos de borda: usuários não autenticados, formulários desabilitados, indisponibilidade de APIs e chamadas repetidas rápidas.

Para contexto sobre ferramentas MCP dentro do ecossistema do Google especificamente, nosso tutorial Google MCP Servers cobre vários padrões relevantes. E para uma visão além do Chrome, veja Top Remote MCP Servers.

Conclusão

O WebMCP dá aos sites um canal de comunicação direto com agentes de IA. Em vez de o agente ter que adivinhar a navegação na página, o site publica definições estruturadas de ferramentas, e o agente as chama com parâmetros tipados. A API declarativa transforma formulários existentes em ferramentas chamáveis por agentes com poucos atributos HTML. A API imperativa cobre tudo que é mais complexo. O modelo de segurança mantém o humano no controle das ações que importam.

A especificação ainda é inicial, disponível apenas no Chrome Canary atrás de uma flag e não recomendada para produção. Mas o fato de Google e Microsoft coautoriarem, com governança do W3C, sugere um caminho real para virar um padrão estável da web. Investir tempo agora significa que você já vai dominar os padrões de design de ferramentas e os mecanismos de segurança quando chegar a versão estável.

Se quiser começar a se preparar, faça um inventário dos formulários dos seus sites e identifique quais mais se beneficiariam do acesso por agentes. Formulários de busca e verificadores de disponibilidade são pontos de partida de baixo risco. Quando estiver confortável com a API declarativa neles, avance para ferramentas imperativas nos fluxos que exigem lógica customizada. 

Para continuar explorando o tema, recomendo:

• Tutorial MCP Model Context Protocol para os conceitos fundamentais por trás do WebMCP.
• Construindo servidores MCP com FastMCP para ferramentas MCP no servidor que complementam o WebMCP no cliente.
• Tutorial Google MCP Servers para padrões de integração específicos do Google.
• Top Remote MCP Servers e Top MCP Servers and Clients para o ecossistema mais amplo.