Módulo 1.2 — WebMCP + backend + MCP

Asigna responsabilidades explícitas

¿Qué es? WebMCP ofrece capacidades contextuales; el backend conserva las reglas y la autoridad; MCP expone integraciones al host.

Por qué aprender: La separación evita convertir la página en un backend o duplicar integraciones.

Antes de modelar

Escribe la solicitud de la persona, el estado actual y la evidencia que demostrará la finalización.

Error de partida

Empezar por el nombre de una función o por un botón produce una tool sin un objetivo humano claro.

Anticípate antes de abrir el código

¿Qué información cambia la decisión? ¿Qué efecto debe aparecer en la interfaz? Responde antes de implementar.

pagina: contexto + UI + tool adapter
backend: auth + regra + transação
mcp: sistemas externos

Profundiza: evidencia que vale la pena guardar

Registra la entrada, el estado anterior, la decisión tomada, el resultado y el cambio visible en la página.

Incluye también una falla provocada y el comportamiento observado sin soporte de WebMCP.

Conceptos clave

WebMCP UX

backend domain

MCP integration

agent host

Elige dónde debe vivir una tool

¿Qué es? La proximidad a la experiencia, la necesidad de secretos, el alcance y el ciclo de vida orientan la decisión.

Por qué aprender: No toda función visible debe ser WebMCP ni toda integración necesita aparecer en la página.

Pregunta	Contrato sólido	Contrato débil
¿Cuándo usarlo?	La descripción especifica la intención y el contexto.	“Hace cosas” o “gestiona”.
¿Qué recibe?	Solo los datos necesarios.	Objeto genérico e ilimitado.
¿Qué devuelve?	Estado y siguiente acción verificables.	Texto sin protocolo.
¿Cómo falla?	Código, motivo y recuperación.	Excepción opaca.

Haz

✓ Usa verbos específicos.
✓ Delimita las entradas.
✓ Declara la evidencia.

Evita

✗ Mezclar intenciones.
✗ Aceptar cualquier objeto.
✗ Ocultar efectos.

if (needsPageState) return "WebMCP";
if (needsExternalSystem) return "MCP";
return "backend API";

Profundiza: evidencia que vale la pena guardar

Registra la entrada, el estado anterior, la decisión tomada, el resultado y el cambio visible en la página.

Incluye también una falla provocada y el comportamiento observado sin soporte de WebMCP.

Conceptos clave

placement

secreto

reach

lifecycle

Crea una única capa de dominio

¿Qué es? El clic humano, la tool WebMCP y el servidor MCP invocan la misma regla de aplicación cuando comparten un caso de uso.

Por qué aprender: Una única fuente de verdad reduce las discrepancias y las auditorías contradictorias.

Observa

Captura el estado, la entrada y el contexto antes de la acción.

Decide

Valida las precondiciones y elige la transición permitida.

Ejecuta

Aplica la regla compartida y respeta la cancelación.

Demuestra

Actualiza la interfaz y devuelve un resultado estructurado.

Punto de control

Si la etapa 2 falla, la tool no intenta “arreglárselas”: devuelve una recuperación explícita.

startEnrollment(input, actor)
  -> policy.authorize(actor)
  -> repository.save(input)

Profundiza: evidencia que vale la pena guardar

Registra la entrada, el estado anterior, la decisión tomada, el resultado y el cambio visible en la página.

Incluye también una falla provocada y el comportamiento observado sin soporte de WebMCP.

Conceptos clave

application service

ports

adapters

regla única

Propaga la identidad y la trazabilidad

¿Qué es? Las llamadas llevan identidad verificada, delegación limitada y trace context entre las capas.

Por qué aprender: Sin propagación, los logs no explican quién inició el efecto ni dónde cambió la decisión.

CÓDIGO DE REFERENCIA

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

Entrada

Es pequeña, está descrita y se puede validar.

Ejecución

Reutiliza la regla real de la aplicación.

Salida

Permite verificar el efecto y continuar.

Lee el código como un contrato

Subraya dónde se valida la entrada, dónde ocurre el efecto, dónde llega la cancelación y dónde se actualiza la UI.

Profundiza: evidencia que vale la pena guardar

Registra la entrada, el estado anterior, la decisión tomada, el resultado y el cambio visible en la página.

Incluye también una falla provocada y el comportamiento observado sin soporte de WebMCP.

Conceptos clave

actor

delegation

traceparent

correlation

Normaliza los contratos entre fronteras

¿Qué es? Los schemas, errores y sobres se versionan sin fingir que WebMCP, HTTP y MCP usan transportes idénticos.

Por qué aprender: El modelo de dominio puede ser común mientras los adapters conservan sus propias semánticas.

Falla provocada

Ejecuta el escenario con estado ausente, entrada no válida o capacidad no disponible.

Recuperación esperada

La respuesta informa qué falló, qué sigue siendo seguro y qué acción puede continuar.

Matriz mínima de pruebas

✓ recorrido feliz reproducible

✓ entrada inválida que permite actuar

✓ la cancelación termina el trabajo

✓ el fallback preserva el recorrido

✓ la interfaz refleja el estado

✓ el backend mantiene la autorización

DomainError.NOT_FOUND
 -> HTTP 404
 -> WebMCP { ok:false, code:"NOT_FOUND" }
 -> MCP isError result

Profundiza: evidencia que vale la pena guardar

Registra la entrada, el estado anterior, la decisión tomada, el resultado y el cambio visible en la página.

Incluye también una falla provocada y el comportamiento observado sin soporte de WebMCP.

Conceptos clave

canonical model

adapter

control de versiones

error mapping

Demuestra el corte vertical

¿Qué es? La prueba sigue el pedido, la elección, la ejecución, la autorización, la integración, la UI y la respuesta final.

Por qué aprender: La prueba de extremo a extremo detecta fallas invisibles en pruebas aisladas.

Ejercicio de síntesis

1. Explica el problema sin usar el nombre de la tecnología.
2. Diseña el estado anterior y posterior.
3. Implementa la prueba funcional más pequeña.
4. Provoca una falla y registra la recuperación.
5. Entrega código, evidencia y una limitación conocida.

Desafío del módulo

Diseña e implementa una porción vertical en la que WebMCP coordina la UI, el backend autoriza y MCP integra un sistema externo.

Criterio de experto responsable

La entrega debe funcionar, explicar sus límites y preservar la ruta humana cuando la capacidad experimental no exista.

trace: user_turn -> webmcp_tool -> backend_policy -> mcp_call -> ui_update -> answer

Profundiza: evidencia que vale la pena guardar

Registra la entrada, el estado anterior, la decisión tomada, el resultado y el cambio visible en la página.

Incluye también una falla provocada y el comportamiento observado sin soporte de WebMCP.

Conceptos clave

slice vertical

contract test

traza

efecto visible

📦 Entrega del módulo

Diseña e implementa una porción vertical en la que WebMCP coordina la UI, el backend autoriza y MCP integra un sistema externo.

Criterio de aceptación

La entrega funciona con soporte para WebMCP y mantiene la ruta manual cuando la API no existe.

Evidencia

Incluye el código, el escenario probado, el resultado observado y una limitación conocida.

← Volver a la ruta Siguiente módulo: 1.3 →

Fuentes técnicas

Borrador y repositorio oficial de WebMCP
Especificación renderizada
Snapshot oficial: 26/08/2026 · commit 41d12f0. La API declarativa sigue siendo experimental; valida el draft antes de producción.