WebMCP na prática com document.modelContext

O que é WebMCP?

O WebMCP é uma API JavaScript proposta no grupo comunitário Web Machine Learning do W3C que deixa a página expor funções como ferramentas para agentes de IA e tecnologias assistivas chamarem no navegador. Cada ferramenta tem nome, descrição em linguagem natural e um schema de entrada, e o agente decide quando chamar. O Chrome descreve duas APIs, a declarativa, que transforma um formulário HTML em ferramenta, e a imperativa, que registra a ferramenta por JavaScript.

O WebMCP difere do MCP no lugar onde a ferramenta roda. No MCP, a ferramenta roda em um servidor que o agente acessa pela rede. No WebMCP, ela roda no script da própria página, com a sessão de quem está navegando. O lado do servidor está no texto sobre servidor MCP em um site.

O WebMCP deixa a página registrar ferramentas que um agente de IA chama no navegador, com a sessão de quem navega, enquanto no MCP a ferramenta roda em um servidor.

Lucas Ferraz, especialista em SEO

Onde a API mora agora?

O WebMCP registra ferramentas em document.modelContext, e não em navigator.modelContext, na especificação e na documentação do Chrome de novembro de 2026. 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 navigator.modelContext é o local antigo, que alguns builds ainda expõem como alias, e não aparece no texto atual da especificação.

A assinatura também mudou em relação às primeiras demonstrações. O registerTool recebe a ferramenta e um objeto de opções, onde vão o signal de um AbortController para desregistrar e a lista exposedTo, e devolve uma Promise. A ferramenta tem name, title, description, inputSchema, outputSchema, a função execute e annotations. A especificação define só quatro anotações, todas booleanas, readOnlyHint, untrustedContentHint, consequentialHint e debugging. Pela documentação do Chrome, a partir do Chrome 153 desregistrar uma ferramenta não cancela as execuções que já estão em andamento.

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 começou no Chrome 149 e, pela extensão registrada em 28 de setembro de 2026, vai até o Chrome 162. O trial original terminava no Chrome 156, e o Chrome Status atribui a extensão às melhorias feitas na API a partir do retorno do trial. A data de calendário do fim não foi publicada.

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?

O lucasferraz.com serve 14 ferramentas WebMCP em /agentes/webmcp.js, e 12 delas levam readOnlyHint verdadeiro. O arquivo é gerado de um template com as ferramentas da mesma função que alimenta o servidor MCP do site em /mcp, então os dois saem de uma definição só. As ferramentas ficam em dois grupos.

• Do servidor (8): search_content, list_studies, get_study, list_posts, get_page_markdown, get_author_profile, get_book e cite, cujo execute chama o /mcp da mesma origem, sem credencial, e marca a chamada com a origem webmcp;
• Da página (6): get_current_page, list_page_sections, scroll_to_section, open_faq_answer, navigate_to e set_color_theme, que só existem no navegador.

O registro das ferramentas do servidor é um laço curto sobre a mesma lista do /mcp.

TOOLS.forEach(function (t) {
  registrar({
    name: t.name, title: t.title, description: t.description, inputSchema: t.inputSchema, annotations: t.annotations,
    execute: function (input) { return chamarMcp(t.name, input); }
  });
});

As duas sem readOnlyHint verdadeiro são navigate_to, que abre outra página do próprio site, e set_color_theme, que troca o tema claro ou escuro. As duas mudam a página, e nenhuma das duas envia dado. No site da agência, as ferramentas WebMCP seguem a mesma regra, e a que leva ao pedido de orçamento é um caso pequeno de comércio agêntico, com o envio sempre na mão de quem navega.

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.

Relendo o código contra a IDL de 2 de novembro, achei um resíduo do MCP. O objeto de anotações do site leva também destructiveHint, idempotentHint e openWorldHint, que vêm das anotações do MCP e não existem na ToolAnnotations do WebMCP. Na conversão de dicionário do WebIDL, membro desconhecido é ignorado, então nada quebra, mas essas três dicas não dizem nada ao navegador.

Experimento, não canal

O WebMCP ainda é um experimento, e até novembro de 2026 não encontrei fonte primária de um agente de uso amplo que chame essas ferramentas em produção. No Google I/O de 2026, o Google anunciou que o Gemini no Chrome vai suportar o WebMCP em breve, o que é promessa e não uso. O custo de manter é baixo, com um script gerado da mesma definição do servidor MCP e uma meta tag com o token.

O que acompanho é o registro do servidor deste site. O /mcp grava cada chamada com data, método, ferramenta e cliente, sem IP, e a chamada que vem do WebMCP chega marcada com a origem webmcp. As seis ferramentas da página não passam pelo servidor e não deixam rastro nele. Quando o registro mostrar chamadas de um agente real, este texto ganha uma atualização com o que foi chamado e de onde.