WebMCP: como preparar seu site para agentes de IA com exemplos práticos

As duas formas de implementar WebMCP

A proposta trabalha com duas APIs: imperativa e declarativa.

API imperativa: ferramentas com JavaScript

A API imperativa é adequada para ações que dependem de estado, componentes, regras ou chamadas assíncronas.

Este exemplo representa a busca de produtos em um e-commerce brasileiro:

const controller = new AbortController()

await document.modelContext.registerTool({
  name: 'buscar_produtos',
  description: 'Busca produtos disponíveis e atualiza a vitrine atual. Use quando a pessoa quiser encontrar itens por nome, categoria ou faixa de preço.',
  inputSchema: {
    type: 'object',
    properties: {
      termo: {
        type: 'string',
        description: 'Produto ou categoria procurada.',
      },
      preco_maximo: {
        type: 'number',
        minimum: 0,
        description: 'Valor máximo em reais.',
      },
      entrega_ate: {
        type: 'string',
        format: 'date',
        description: 'Data limite de entrega no formato AAAA-MM-DD.',
      },
    },
    required: ['termo'],
    additionalProperties: false,
  },
  annotations: {
    readOnlyHint: true,
  },
  async execute({ termo, preco_maximo, entrega_ate }) {
    const produtos = await catalogo.buscar({
      termo,
      precoMaximo: preco_maximo,
      entregaAte: entrega_ate,
    })

    vitrine.exibir(produtos)

    return {
      total: produtos.length,
      produtos: produtos.slice(0, 10).map(produto => ({
        id: produto.id,
        nome: produto.nome,
        preco: produto.preco,
        prazo: produto.prazo,
      })),
    }
  },
}, { signal: controller.signal })

// Ao sair da rota ou desmontar o componente:
controller.abort()

Há decisões importantes nesse exemplo:

• o nome descreve uma ação específica;
• a descrição explica o que acontece e quando usar;
• o schema limita formato, faixa e campos extras;
• a função reaproveita a mesma regra usada pela vitrine;
• o retorno é pequeno e estruturado;
• o AbortController remove a ferramenta quando ela deixa de fazer sentido.

Em uma SPA feita com Vue, Nuxt ou React, registrar uma ferramenta e nunca removê-la pode deixar ações antigas disponíveis depois de uma mudança de rota. O ciclo de vida da ferramenta deve acompanhar o ciclo de vida da tela.

Também vale observar o namespace. Exemplos antigos podem usar navigator.modelContext, mas a documentação atual orienta document.modelContext. Como a proposta ainda está evoluindo, confirme a versão antes de colocar um experimento em produção.

API declarativa: formulários que viram ferramentas

Quando a ação já é um formulário HTML, a opção declarativa pode exigir menos código. A página adiciona atributos que descrevem o formulário e seus campos.

<form
  toolname="abrir_chamado"
  tooldescription="Prepara uma solicitação de suporte para a conta autenticada."
  action="/suporte/chamados"
>
  <label for="assunto">Assunto</label>
  <input
    id="assunto"
    name="assunto"
    required
    toolparamdescription="Resumo objetivo do problema."
  >

  <label for="categoria">Categoria</label>
  <select
    id="categoria"
    name="categoria"
    required
    toolparamdescription="Área responsável pelo atendimento."
  >
    <option value="financeiro">Financeiro</option>
    <option value="acesso">Acesso à conta</option>
    <option value="produto">Uso do produto</option>
  </select>

  <label for="detalhes">Detalhes</label>
  <textarea id="detalhes" name="detalhes" required></textarea>

  <button type="submit">Revisar e enviar</button>
</form>

Quando o agente invoca essa ferramenta, o navegador pode focar o formulário e preencher os campos. Sem toolautosubmit, a pessoa ainda precisa clicar para enviar. Isso é uma boa escolha para chamados, inscrições e operações em que vale revisar o conteúdo.

Com toolautosubmit, o envio pode acontecer automaticamente. Essa opção deve ser reservada a ações de baixo risco, como aplicar um filtro ou executar uma busca. Comprar, cancelar, excluir ou contratar são verbos que pedem uma etapa humana explícita.

Um cenário completo: atendimento de um SaaS brasileiro

Considere um sistema usado por pequenas empresas para emitir cobranças e acompanhar pagamentos.

Um cliente abre o painel e pede ao agente do navegador:

“Veja por que a cobrança da Loja Centro ainda aparece como pendente e, se for necessário, prepare um chamado para o financeiro.”

A aplicação poderia registrar ferramentas em etapas:

1. buscar_cliente_por_nome, disponível na lista de clientes;
2. consultar_cobrancas, registrada depois que um cliente é selecionado;
3. executar_diagnostico_de_cobranca, disponível na tela da cobrança;
4. preparar_chamado_financeiro, liberada quando o diagnóstico não resolve o caso.

O agente navega por capacidades que aparecem conforme o estado da interface. Ele não recebe todos os recursos do sistema de uma vez.

Esse desenho reduz ambiguidade e exposição. A ferramenta de diagnóstico usa o cliente selecionado e a sessão autenticada. Ela não deveria aceitar um empresa_id arbitrário enviado pelo modelo, porque isso abriria espaço para consultar dados de outra conta.

Na etapa final, o chamado pode ser preparado, mas a pessoa revisa o resumo e confirma o envio. O ganho não vem de esconder o produto. Vem de encurtar um fluxo complexo sem retirar controle do usuário.

Benefícios que podem justificar a implementação

Menos dependência de cliques simulados

Uma ferramenta com schema é mais previsível do que uma sequência baseada em coordenadas, textos e aparência. Mudanças visuais deixam de quebrar ações que usam a lógica do produto.

Reutilização do estado e da autenticação

O WebMCP opera na página atual. Isso permite aproveitar usuário autenticado, item selecionado, filtros, permissões e stores já carregadas, sem criar uma segunda experiência do zero.

Usuário continua dentro do produto

A interface permanece visível. A empresa preserva contexto, marca, mensagens de orientação e pontos de confirmação. Isso é diferente de uma integração de backend que executa tudo longe do site.

Menos etapas e menos interpretação

Uma ação estruturada pode substituir vários ciclos de captura, clique e verificação. A economia exata depende do fluxo, mas a arquitetura reduz passos ambíguos.

Adoção progressiva

É possível começar com uma ou duas tarefas de alto valor. Navegadores sem suporte continuam usando o site normal. O WebMCP atua como melhoria progressiva, não como requisito para acessar o produto.

Uma nova camada de experiência do produto

Ferramentas bem desenhadas podem se tornar parte da proposta do software: “nosso agente ajuda a conciliar”, “o navegador prepara a reserva” ou “o suporte diagnostica a conta com você”. A decisão deixa de ser apenas técnica e passa a envolver produto, operação e confiança.

Onde o WebMCP ainda falha ou não faz sentido

WebMCP está em fase experimental. A proposta, a implementação dos navegadores e até nomes da API podem mudar.

Ele também não resolve todos os problemas:

• o agente precisa visitar uma página para descobrir suas ferramentas;
• clientes e navegadores ainda precisam implementar o padrão;
• interfaces complexas podem exigir refatoração do estado;
• uma ferramenta mal descrita continua produzindo escolhas ruins;
• o schema valida formato, mas não substitui autorização;
• ações totalmente autônomas e sem interface continuam sendo território de APIs e MCP de backend;
• adicionar WebMCP não garante tráfego orgânico, citação por modelos ou aumento de conversão.

Para um site institucional simples, com páginas somente de leitura, dados estruturados, boa acessibilidade e conteúdo rastreável talvez sejam prioridades maiores. WebMCP começa a fazer mais sentido quando existe uma tarefa interativa relevante.

Boas práticas para ferramentas úteis e seguras

Comece pela tarefa, não pela quantidade

Liste os fluxos em que o usuário mais erra, demora ou abandona. Escolha uma ação de leitura e uma ação de preparação. Evite registrar dezenas de ferramentas apenas porque é possível.

Quanto mais ferramentas parecidas o agente recebe, mais difícil fica escolher a correta. buscar_pedido, consultar_pedido e ver_pedido provavelmente deveriam ser uma única capacidade.

Use nomes que revelem a consequência

Existe uma diferença importante entre preparar_cancelamento e cancelar_assinatura. O primeiro abre ou preenche uma etapa. O segundo indica que a consequência acontece imediatamente.

A descrição deve explicar o que a ferramenta faz, em qual estado pode ser usada e qual resultado devolve. Instruções vagas transferem a ambiguidade para o modelo.

Trate o schema como contrato

Defina tipos, campos obrigatórios, enumerações, limites e descrições. Use additionalProperties: false quando campos extras não forem aceitos.

Mesmo assim, valide novamente dentro da aplicação e no servidor. O agente é um cliente, não uma autoridade confiável.

Reutilize a mesma regra de negócio da interface

Botão e ferramenta devem chamar a mesma função de domínio. Duplicar a lógica cria dois comportamentos, dois conjuntos de bugs e resultados divergentes.

Em um projeto Vue ou Nuxt, a ferramenta pode chamar um serviço ou uma action da store. Evite manipular elementos do DOM como se estivesse criando seu próprio robô de cliques.

Registre somente ferramentas válidas naquele estado

Se não há produto selecionado, não registre adicionar_ao_carrinho. Se a conta não tem permissão financeira, não exponha preparar_reembolso.

Disponibilidade dinâmica ajuda o agente a entender o produto e reduz o contexto enviado ao modelo.

Nunca confie apenas na sessão do frontend

O backend deve conferir autenticação, tenant, papel, propriedade do recurso e limites da operação. O fato de uma ferramenta rodar dentro de uma página autenticada não autoriza qualquer argumento enviado a ela.

Para mutações, adote idempotência quando fizer sentido. Se houver repetição por timeout, o sistema não deve criar duas cobranças ou dois chamados.

Separe leitura, preparação e confirmação

Uma arquitetura segura costuma ter três níveis:

1. ferramentas de leitura podem executar diretamente;
2. ferramentas de preparação alteram estado temporário ou preenchem a interface;
3. ações irreversíveis exigem confirmação visível.

Pagamento, exclusão, publicação, alteração de plano e envio de mensagem para terceiros merecem cuidado especial.

Registre observabilidade própria

Meça qual ferramenta foi descoberta, chamada, concluída, cancelada ou rejeitada. Registre duração e código de erro sem armazenar prompts, documentos ou dados pessoais desnecessários.

No Brasil, esse desenho também precisa respeitar finalidade, minimização e segurança no tratamento de dados pessoais. WebMCP não cria uma exceção à LGPD.

Teste com frases reais, não só chamadas manuais

Uma ferramenta pode funcionar tecnicamente e ainda ser mal escolhida pelo agente. Crie testes com pedidos ambíguos, campos ausentes, valores extremos, repetição e tentativas sem permissão.

O inspetor de WebMCP do Chrome permite visualizar ferramentas, validar schemas e fazer chamadas manuais. Depois, teste com linguagem natural e acompanhe se o agente escolhe a ação correta.

Como começar um experimento sem comprometer o produto

Um primeiro piloto pode seguir este roteiro:

1. escolha uma página autenticada com uma tarefa frequente;
2. mapeie a função de domínio usada hoje pela interface;
3. registre uma ferramenta somente de leitura;
4. crie um schema pequeno e restritivo;
5. devolva um resultado estruturado e curto;
6. conecte o ciclo de registro à rota ou ao componente;
7. teste sucesso, erro, cancelamento e falta de permissão;
8. compare tempo, taxa de conclusão e necessidade de intervenção;
9. só então experimente uma ação de preparação com confirmação humana.

Para desenvolvimento local, a documentação atual do Chrome indica o recurso experimental chrome://flags/#enable-webmcp-testing. A disponibilidade e o processo de testes podem mudar, portanto esse passo deve ser conferido na documentação mais recente.

Onde a Cloudflare entra nessa história

A Cloudflare anunciou um preview que pode adicionar uma ponte WebMCP na borda, sem exigir alteração no código de origem do site. A ativação fica na área de Agent Readiness e injeta um módulo em respostas HTML.

O preview começou com dois pacotes. Um expõe ferramentas relacionadas a credenciais C2PA em imagens. O outro conecta a página a um servidor MCP no mesmo domínio, por padrão em /mcp, reutilizando a sessão do visitante.

Isso é útil para experimentar, principalmente em sites estáticos ou aplicações em que alterar o deploy é mais trabalhoso. Mas a ponte não descobre automaticamente toda a lógica de negócio escondida em botões. Para oferecer ferramentas como consultar_fatura ou preparar_reembolso, ainda é necessário projetar capacidades e conectá-las às regras do produto, seja na página, seja em um servidor MCP.

O valor do anúncio da Cloudflare está em reduzir a barreira de distribuição e teste. O conceito do WebMCP continua independente da Cloudflare e depende de adoção mais ampla por navegadores, agentes, frameworks e sites.