WebMCP Next.js

Choose one workflow

Next.js teams should begin with a workflow that already works for people: product lookup, support search, quote preparation or appointment availability. A WebMCP tool should describe a narrow capability with a useful result, not expose every visual control. Write the goal, inputs, output and failure states before writing registration code. This makes the tool easier to explain to an agent and easier for a human to test.

Use the current browser surface

The current documented imperative surface is document.modelContext. Feature-detect it in the browser and register a tool with a stable name, description, inputSchema and execute function. Keep the ordinary Next.js UI available when the API is absent. Treat navigator.modelContext only as a legacy compatibility signal, and do not describe a static code reference as runtime support.

Design inputs as a contract

Use explicit JSON Schema properties, types, formats, descriptions, required fields and additionalProperties: false where appropriate. For Next.js, map agent input into the same validated application action used by a person. Never trust a string because it came from an agent, and do not use hidden component state or a client-only disabled button as authorization.

Separate preparation from commitment

Search and lookup are often read-only. Cart preparation or draft quote data may be reversible. Booking, checkout, order submission, account changes and identity workflows can create commitments or affect sensitive data. Mark the consequence, show the final values, require an explicit human confirmation and enforce authorization on the server. WebMCP should reduce friction without bypassing consent or security.

Test lifecycle and failure states

A real implementation must survive route changes, hydration, re-rendering, duplicate mounts, network errors, rejected validation and cancellation. Next.js integration code should clean up registrations where the API supports it and should not leave stale handlers after navigation. Test keyboard access, labels, loading, error and success states in the same page a person uses.

Move from guidance to verification

Use the WebMCP Generator for a starting schema, the Validator for static checks and the Simulator for task-to-tool mapping. A controlled browser test is still required before calling a tool Verified. For a production rollout, involve the implementation service when data, money or identity are involved.

Framework-specific delivery notes

In Next.js, server-render the explanation, metadata and ordinary form, then isolate registration in a Client Component. Do not reference document.modelContext during server rendering. Test hydration, streaming, route transitions and cache behavior, and keep authorization, prices and secrets in the server application rather than in a browser bundle.

A practical test case

Give the implementation one deterministic test: a user asks for a useful read-only result, the agent supplies valid and invalid input, the page shows a loading state, the server authorizes the request, and the human can continue without WebMCP. Then repeat with a consequential action and verify that the final commit is blocked until confirmation. Record expected output, error text and cleanup behavior for nextjs.

Connect the delivery path

Use Autopilot to prioritise the workflow, then the Generator, Validator and Simulator. The Implementation Service can review the production boundary.

Operational detail

Separate three concerns in the review: server-rendered explanation, client-side capability registration and server-side authorization. A page can be indexable and readable even when the browser feature is unavailable. Test a hard reload, hydration mismatch, back/forward navigation and a failed server response. The fallback should preserve the same task and validation path rather than showing a dead WebMCP-only control.