MÓDULO 1.2

🏛️ WebMCP + backend + MCP

Projete uma arquitetura híbrida que separa experiência da página, regras de domínio e integrações externas.

6

Tópicos

3h

Carga

Expert

Nível

Arquitetura

Tipo

0 de 60%
1

Atribua responsabilidades explícitas

O que é: WebMCP oferece capacidades contextuais; backend guarda regras e autoridade; MCP expõe integrações ao host.

Por que aprender: A separação evita transformar a página em backend ou duplicar integrações.

Página + WebMCP estado de partida Backend de domínio decisão observável Servidor MCP resultado verificável

Antes de modelar

Escreva o pedido da pessoa, o estado atual e a evidência que provará conclusão.

Erro de partida

Começar pelo nome de uma função ou por um botão produz uma tool sem objetivo humano claro.

Preveja antes de abrir o código

Qual informação muda a decisão? Qual efeito precisa aparecer na interface? Responda antes de implementar.

pagina: contexto + UI + tool adapter
backend: auth + regra + transação
mcp: sistemas externos
Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

WebMCP UX

02

backend domain

03

MCP integration

04

agent host

2

Escolha onde uma tool deve viver

O que é: Proximidade da experiência, necessidade de segredo, alcance e ciclo de vida orientam a decisão.

Por que aprender: Nem toda função visível deve ser WebMCP e nem toda integração precisa aparecer na página.

PerguntaContrato forteContrato fraco
Quando usar?A descrição nomeia intenção e contexto.“Faz coisas” ou “gerencia”.
O que recebe?Somente dados necessários.Objeto genérico e ilimitado.
O que devolve?Estado e próxima ação verificáveis.Texto sem protocolo.
Como falha?Código, motivo e recuperação.Exceção opaca.

Faça

  • ✓ Use verbos específicos.
  • ✓ Delimite entradas.
  • ✓ Declare a evidência.

Evite

  • ✗ Misturar intenções.
  • ✗ Aceitar qualquer objeto.
  • ✗ Esconder efeitos.
if (needsPageState) return "WebMCP";
if (needsExternalSystem) return "MCP";
return "backend API";
Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

placement

02

secret

03

reach

04

lifecycle

3

Crie uma camada de domínio única

O que é: Clique humano, tool WebMCP e servidor MCP chamam a mesma regra de aplicação quando compartilham um caso de uso.

Por que aprender: Uma fonte de verdade reduz divergência e auditorias contraditórias.

1

Observe

Capture estado, entrada e contexto antes da ação.

2

Decida

Valide pré-condições e escolha a transição permitida.

3

Execute

Aplique a regra compartilhada e respeite cancelamento.

4

Prove

Atualize a interface e devolva resultado estruturado.

Ponto de controle

Se a etapa 2 reprovar, a tool não tenta “dar um jeito”: ela devolve uma recuperação explícita.

startEnrollment(input, actor)
  -> policy.authorize(actor)
  -> repository.save(input)
Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

application service

02

ports

03

adapters

04

single rule

4

Propague identidade e rastreio

O que é: Chamadas carregam identidade verificada, delegação limitada e trace context entre as camadas.

Por que aprender: Sem propagação, logs não explicam quem iniciou o efeito nem onde a decisão mudou.

CÓDIGO DE REFERÊNCIA

headers: { traceparent, "X-Actor-Id": actor.id, "X-Delegation-Id": grant.id }
Entrada

É pequena, descrita e validável.

Execução

Reutiliza a regra real da aplicação.

Saída

Permite verificar efeito e continuar.

Leia o código como contrato

Sublinhe onde a entrada é validada, onde o efeito acontece, onde o cancelamento chega e onde a UI é atualizada.

Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

actor

02

delegation

03

traceparent

04

correlation

5

Normalize contratos entre fronteiras

O que é: Schemas, erros e envelopes são versionados sem fingir que WebMCP, HTTP e MCP têm transportes idênticos.

Por que aprender: O modelo de domínio pode ser comum enquanto adapters preservam semânticas próprias.

Falha provocada

Execute o cenário com estado ausente, entrada inválida ou capacidade indisponível.

Recuperação esperada

A resposta informa o que falhou, o que permanece seguro e qual ação pode continuar.

Matriz mínima de teste

✓ caminho feliz reproduzível

✓ entrada inválida acionável

✓ cancelamento encerra trabalho

✓ fallback preserva a jornada

✓ interface reflete o estado

✓ backend mantém autorização

DomainError.NOT_FOUND
 -> HTTP 404
 -> WebMCP { ok:false, code:"NOT_FOUND" }
 -> MCP isError result
Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

canonical model

02

adapter

03

versioning

04

error mapping

6

Prove a fatia vertical

O que é: O teste segue pedido, escolha, execução, autorização, integração, UI e resposta final.

Por que aprender: A prova ponta a ponta encontra falhas invisíveis em testes isolados.

Exercício de síntese

  1. 1. Explique o problema sem usar o nome da tecnologia.
  2. 2. Desenhe o estado anterior e posterior.
  3. 3. Implemente a menor prova funcional.
  4. 4. Provoque uma falha e registre a recuperação.
  5. 5. Entregue código, evidência e uma limitação conhecida.

Desafio do módulo

Desenhar e implementar uma fatia vertical em que WebMCP coordena UI, backend autoriza e MCP integra um sistema externo.

Critério de Expert responsável

A entrega precisa funcionar, explicar seus limites e preservar o caminho humano quando a capacidade experimental não existir.

trace: user_turn -> webmcp_tool -> backend_policy -> mcp_call -> ui_update -> answer
Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

vertical slice

02

contract test

03

trace

04

visible effect

📦 Entrega do módulo

Desenhar e implementar uma fatia vertical em que WebMCP coordena UI, backend autoriza e MCP integra um sistema externo.

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.

← Voltar para a trilhaPróximo módulo: 1.3 →

Fontes técnicas