WebMCP: O Protocolo que Torna Sites Legíveis para Agentes de IA

O que é WebMCP

WebMCP (Web Model Context Protocol) é um padrão web proposto que permite a desenvolvedores expor funcionalidades de aplicações web — funções JavaScript ou elementos HTML <form> — como “tools” estruturadas, projetadas para consumo direto por agentes de IA.

Traduzindo: você declara o que seu site sabe fazer, e o agente executa essas ações de forma programática. Sem “interpretar” a interface visual como um humano faria. Sem adivinhar onde fica o botão.

O protocolo está em Origin Trial no Chrome 149+, com a spec sendo desenvolvida pelo grupo webmachinelearning no W3C. Primeiro padrão web nativo para comunicação estruturada entre páginas e agentes de IA.

Nota: Este site (prompt.api.br) utiliza astro-webmcp para expor seu conteúdo via WebMCP. Se você está usando um agente compatível no Chrome, já pode interagir com este site de forma estruturada.

O problema que WebMCP resolve

Como agentes interagem com sites hoje

Sites são projetados para humanos. Toda a interface — botões, menus, formulários, animações — existe para comunicar visualmente o que é possível fazer. Quando um agente de IA precisa interagir com um site, ele enfrenta um problema estrutural: precisa interpretar a interface como se fosse uma pessoa.

Esse processo se chama actuation: o agente simula cliques, preenche campos de texto e navega entre páginas imitando mouse e teclado. Funciona? Às vezes. Mas é como pedir pra alguém operar um caixa eletrônico vendado — até rola, mas demora e quebra no primeiro redesign de tela.

Actuation é:

• Lento — renderiza a página, analisa o DOM, identifica elementos interativos
• Frágil — mudou uma classe CSS ou ID? Quebrou.
• Impreciso — o agente pode confundir botões visuais parecidos
• Caro — consome tokens do LLM para interpretar HTML complexo

O que WebMCP propõe

Em vez do agente ficar adivinhando como interagir com a interface, o site declara explicitamente suas capacidades:

Antes (actuation):
  Agente → analisa DOM → encontra botão → simula clique → torce para funcionar

Depois (WebMCP):
  Agente → consulta tools disponíveis → chama função estruturada → recebe resultado

A analogia mais honesta: actuation é pedir a alguém que navegue por um restaurante lendo cada cartaz na parede tentando descobrir o cardápio. WebMCP é entregar o cardápio na mão e dizer “escolhe”.

Os três pilares do WebMCP

Na prática, esses três pilares eliminam os problemas centrais de actuation:

• Discovery mata a ambiguidade — o agente sabe exatamente o que está disponível
• JSON Schemas mata a alucinação — inputs são validados contra um schema explícito
• State mata a perda de contexto — o agente sabe em que ponto da interação está

Características fundamentais

Efêmero (tab-bound)

Tools existem apenas enquanto a página está aberta na tab do browser. Fechou a tab? Sumiu tudo. Proposital: garante que o agente só interage com o que está visível e ativo para o usuário.

Visível

Toda execução acontece na interface visível. O usuário acompanha o que o agente está fazendo — preenchendo um formulário, navegando para outra página, ativando um filtro. Nada roda por baixo dos panos.

Origin-isolated

WebMCP só funciona em documentos isolados por origin. Um site malicioso não consegue registrar tools se passando por outro domínio. A boundary de segurança é a mesma same-origin policy que o browser já usa pra tudo.

Progressive enhancement

Sites funcionam normalmente sem suporte a WebMCP. As tools são registradas apenas quando o browser suporta e o agente está ativo. Pra quem visita com Firefox ou Safari? Zero impacto. O site carrega igual.

Como WebMCP funciona — Visão geral

O fluxo completo de uma interação WebMCP segue cinco etapas:

┌────────────────────────────────────────────────────────────────┐
│                    CICLO DE VIDA WebMCP                         │
│                                                                │
│  1. REGISTRATION                                               │
│     Página registra tools via document.modelContext             │
│     (Imperative API ou Declarative via <form>)                 │
│                                                                │
│  2. DISCOVERY                                                  │
│     Agente consulta browser: "que tools existem aqui?"         │
│     Recebe lista com nomes, descrições e schemas               │
│                                                                │
│  3. INVOCATION                                                 │
│     Agente decide chamar uma tool com argumentos tipados        │
│     Ex: search_content({ query: "astro", limit: 3 })           │
│                                                                │
│  4. EXECUTION                                                  │
│     Browser medeia a chamada → executa callback da tool         │
│     Tudo acontece no contexto da página, visível ao usuário    │
│                                                                │
│  5. RESPONSE                                                   │
│     Resultado estruturado retorna ao agente                    │
│     Agente pode usar para planejar próxima ação                │
│                                                                │
└────────────────────────────────────────────────────────────────┘

As duas APIs do WebMCP

WebMCP oferece duas formas complementares de expor tools:

API Imperativa (JavaScript)

Para lógica programática — buscas, navegação, operações complexas. Você registra tools via JavaScript com document.modelContext.registerTool().

document.modelContext.registerTool({
  name: 'search_products',
  description: 'Search products by keyword, category or price range',
  inputSchema: {
    type: 'object',
    properties: {
      query: { type: 'string', description: 'Search term' },
      category: { type: 'string', description: 'Product category' },
      maxPrice: { type: 'number', description: 'Maximum price in BRL' }
    },
    required: ['query']
  },
  execute: async ({ query, category, maxPrice }) => {
    const results = await searchProducts(query, category, maxPrice);
    return JSON.stringify(results.slice(0, 5));
  }
});

Detalhes completos em API Imperativa.

API Declarativa (HTML)

Para formulários existentes — adicione atributos ao HTML e o browser transforma em tools automaticamente. Zero JavaScript.

<form toolname="contact_support"
      tooldescription="Submit a support request to our team"
      toolautosubmit>
  <label for="subject">Subject</label>
  <input type="text" name="subject" required>
  
  <label for="message">Message</label>
  <textarea name="message" required
    toolparamdescription="Detailed description of the issue"></textarea>
  
  <button type="submit">Send</button>
</form>

Detalhes completos em API Declarativa.

Diagrama de arquitetura

┌─────────────────────────────────────────────────────────────────┐
│                         BROWSER (Chrome 149+)                    │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                    PÁGINA WEB                             │   │
│  │                                                           │   │
│  │  ┌─────────────────┐    ┌──────────────────────────┐    │   │
│  │  │  Imperative API  │    │     Declarative API       │    │   │
│  │  │                  │    │                           │    │   │
│  │  │  registerTool()  │    │  <form toolname="...">   │    │   │
│  │  │  getTools()      │    │    toolautosubmit         │    │   │
│  │  │  executeTool()   │    │    toolparamdescription   │    │   │
│  │  └────────┬─────────┘    └─────────────┬─────────────┘    │   │
│  │           │                             │                  │   │
│  │           └──────────────┬──────────────┘                  │   │
│  │                          │                                 │   │
│  │                          ▼                                 │   │
│  │           ┌──────────────────────────┐                    │   │
│  │           │  document.modelContext    │                    │   │
│  │           │  (Tool Registry)          │                    │   │
│  │           └──────────────┬───────────┘                    │   │
│  └──────────────────────────┼────────────────────────────────┘   │
│                             │                                    │
│                             ▼                                    │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              BROWSER INTERNALS                             │   │
│  │                                                           │   │
│  │  • Origin isolation check                                 │   │
│  │  • Permissions Policy enforcement                         │   │
│  │  • Cross-origin mediation                                 │   │
│  │  • Tool serialization (JSON)                              │   │
│  └──────────────────────────┬────────────────────────────────┘   │
│                             │                                    │
└─────────────────────────────┼────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                        AGENTE DE IA                               │
│                                                                  │
│  1. Descobre tools disponíveis (schemas, descrições)             │
│  2. Decide qual tool chamar baseado no objetivo do usuário       │
│  3. Envia argumentos tipados                                     │
│  4. Recebe resultado estruturado                                 │
│  5. Planeja próxima ação (ou retorna resultado ao usuário)       │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Como ativar WebMCP

Opção 1: Flag local (desenvolvimento)

Para testar localmente sem origin trial:

1. Abra chrome://flags/#enable-webmcp-testing no Chrome 149+
2. Mude para Enabled
3. Clique em Relaunch

Pronto — as APIs document.modelContext ficam disponíveis em todas as páginas locais.

Opção 2: Origin Trial (produção)

Para habilitar em produção para seus visitantes:

1. Acesse o registro do Origin Trial
2. Registre seu domínio
3. Adicione o token no <meta> de suas páginas:

<meta http-equiv="origin-trial" content="SEU_TOKEN_AQUI">

Opção 3: Chrome Early Preview Program

Para acesso antecipado a novas features:

• Inscreva-se em goo.gle/chrome-ai-dev-preview-join

Verificando se está ativo

// Feature detection compatível com Chrome 149 e 150+
const mc = document.modelContext ?? navigator.modelContext;

if (mc?.registerTool) {
  console.log('WebMCP disponível!');
} else {
  console.log('WebMCP não suportado neste browser');
}

Atenção: No Chrome 150+, a interface migrou de navigator.modelContext para document.modelContext. O pattern de feature detection acima funciona com ambas as versões. Detalhes em API Imperativa.

Permissions Policy

WebMCP é controlado pela Permissions Policy tools:

• Default: self — habilitado para o documento principal e iframes same-origin
• Cross-origin iframes: Precisam de permissão explícita

<!-- Permitir WebMCP em iframe cross-origin -->
<iframe src="https://widget.example.com" allow="tools"></iframe>

Para desabilitar completamente:

Permissions-Policy: tools=()

Quando usar WebMCP

WebMCP não substitui MCP — eles são complementares. Veja o comparativo detalhado.

Exemplo prático mínimo

O menor exemplo funcional possível — uma tool que retorna o título da página atual:

<!DOCTYPE html>
<html>
<head>
  <title>Minha Página com WebMCP</title>
</head>
<body>
  <h1>Olá, agente!</h1>
  
  <script>
    const mc = document.modelContext ?? navigator.modelContext;
    
    if (mc?.registerTool) {
      mc.registerTool({
        name: 'get_page_title',
        description: 'Returns the current page title',
        inputSchema: { type: 'object', properties: {} },
        execute: async () => document.title,
        annotations: { readOnlyHint: true }
      });
    }
  </script>
</body>
</html>

15 linhas. Com isso, um agente de IA já consulta o título da sua página de forma estruturada — sem parsear DOM, sem xpath, sem regex.

Ferramentas para desenvolvimento

Estado atual da spec (junho 2026)

• Status: Origin Trial ativo no Chrome 149+
• Spec: W3C Incubation (webmachinelearning group)
• Autores: Microsoft + Google (Dominic Farolino como spec driver)
• Repositório: github.com/webmachinelearning/webmcp — 2.6K+ stars
• Breaking change Chrome 150: navigator.modelContext → document.modelContext
• Concorrência em PT-BR: Zero — este é o primeiro conteúdo abrangente em português

A spec ainda está em evolução. Existem 11 open questions na spec, incluindo suporte a I/O multimodal, streaming, Service Workers e gerenciamento de consentimento.

Limitações conhecidas

Casos de uso concretos

E-commerce

Um agente busca produtos, filtra por categoria, adiciona ao carrinho e inicia checkout — tudo via tools estruturadas, sem tentar clicar em thumbnail que mudou de posição no último redesign.

Sites de conteúdo

Este site (prompt.api.br) usa astro-webmcp para permitir que agentes busquem artigos, naveguem entre seções e obtenham metadata das páginas — sem scraping, sem parsing de HTML.

Aplicações SaaS

Dashboards complexos com menus aninhados, filtros e formulários multi-step expõem cada operação como uma tool. O agente executa “run diagnostics” diretamente. Sem navegar 5 níveis de menu pra chegar lá.

Suporte ao cliente

Formulários de suporte com dropdowns de categorização e campos contextuais funcionam nativamente via API Declarativa. O agente preenche corretamente porque conhece o schema dos campos — não precisa adivinhar qual opção do select corresponde a “problema de cobrança”.

Reservas e booking

Seleção de datas, horários, número de pessoas e preferências — tudo mapeado em um JSON Schema que o agente entende sem ambiguidade. Nada de “clicar no calendário e torcer pro modal abrir”.

O ecossistema atual

Frameworks com suporte

Demos oficiais do Google

Próximos passos

Com os fundamentos claros, o caminho natural:

1. API Imperativa — Registre tools via JavaScript
2. API Declarativa — Transforme formulários em tools
3. Segurança — Proteja suas tools contra ataques
4. WebMCP vs MCP — Entenda quando usar cada um
5. Best Practices — Construa tools eficazes
6. astro-webmcp — Integração prática com Astro

Quer implementar WebMCP no seu site Astro agora mesmo? Pula direto pra astro-webmcp.