Expondo as Ações do Seu Site para Agentes de IA com WebMCP

O WebMCP inverte a direção do Model Context Protocol. Em vez de um agente se conectar a um servidor que você hospeda, sua página registra suas próprias ferramentas em JavaScript com document.modelContext.registerTool(), e um agente que já tem a página aberta chama essas ações declaradas diretamente, em vez de clicar pela sua interface e adivinhar quais são os campos do seu formulário.

Se você já conectou um servidor MCP a um agente de programação, o modelo do lado do servidor é familiar: um processo, um transporte, uma lista de ferramentas, um cliente que se conecta. O caso do navegador é o complicado. O tráfego do agente chega em uma página renderizada com uma sessão autenticada, e até agora o único caminho possível era o acionamento: ler o DOM, inferir o que os botões fazem, torcer para que a etapa de checkout não seja renderizada novamente no meio do clique.

Este artigo cobre os mecanismos que importam para quem é dono de uma aplicação real: como é um registro de ferramenta correto, o que as três dicas de anotação de fato mudam no comportamento do agente, onde as ferramentas de site rodam hoje e a consequência de segurança de uma ferramenta rodar dentro da sessão autenticada do usuário.

A Inversão: O Que Torna o WebMCP Diferente?

Um servidor MCP do lado do servidor é algo a que um agente se conecta, configurado uma vez e acessível independentemente de qualquer página aberta. O WebMCP funciona no sentido oposto. A documentação de site tools da OpenAI traça a linha em onde as ferramentas residem. O MCP aponta uma aplicação de IA para um servidor, local ou remoto, que fica fora da página e funciona com ou sem um navegador aberto. Um site com WebMCP entrega suas próprias capacidades como um conjunto pronto de ferramentas que um agente encontra ao chegar, e não há nada para o usuário instalar.

O benefício é precisão. A documentação do WebMCP do Chrome coloca a diferença em termos de quem decide o que um controle significa: com uma ferramenta, o site diz isso explicitamente, e não sobra nada para o agente deduzir. O acionamento lhe dá uma cadeia de etapas e um julgamento a cada uma delas. Um agente que chama search_orders({ status: "open" }) contra um schema que você escreveu não pode errar o clique em um dropdown de filtro, e não pode quebrar porque você renomeou uma classe CSS.

Como Registrar uma Ferramenta com document.modelContext.registerTool()?

O registro de ferramenta recebe um objeto com um name, uma description e um inputSchema; a referência da API imperativa do Chrome trata esses três como campos obrigatórios, com annotations e uma função execute carregando o comportamento. Faça feature detection antes de chamar, exatamente como o próprio exemplo da OpenAI faz, porque a API ainda não está presente na maioria dos navegadores.

async function registerAgentTools() {
  if (typeof document.modelContext?.registerTool !== "function") return;

  await document.modelContext.registerTool({
    name: "list_orders",
    description:
      "List the signed-in customer's orders, newest first, optionally filtered by fulfilment status. Returns order number, placed date, status and total.",
    inputSchema: {
      type: "object",
      properties: {
        status: {
          type: "string",
          enum: ["open", "shipped", "delivered", "cancelled"],
          description: "Fulfilment status to filter by. Omit for all orders.",
        },
        limit: {
          type: "integer",
          minimum: 1,
          maximum: 20,
          description: "Maximum orders to return. Defaults to 10.",
        },
      },
      required: [],
      additionalProperties: false,
    },
    annotations: { readOnlyHint: true },
    // Same function the orders table calls. The API still checks the session.
    execute: async ({ status, limit = 10 }) => fetchOrders({ status, limit }),
  });
}

A descrição é a única coisa que o modelo lê ao decidir se esta ferramenta se encaixa na solicitação, então ela tem tanto peso quanto o código por trás dela. Nomeie o formato de retorno, nomeie o filtro e diga o que a ferramenta não cobre.

Repare no que o execute faz aqui: ele delega. A ferramenta chama a mesma função de busca de dados que a UI chama, e o servidor por trás aplica a mesma autorização que já aplica. A orientação da OpenAI direciona os desenvolvedores à autenticação e autorização já existentes, em vez de um caminho paralelo, e a razão de engenharia é evidente: dois caminhos de código para a mesma capacidade vão divergir, e o que não tem uma UI na frente é justamente aquele cuja divergência ninguém percebe.

O Que as Três Dicas de Anotação Mudam?

Anotações são metadados que informam a um agente como tratar uma ferramenta antes de chamá-la. O Chrome documenta três, e a orientação de segurança de ferramentas do Chrome reformula cada uma em termos do risco que ela sinaliza.

Defina-as por ferramenta, deliberadamente. Uma ferramenta cancel_subscription sem consequentialHint é uma ferramenta que um agente pode disparar sem pausar, e uma ferramenta de busca de avaliações sem untrustedContentHint entrega ao modelo um bloco de texto escrito por desconhecidos sem nenhuma sinalização.

Onde o WebMCP Roda Hoje?

A página de site tools da OpenAI estabelece onde o ChatGPT vai honrar uma ferramenta registrada: no navegador integrado do aplicativo desktop do ChatGPT, mantido atualizado, onde o ChatGPT Work e o Codex podem encontrar e chamar o que a página oferecer. O modelo também importa, com GPT-5.6 Sol e GPT-5.6 Terra suportados e o WebMCP desativado no GPT-5.6 Luna. Workspaces Enterprise e Edu ficam de fora, e se o recurso aparece ou não ainda depende do rollout e do que a página aberta registra. Uma seta na barra de endereços lista as ferramentas que uma página fornece, e o recurso inteiro pode ser desativado em Browser permissions.

A implementação do Chrome ainda é um preview. O Chrome documenta o WebMCP atrás da flag chrome://flags/#enable-webmcp-testing para desenvolvimento local, definida como Enabled com um relaunch, ao lado de um origin trial que você pode ingressar a partir do Chrome 149. Não está ativado por padrão no canal estável, e as declarações de suporte de ambos os fornecedores mudam, então leia as páginas de origem antes de colocar algo em produção contando com elas.

O Que o Navegador do ChatGPT Não Suporta

A documentação da OpenAI é clara ao afirmar que o navegador integrado cobre apenas parte do WebMCP, e ela nomeia duas lacunas. Ferramentas definidas por meio de atributos de formulário HTML não se tornam site tools, e ferramentas registradas dentro de um iframe não são descobertas, incluindo iframes de mesma origem. A instrução prática é curta: registre de forma imperativa, no documento de nível superior, e não dependa de nada exótico.

Essa restrição de iframe é do ChatGPT, não do padrão. O Chrome coloca ambas as APIs atrás da Permissions Policy tools, que começa em self. Com esse padrão, o documento de nível superior e frames de mesma origem podem registrar ferramentas, e um iframe cross-origin não pode. Um widget incorporado em outra origem pode registrar ferramentas se o frame receber a policy tools, se a ferramenta passar exposedTo listando origens autorizadas, e se o chamador passar fromOrigins para getTools(). O Chrome também restringe o WebMCP a documentos com isolamento de origem, então uma página que usa document.domain não recebe API nenhuma.

Sua Ferramenta Roda Como o Usuário Autenticado

Uma ferramenta registrada é executada dentro da página ativa sob a sessão autenticada do usuário, o que significa que toda capacidade que você expõe é uma capacidade que um agente pode exercer com a autoridade desse usuário. A questão de escopo não é o que seria conveniente automatizar. É o que você aceitaria que fosse invocado sem um clique.

A orientação de segurança do Chrome é excepcionalmente direta sobre por que isso importa. Um modelo recebe instruções e dados como uma sequência contínua de tokens, sem divisão entre eles. Segurança não pode ser garantida dentro de algo probabilístico. Prompt injection já funcionou, de forma repetida, contra sistemas de agentes rodando os melhores modelos disponíveis, e o número desses ataques na web continua subindo. A OpenAI diz algo bem parecido sobre as próprias ferramentas: em sua documentação de site tools, tanto as definições de ferramenta de um site quanto os resultados que elas retornam contam como conteúdo não confiável.

Disso decorrem três controles concretos. A visibilidade de ferramentas começa fechada, já que outros sites e iframes cross-origin não conseguem ver suas ferramentas até você nomear suas origens em exposedTo; aplique às ferramentas somente leitura que revelam dados do usuário o mesmo cuidado que aplica às ferramentas de escrita. O Chrome também aponta um caminho de acesso que você não abriu: extensões podem consultar e executar suas ferramentas a partir de um content script, e uma que tenha host_permission para o seu site já pode, de qualquer forma, rodar seu próprio JavaScript na página. E mantenha os textos curtos. O Chrome recomenda 500 caracteres para a descrição de uma ferramenta, 150 por descrição de parâmetro, 30 para nomes de ferramentas e parâmetros, e 1,5 mil por saída de ferramenta, descrevendo todos os quatro como recomendações que podem mudar com o feedback do ecossistema e que podem depois ser formalizadas. O trabalho sobre gerenciamento de consentimento continua, incluindo um requestUserInteraction() em rascunho de especificação para perguntar algo ao usuário no meio da execução, que ainda não foi lançado.

WebMCP Não É uma Jogada de SEO

Registrar site tools muda o que um agente pode fazer depois que chega à sua página. Não faz nada para que ele chegue. A própria lista de limitações do Chrome aponta a descobribilidade de ferramentas como um problema em aberto: um cliente ou um navegador só descobre que um site tem ferramentas chamáveis ao ir até lá. Não há crawl, nem índice, nem feed de ferramentas registradas. Lida junto com esse mecanismo, a conclusão é direta, embora seja nossa leitura e não uma declaração do fornecedor: WebMCP é uma superfície de caminho de conversão, não uma alavanca de ranqueamento ou citação, e tratar a descrição de uma ferramenta como texto de meta description é não entender quem a lê.

Escolha uma ação que seus usuários já concluem no seu site, registre-a primeiro como somente leitura e coloque o trabalho de verdade na descrição e no schema. É aí que um agente entende ou não a sua aplicação, e é a parte que nenhum rollout de navegador vai resolver por você.

Perguntas Frequentes

Como faço para cancelar o registro de uma ferramenta WebMCP quando o usuário navega para outra página?

Não existe um método unregisterTool. Passe um AbortSignal no objeto de opções de document.modelContext.registerTool e então aborte esse controller quando a ferramenta não se aplicar mais, como no unmount de um componente ou em uma mudança de rota de SPA. As boas práticas do Chrome colocam isso em termos de estado da página: registre uma ferramenta enquanto ela for útil e cancele o registro assim que deixar de ser. Amarrar o abort às suas transições de página é a forma prática de fazer isso, e evita que uma ferramenta obsoleta permaneça ativa ou colida com um novo registro de mesmo nome. Os agentes observam a mudança por meio do evento toolchange em document.modelContext.

Qual é a diferença entre as APIs declarativa e imperativa do WebMCP?

A API declarativa transforma um formulário HTML existente em uma ferramenta: adicione os atributos toolname e tooldescription ao elemento form, mais toolparamdescription em campos individuais, e o navegador deriva uma representação estruturada a partir do formulário. Remover qualquer um desses atributos cancela o registro da ferramenta. A API imperativa, document.modelContext.registerTool, é adequada para ferramentas dinâmicas e lógica complexa. O navegador integrado do ChatGPT suporta apenas o caminho imperativo.

Existe suporte em React ou Angular para registrar ferramentas WebMCP?

Ambos existem e ambos são experimentais. O Chrome Labs mantém o hook useWebMCP no pacote use-webmcp-tool, que registra uma ferramenta no mount, cancela o registro no unmount, exige React 18 ou posterior e degrada para um no-op onde a API não estiver presente. O Angular expõe provideExperimentalWebMcpTools a partir do seu pacote core, vinculando o tempo de vida da ferramenta a um injector, com providers de rota ou de aplicação como posicionamento recomendado.

O navegador valida os argumentos que um agente passa contra o meu inputSchema?

Não presuma que sim. Trate a entrada que chega ao execute como não validada e verifique-a em código antes de agir sobre ela. A orientação do Chrome sobre WebMCP diz aos desenvolvedores para validar restrições e retornar erros descritivos para que o agente possa tentar novamente, e o Angular afirma claramente que não verifica os argumentos fornecidos pelo agente contra o JSON schema que você declarou. Verificações de autorização no lado do servidor continuam valendo, por cima disso.