Veja o problema antes da tecnologia
O que é: um mesmo objetivo pode ser alcançado por caminhos diferentes. Nosso exemplo será o site fictício INEMA Cursos, no qual alguém quer encontrar um curso de WebMCP para iniciante.
Por que aprender: se você começa pela sintaxe, WebMCP parece apenas mais uma API. Quando começa pela jornada, percebe a mudança: agentes de navegador e tecnologias assistivas deixam de depender apenas da interpretação visual e passam a conversar com uma capacidade declarada.
Pessoa
- 1. Lê os rótulos.
- 2. Preenche tema e nível.
- 3. Pressiona Buscar.
- 4. Interpreta a lista.
Agente visual
- 1. Observa pixels ou DOM.
- 2. Localiza os controles.
- 3. Clica, digita e seleciona.
- 4. Relê a tela para inferir sucesso.
Agente com WebMCP
- 1. Recebe a tool
buscar_cursos. - 2. Monta argumentos estruturados.
- 3. Invoca a capacidade.
- 4. Recebe um resultado verificável.
A frase que organiza a aula
O site deixa de ser apenas algo que o agente enxerga e passa a ser algo com que ele conversa estruturalmente.
buscar_cursos({
tema: "WebMCP",
nivel: "iniciante"
})Pare e preveja
Se o botão mudar de “Buscar” para “Encontrar”, qual caminho tende a quebrar primeiro? A automação que depende do controle visual. A intenção da tool continua buscar_cursos.
Conceitos-chave
objetivo humano
passos visuais
capacidade explícita
mesma interface
Separe cinco formas de conversar com um site
O que é: Web semântica, automação de navegador, API, MCP e WebMCP não são sinônimos. São interfaces diferentes para entender, operar, chamar ou descobrir capacidades.
Por que aprender: um Builder escolhe a interface pelo problema. Confundir esses termos produz tools que apenas repetem endpoints, agentes frágeis e falsas promessas de segurança.
| Tecnologia | O agente faz o quê? | No INEMA Cursos | Limite |
|---|---|---|---|
| Web semântica | Entende estrutura e significado. | Reconhece formulário e resultados. | Entender não executa uma intenção. |
| Automação do browser | Opera elementos e navegação. | Preenche inputs e clica. | Depende da apresentação. |
| API | Chama endpoints conhecidos. | GET /api/cursos | A LLM não descobre finalidade sozinha. |
| MCP | Descobre tools por servidor MCP. | Um servidor oferece busca a clientes. | Não nasce do documento atual. |
| WebMCP | Recebe tools da experiência web. | A página oferece buscar_cursos. | Depende do contexto e suporte. |
O que WebMCP acrescenta
- ✓ capacidades descobertas na página;
- ✓ descrição em linguagem natural;
- ✓ argumentos definidos por schema;
- ✓ execução ligada à experiência.
O que não substitui
- ✗ HTML semântico;
- ✗ API e regras do backend;
- ✗ autorização e validação;
- ✗ interface e controle humano.
Uma analogia precisa
A API é a cozinha. MCP é um balcão padronizado que apresenta serviços a agentes. WebMCP é o cardápio contextual da mesa atual, implementado pelo JavaScript da página e apoiado pela cozinha.
API aplicação → HTTP → backend
MCP LLM → host MCP → servidor MCP → sistemas
WebMCP LLM → agente do navegador → página → JS/UI/backendConceitos-chave
Acompanhe o momento mágico do WebMCP
O que é: a página registra, o navegador observa, o agente recebe metadados, escolhe e pede a execução. A tool não aparece magicamente para a LLM.
Por que aprender: enxergar o ciclo impede atribuir a decisão à página, colocar autorização na descrição ou esperar que a LLM chame uma API que nunca lhe foi apresentada.
A página oferece
Registra uma capacidade, mas não decide o objetivo do usuário.
O agente raciocina
Relaciona pedido, descrição e schema; depois produz a chamada.
A aplicação executa
Atualiza a UI e pode chamar um backend, que continua autorizando.
Detalhe do draft
getTools() atende agentes dentro da página. O agente do navegador observa as tools por mecanismo interno do user agent.
Conceitos-chave
Leia sua primeira tool linha por linha
O que é: uma tool imperativa é um objeto registrado em document.modelContext. Ela combina identidade, orientação, contrato de entrada e comportamento real.
Por que aprender: uma tool pode executar e ainda ser impossível de escolher, aceitar argumentos ruins ou devolver resultado inútil. O contrato é parte do produto.
await document.modelContext.registerTool({
name: "buscar_cursos",
title: "Buscar cursos",
description: "Busca cursos disponíveis por tema e nível.",
inputSchema: {
type: "object",
properties: {
tema: { type: "string", description: "Assunto desejado." },
nivel: {
type: "string",
enum: ["iniciante", "intermediario", "avancado"]
}
},
required: ["tema"],
additionalProperties: false
},
execute: async ({ tema, nivel }, { signal }) => {
const cursos = await buscarCursos({ tema, nivel, signal });
mostrarCursosNaTela(cursos);
return { ok: true, total: cursos.length, cursos };
}
});name
Identifica
É a chave estável usada na chamada.
description
Orienta a escolha
Explica quando e para que usar; não autoriza.
inputSchema
Delimita
Descreve tipos, enumerações e obrigatórios.
execute
Realiza
Recebe a entrada e um AbortSignal.
Trace a execução
pedido: "Procure WebMCP para iniciante"
escolha: buscar_cursos
entrada: { tema: "WebMCP", nivel: "iniciante" }
efeito: lista renderizada na página
saída: { ok: true, total: 2, cursos: [...] }Contrato útil
buscar_cursos tem objetivo e saída observável.
Contrato vago
gerenciar_site({ dados }) esconde intenções e efeitos.
Indo mais fundo: cancelamento
Passe o signal ao fetch. Quando o agente cancelar, interrompa trabalho e limpe o estado visual.
Conceitos-chave
Veja o catálogo mudar com o contexto
O que é: o catálogo pode ser efêmero. Tools aparecem ou desaparecem conforme documento, rota, componente e sessão.
Por que aprender: oferecer todas as ações o tempo todo aumenta contexto, confunde a escolha e permite chamadas sem sentido no estado atual.
CONTEXTO
Home pública
A pessoa ainda está descobrindo o catálogo.
TOOLS EXPOSTAS
- buscar_cursos
- abrir_categoria
Home
buscar_cursos · abrir_categoria
Curso
ver_detalhes · adicionar_carrinho
Carrinho
alterar_quantidade · iniciar_checkout
Conta
consultar_pedidos · alterar_endereco
const paginaProduto = new AbortController();
await document.modelContext.registerTool(
adicionarAoCarrinho,
{ signal: paginaProduto.signal }
);
// O componente saiu da tela.
paginaProduto.abort("Produto fechado");Catálogo pequeno é produto
A tool de alterar endereço só aparece depois do login, mas a autorização real ainda pertence ao backend.
Conceitos-chave
Construa, erre e explique sua arquitetura
O que é: o primeiro projeto é uma experiência completa: fluxo humano, tool, resultado visível, falha compreensível e limite arquitetural declarado.
Por que aprender: uma demo feliz não prova fallback, cancelamento, autorização nem recuperação. Builder responde pela interação inteira.
Tool não existe
O ambiente não oferece document.modelContext.
Recupere: mantenha o formulário funcional e informe o modo atual.
Entrada inválida
O nível não pertence ao enum.
Recupere: nomeie campo, problema e valores aceitos.
Backend nega
A sessão não permite a ação.
Recupere: preserve autorização e oriente login ou alternativa.
Usuário cancela
A busca perde utilidade.
Recupere: propague o signal e limpe o carregamento.
Exercício guiado
- 1. Escreva o pedido humano.
- 2. Liste os passos visuais.
- 3. Defina nome, descrição, entrada e saída.
- 4. Separe página e backend.
- 5. Provoque falha e cancelamento.
Desafio Builder
Adicione consultar_curso({ cursoId }) sem sobrepor buscar_cursos. Explique como o agente decide entre elas.
Projeto do módulo
Entregue o mini-site INEMA Cursos com busca manual e simulação identificada de chamada WebMCP. Se a API existir, registre a tool real por enhancement progressivo.
Critérios de aceite
- ✓ busca humana funciona;
- ✓ simulação está identificada;
- ✓ chamada e retorno aparecem;
- ✓ estado visual muda;
- ✓ erro ensina a corrigir;
- ✓ arquitetura separa responsabilidades.
Explique a arquitetura em quatro vozes
Define o objetivo, acompanha o estado e confirma efeitos relevantes.
Interpreta o pedido, escolhe a tool e monta os argumentos.
Registra a capacidade, executa JavaScript e mantém a interface sincronizada.
Valida dados, aplica autorização e preserva as regras de negócio.
Conceitos-chave
📦 Entrega do módulo
Produzir um documento de arquitetura comparando automação visual, API tradicional, MCP, WebMCP e MCP + WebMCP.
Critério de aceite
A entrega funciona com suporte WebMCP e mantém o caminho manual quando a API não existe.
Evidência
Inclua código, cenário testado, resultado observado e uma limitação conhecida.
Fontes técnicas
- Draft e repositório oficial WebMCP
- Especificação renderizada
- Snapshot oficial: 26/08/2026 · commit 41d12f0. A API declarativa permanece experimental; valide o draft antes de produção.