Como usar WebMCP para abrir seu site para Agentes

Imagine que, no futuro, agentes de IA ajudem você a reservar passagens aéreas e comprar produtos na web, sem precisar depender de "capturas de tela + adivinhação de botões", que quebram com qualquer alteração no site. Em vez disso, seu site se declara ativamente para o agente: "Eu tenho essas APIs, você pode chamá-las diretamente".

Isso é o que está sendo amplamente discutido pelo W3C: o WebMCP (Web Model Context Protocol).

Se os MCPs criados por diversos especialistas permitem que a IA opere seu "servidor backend", o WebMCP é a chave para que a IA opere diretamente na "interface do usuário" do "navegador do usuário" de forma fluida. Este artigo irá testar no Chrome 151 e ajudá-lo a entender rapidamente a diferença entre APIs declarativas e imperativas, além de apresentar três casos de uso reais oficiais, mostrando como as ferramentas podem surgir dinamicamente com a página!

WebMCP é o que?

WebMCP (Web Model Context Protocol) é um padrão web que está sendo discutido pelo W3C. O conceito central é que os sites, usando JavaScript ou HTML, registram "ferramentas" para navegadores com capacidade de agente. Quando um agente encontra uma ferramenta registrada, ele pode chamar diretamente as funções relacionadas e obter resultados estruturados, sem depender de capturas de tela + adivinhação de botões.

MCP é um padrão de backend, permitindo que agentes se conectem ao seu servidor para obter dados; WebMCP é um padrão de frontend, permitindo que agentes operem a interface do usuário nesta aba que você está com aberta.

A vida útil do MCP é permanente (servidor em execução), enquanto o WebMCP é temporário (desaparece ao fechar a aba). Se você oferece MCP e WebMCP em seu serviço, pode entender que o MCP gerencia a lógica central, enquanto o WebMCP gerencia o tratamento da interface do usuário na última milha.

API Declarativa: duas propriedades, formulário se torna ferramenta

A API declarativa é a parte mais atraente do WebMCP. Você não precisa escrever uma linha de JavaScript; basta adicionar anotações toolname e tooldescription diretamente ao <form> para concluir o registro da ferramenta:

<form toolname="createSupportRequest"
      tooldescription="Submete um pedido de suporte ao cliente.">
  <label for="name">Nome</label>
  <input type="text" id="name" name="name">
  <label for="topic">Tipo de Problema</label>
  <select name="topic" toolparamdescription="Determina a qual equipe o problema deve ser direcionado">
    <option value="billing">Problema de Faturamento</option>
    <option value="tech">Problema Técnico</option>
  </select>
  <button type="submit">Enviar</button>
</form>

Após os testes, descobrimos que document.modelContext.getTools() automaticamente transforma este formulário em um JSON Schema completo — as opções do <select> se tornam anyOf + enum, toolparamdescription, e o texto em chinês do <label> se torna a descrição do campo. Isso significa que, quando o agente reconhece esse schema, ele sabe o que pode ser preenchido neste formulário e quais valores cada campo aceita.

O controle avançado possui três propriedades que você pode usar:

toolparamdescription: descrição do uso de um único campo; se não estiver escrito, usará o texto do <label>.
toolautosubmit: ao adicionar isso, o agente chamará a ferramenta e submeterá o formulário diretamente, sem esperar que alguém clique em enviar.
SubmitEvent.agentInvoked: esse valor booleano informará se "esta submissão foi iniciada pelo agente". Junto com respondWith(Promise), permite que o agente obtenha resultados de execução assíncronos.

Além disso, existem duas pseudo-classes CSS: :tool-form-active e :tool-submit-active, que permitem que o agente mostre os campos que estão sendo preenchidos, e o usuário também pode ver a interface indicando "IA está me ajudando a preencher".

API Imperativa

A API imperativa é adequada para cenários que não envolvem o processamento de formulários — como verificar o status de pedidos, executar diagnósticos e gerenciar estados. Ela oferece três métodos principais, todos disponíveis em document.modelContext:

// Registrar ferramenta
await document.modelContext.registerTool({
  name: 'get_order_status',
  description: 'Consulta o status do pedido, retornando o número do pedido, status de entrega e local',
  inputSchema: {
    type: 'object',
    properties: {
      orderId: { type: 'string', description: 'Número do pedido' }
    },
    required: ['orderId']
  },
  execute: async ({ orderId }) => {
    return `Pedido ${orderId} enviado, status: em entrega`;
  },
});

// Listar ferramentas disponíveis
const tools = await document.modelContext.getTools();

// Executar ferramenta manualmente
const result = await document.modelContext.executeTool(tools[0], '{"orderId": "ORD-123"}');

Os três métodos testados funcionaram normalmente: registerTool registrou com sucesso, getTools() listou ferramentas personalizadas e ferramentas de formulário declarativas, e executeTool retornou corretamente o resultado da execução. Além disso, o evento toolchange será acionado quando a lista de ferramentas mudar, e AbortSignal pode cancelar a execução ou registro da ferramenta.

No entanto, há uma explicação que foi escrita, mas não está muito clara: O Chrome 150 já descontinuou navigator.modelContext, substituindo-o por document.modelContext (em discussão no W3C Web Incubator Community Group). No entanto, em meu Chrome 151, ambos ainda são objetos, então, se você for trabalhar agora, use document.modelContext.

A jornada do demo oficial

O repositório oficial webmcp-tools tem uma pasta de demos com 15 cenários. Testei alguns que têm uma experiência de usuário mais completa, e aqui está um que é um pouco diferente do MCP do servidor: o WebMCP não fornece todas as ferramentas de uma vez, mas as faz surgir conforme o estado da página.