WebMCP na prática com document.modelContext

Onde a API mora agora?

Em setembro de 2026, as ferramentas WebMCP são registradas em document.modelContext, e não mais em navigator.modelContext. O rascunho da especificação define modelContext como atributo de Document, exposto só em contexto seguro, com três métodos: registerTool, getTools e executeTool. O local antigo, no navigator, está depreciado desde o Chrome 150, segundo a leitura de quem acompanha a especificação, e não aparece mais no texto atual.

A assinatura também mudou em relação às primeiras demonstrações. O registerTool recebe a ferramenta e um objeto de opções, onde vai o signal de um AbortController para desregistrar, e devolve uma Promise. A ferramenta tem nome, descrição, inputSchema, a função execute e, agora, annotations, com dicas como readOnlyHint e consequentialHint.

O registerTool recebe a ferramenta e um objeto de opções, onde vai o signal de um AbortController para desregistrar, e devolve uma Promise.

Lucas Ferraz, especialista em SEO

const mc = document.modelContext || navigator.modelContext;
if (mc && typeof mc.registerTool === 'function') {
  const ctrl = new AbortController();
  mc.registerTool({
    name: 'gerar_url_amigavel',
    description: 'Converte um título em slug de URL amigável.',
    inputSchema: { type: 'object', properties: { texto: { type: 'string' } }, required: ['texto'] },
    annotations: { readOnlyHint: true },
    execute: async ({ texto }) => ({ content: [{ type: 'text', text: slugify(texto) }] })
  }, { signal: ctrl.signal }).catch(() => {});
}

O fallback para navigator.modelContext cobre os builds que ainda expõem o local antigo. Quando o Chrome remover o alias, a primeira condição basta.

O que estava errado no meu site?

A implementação que publiquei em 5 de setembro de 2026 checava só navigator.modelContext e não tinha token de origin trial, então nenhuma ferramenta era registrada para um visitante comum. O script fazia feature detection e ficava inerte quando a API não existia, o que é o comportamento certo. O problema é que ele procurava a API no lugar antigo, e no Chrome estável a API só aparece com o token do trial. Duas condições, as duas falhando em silêncio.

Encontrei o erro ao preparar este texto, lendo a especificação atual contra o código. Três ajustes entraram em 25 de setembro. O script passou a procurar primeiro em document.modelContext. O registerTool passou a receber o signal no objeto de opções, como a especificação define. E o tema ganhou a saída da meta tag de origin trial, que imprime o token quando ele estiver configurado.

A busca mostra que o desencontro não é só meu. Em 25 de setembro, o primeiro resultado em português para "webmcp como implementar registerTool" era um tutorial de 17 de setembro que ainda ensinava navigator.modelContext.

O token que liga a API

Fora da flag de teste, o Chrome só expõe o WebMCP em origens registradas no origin trial, que vai do Chrome 149 ao 156. O registro é feito no painel de origin trials do Chrome, para o domínio, e devolve um token. O token vai na página como meta tag http-equiv origin-trial, ou no cabeçalho HTTP Origin-Trial. Para desenvolver, a flag chrome://flags/#enable-webmcp-testing liga a API só na sua máquina.

Como a página que carrega o token pode ficar em cache na CDN, prefiro a meta tag no HTML a um cabeçalho montado por requisição. O HTML é igual para todos os visitantes, e o token também. Quando o trial terminar, o token para de valer e a API some, sem quebrar o site, porque o script continua fazendo feature detection.

Quais ferramentas publiquei?

As cinco ferramentas do site são de leitura ou de navegação, e nenhuma envia dado nem muda estado. Três delas levam a páginas do site: buscar conteúdo, abrir um serviço e ir para o pedido de orçamento. Duas devolvem resultado: gerar um slug de URL, calculado no próprio navegador, e testar a prontidão de um site para IA, que chama a mesma rota pública da ferramenta gratuita. Uma sexta, que só existe na página de contato, preenche o formulário e pede que a pessoa revise e envie.

A regra vem da própria orientação de segurança do Chrome e da natureza da API. A ferramenta roda na página, com a sessão de quem está navegando. Um agente que leu conteúdo malicioso pode chamar uma ferramenta legítima com um pedido falso. Por isso só publico o que um humano não se incomodaria de ver sendo chamado sem aviso, e marco com readOnlyHint o que não muda nada.

Experimento, não canal

O WebMCP ainda é um experimento: a API funciona, mas em setembro de 2026 não encontrei um agente de uso amplo que chame essas ferramentas em produção. No Google I/O de 2026, o Google anunciou o Gemini no Chrome como consumidor, e até lá as ferramentas ficam paradas esperando quem as use. O custo de manter é baixo: um arquivo de script, uma meta tag e um evento no GA4 a cada chamada.

O que acompanho é simples. O evento webmcp_tool no GA4 mostra se alguma ferramenta foi chamada, e o servidor MCP do mesmo site conta as chamadas por ferramenta, sem guardar IP nem argumento. Quando o primeiro número sair do zero, este texto ganha uma atualização com o que foi chamado e de onde.