Torne Seu Site Usável por Agentes de IA: WebMCP, Passo a Passo

Há um novo visitante em seus logs: o agente de IA, atuando em nome de alguém. Neste momento, ele "usa" seu site lendo o DOM e adivinhando qual botão faz o quê. WebMCP substitui a adivinhação por um contrato — sua página declara ferramentas estruturadas que um agente no navegador pode chamar diretamente.

É um padrão W3C em rascunho (Google + Microsoft) que foi lançado como uma prévia inicial no Chrome 146. Aqui está como adicioná-lo, passo a passo, com código para copiar e colar.

O modelo mental (leia isto primeiro)

Uma ferramenta WebMCP é três coisas:

• um nome
• uma descrição que o agente lê para decidir quando chamá-la
• um inputSchema descrevendo seus parâmetros

Quando o agente a chama, seu código é executado na aba do próprio usuário, com sua sessão e permissões, e retorna um resultado. Existem duas maneiras de declarar uma ferramenta — comece com a declarativa.

Passo 1 — Declarativa: exponha um formulário (a vitória fácil)

Se a ação já é um <form> (pesquisa, inscrição, login), adicione dois atributos ao formulário e um a cada entrada. Ele continua funcionando para humanos; o navegador sintetiza uma ferramenta a partir disso.

<form
  tool-name="search-products"
  tool-description="Pesquisar o catálogo de produtos por palavra-chave"
  action="/search" method="get"
>
  <input
    name="query"
    tool-param-description="Palavras-chave para pesquisar, ex. 'tênis de corrida'"
    required
  />
  <button type="submit">Pesquisar</button>
</form>

Como a ferramenta vive em seu HTML, ela sobrevive ao seu passo de construção e é trivial de verificar. Faça disso seu padrão: todo formulário importante recebe tool-name e tool-description.

Passo 2 — Imperativa: registre uma ferramenta em JS (para tudo o mais)

Para lógica que um formulário não pode expressar, registre uma ferramenta com JavaScript. Detecte recursos primeiro para que navegadores não-WebMCP não sejam afetados. O ponto de entrada atual é document.modelContext (prévias mais antigas usavam navigator.modelContext):

const mc = document.modelContext || navigator.modelContext;

if (mc) {
  mc.registerTool({
    name: "add-to-cart",
    description: "Adicionar um produto ao carrinho pelo SKU.",
    inputSchema: {
      type: "object",
      properties: {
        sku: { type: "string", description: "SKU do produto, ex. 'SHOE-42'" },
        quantity: { type: "integer", description: "Quantos adicionar" }
      },
      required: ["sku"],
      additionalProperties: false
    },
    async execute({ sku, quantity = 1 }) {
      const result = await addToCart(sku, quantity); // sua lógica de aplicativo existente
      return { content: [{ type: "text", text: JSON.stringify(result) }] };
    }
  });
}

A chave é: execute chama a mesma função que sua interface de usuário já chama. Você está expondo uma lógica que já possui, não construindo uma segunda integração.

Passo 3 — Retorne a forma correta

O que quer que execute faça, retorne a forma do bloco de conteúdo MCP para que o agente receba um resultado utilizável:

return { content: [{ type: "text", text: JSON.stringify(data) }] };

Passo 4 — Verifique

Duas coisas que vale a pena saber:

• Ferramentas declarativas são fáceis de confirmar — elas estão bem ali em seu HTML.
• Ferramentas imperativas não são — elas só existem depois que seu JS é executado, e em um pacote minificado você não pode visualizá-las.