Module 1.2 — WebMCP + backend + MCP

Assign explicit responsibilities

What is it: WebMCP provides contextual capabilities; the backend maintains rules and authority; MCP exposes integrations to the host.

Why learn this: The separation prevents turning the page into a backend or duplicating integrations.

Before modeling

Write down the person's request, the current state, and the evidence that will prove completion.

Starting error

Starting with a function name or a button produces a tool without a clear human goal.

Anticipate before opening the code

What information changes the decision? What effect needs to appear in the interface? Answer before implementing.

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

Going deeper: evidence worth keeping

Record the input, previous state, decision made, result, and visible change to the page.

Also include a simulated failure and the observed behavior without WebMCP support.

Key Concepts

WebMCP UX

backend domain

MCP integration

agent host

Choose where a tool should live

What is it: Experience proximity, need for secrecy, reach, and lifecycle guide the decision.

Why learn this: Not every visible function should be WebMCP, and not every integration needs to appear on the page.

Question	Strong contract	Weak contract
When should you use it?	The description names the intent and context.	“Does things” or “manages.”
What does it receive?	Only the data needed.	Generic, unlimited object.
What does it return?	Verifiable state and next action.	Text without a protocol.
How does it fail?	Code, reason, and recovery.	Opaque exception.

Do

✓ Use specific verbs.
✓ Define the inputs.
✓ State the evidence.

Avoid

✗ Mix intents.
✗ Accept any object.
✗ Hide effects.

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

Going deeper: evidence worth keeping

Record the input, previous state, decision made, result, and visible change to the page.

Also include a simulated failure and the observed behavior without WebMCP support.

Key Concepts

placement

secret

reach

lifecycle

Create a single domain layer

What is it: A human click, WebMCP tool, and MCP server call the same application rule when they share a use case.

Why learn this: A single source of truth reduces discrepancies and contradictory audits.

Observe

Capture state, input, and context before taking action.

Decide

Validate preconditions and choose the allowed transition.

Run

Apply the shared rule and honor cancellations.

Prove

Update the interface and return a structured result.

Checkpoint

If step 2 fails, the tool doesn’t try to “make it work”: it returns an explicit recovery path.

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

Going deeper: evidence worth keeping

Record the input, previous state, decision made, result, and visible change to the page.

Also include a simulated failure and the observed behavior without WebMCP support.

Key Concepts

application service

ports

adapters

single rule

Propagate identity and traceability

What is it: Calls carry verified identity, limited delegation, and trace context across layers.

Why learn this: Without propagation, logs don’t explain who initiated the effect or where the decision changed.

REFERENCE CODE

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

Input

It is small, documented, and verifiable.

Execution

Reuses the application's actual rule.

Output

Lets you verify the effect and continue.

Read the code as a contract

Underline where input is validated, where the effect happens, where cancellation arrives, and where the UI is updated.

Going deeper: evidence worth keeping

Record the input, previous state, decision made, result, and visible change to the page.

Also include a simulated failure and the observed behavior without WebMCP support.

Key Concepts

actor

delegation

traceparent

correlation

Normalize contracts across boundaries

What is it: Schemas, errors, and envelopes are versioned without pretending WebMCP, HTTP, and MCP use identical transports.

Why learn this: The domain model can be shared while adapters preserve their own semantics.

Simulated failure

Run the scenario with missing state, invalid input, or unavailable capacity.

Expected recovery

The response explains what failed, what remains safe, and what action can continue.

Minimum test matrix

✓ reproducible happy path

✓ actionable invalid input

✓ cancellation ends the work

✓ fallback preserves the user journey

✓ interface reflects the state

✓ backend retains authorization

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

Going deeper: evidence worth keeping

Record the input, previous state, decision made, result, and visible change to the page.

Also include a simulated failure and the observed behavior without WebMCP support.

Key Concepts

canonical model

adapter

versioning

error mapping

Prove the vertical slice

What is it: The test follows the request, selection, execution, authorization, integration, UI, and final response.

Why learn this: The end-to-end proof finds failures that are invisible in isolated tests.

Synthesis exercise

1. Explain the problem without using the name of the technology.
2. Design the before and after states.
3. Implement the smallest working proof.
4. Trigger a failure and record the recovery.
5. Deliver code, evidence, and one known limitation.

Module challenge

Design and implement a vertical slice where WebMCP coordinates the UI, the backend authorizes, and MCP integrates with an external system.

Responsible Expert criterion

The implementation must work, explain its limitations, and preserve the human path when the experimental capability is unavailable.

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

Going deeper: evidence worth keeping

Record the input, previous state, decision made, result, and visible change to the page.

Also include a simulated failure and the observed behavior without WebMCP support.

Key Concepts

vertical slice

contract test

trace

visible effect

📦 Module delivery

Design and implement a vertical slice where WebMCP coordinates the UI, the backend authorizes, and MCP integrates with an external system.

Acceptance criteria

The implementation works with WebMCP support and preserves the manual path when the API is unavailable.

Evidence

Include code, the tested scenario, the observed result, and one known limitation.

← Back to the track Next module: 1.3 →

Technical sources

Draft and official WebMCP repository
Rendered specification
Official snapshot: 26/08/2026 · commit 41d12f0. The declarative API remains experimental; validate the draft before production.