WebMCP Integrator

A tool starts with a real user goal, not with every existing button or function in the code.

Mapping the start, decision, effect, and evidence prevents the integration from copying the interface without understanding its intent.

observable objective · initial state · expected effect · final evidence

Small tools fulfill a complete intent and do not compete for the same call.

When two descriptions seem to answer the same request, the LLM has to guess, and the correct selection rate drops.

no overlap · precise verb · clear boundary · own output

The input should request only the necessary data and represent closed alternatives with enums when possible.

Focused schemas reduce invented arguments, but actual validation is still required in execute and on the backend.

minimum fields · useful enum · concrete description · real validation

The agent may know the name spoken by the user before it knows the system's internal identifier.

Separating search, resolution, and action avoids requiring opaque IDs too early or accepting ambiguous names too late.

name discovers · ID identifies · explicit resolution · ambiguity handled

The catalog should track the route, selection, authentication, and current stage of the journey.

Fewer available tools mean less context and fewer impossible calls.

contextual catalog · dynamic registration · visible session · cleanup

Generic and overlapping names need to become a sequence that reveals intent and effect.

The implementation proves that the catalog guides the agent and also explains the flow to product, security, and QA.

inventory · refactoring · selection test · documentation

Each step states what has already happened, which actions are available, and which transition is valid.

Without a state model, the agent may confirm before starting or repeat an effect that has already completed.

explicit state · valid transition · precondition · effect

Recoverable errors indicate a next action; terminal errors end the attempt with a verifiable reason.

Classification prevents blind loops and lets the agent explain real alternatives to the user.

stable code · actionable message · next action · honest ending

The state used to make a decision can change before execution, especially for job openings, prices, and permissions.

Revalidating at the time of the effect prevents a tool from using an old snapshot as current authorization.

revalidation · state version · conflict · new reading

An idempotency key lets you repeat a request without duplicating a subscription, charge, or submission.

Agents, networks, and users can repeat calls; the operation needs to distinguish a retry from a new effect.

idempotency key · safe retry · previous result · single effect

AbortSignal and timeout end work that has lost relevance or exceeded the operational window.

True cancellation preserves resources and prevents the interface from showing success after the person has given up.

AbortSignal · timeout · visual cleanup · canceled result

The integration must prove the happy path, invalid order, retry, cancellation, and concurrent changes.

A failure matrix turns resilience into verifiable behavior, not architectural intent.

scenarios · evidence · reproduction · regression

Map forms, handlers, services, endpoints, and states before proposing tools.

The audit reveals where the rule already exists and where the interface contains logic that needs to be separated.

forms · JS functions · APIs · state

Not every feature deserves to be migrated first; weigh frequency, value, stability, and reversibility.

The right scope delivers learning early without starting with a critical or poorly understood action.

value · frequency · risk · stability

The same domain function should serve both human clicks and WebMCP execution.

Sharing the logic prevents divergence between the visual flow and the agent’s path.

common service · adapter UI · adapter tool · single rule

The tool translates arguments, calls the existing service, updates the UI, and returns a structured response.

Small wrappers are easier to review and don't recreate the application inside the WebMCP registry.

translation · existing service · synchronized UI · return

The human workflow remains functional when WebMCP is unavailable or disabled.

An experimental technology is added as an additional capability, with monitoring and rollback.

feature detection · fallback · rollout · rollback

The dossier connects inventory, catalog, risks, implementation, tests, and publication plan.

The migration becomes reviewable by product, development, security, and operations.

map · risk · functional proof · rollout

A framework-free implementation makes registration, dependencies, and cleanup explicit.

The reference reduces magic and helps diagnose problems hidden by hooks or dependency injection.

pure function · explicit registration · AbortController · baseline

The effect registers tools for the current state, and cleanup aborts the previous registrations.

Strict Mode, rerenders, and dependency changes must not duplicate names in the catalog.

useEffect · dependencies · cleanup · Strict Mode

A service receives dependencies, registers the tools, and exposes cleanup to the component or route.

Dependency injection keeps rules testable and separate from the visual lifecycle.

service · DI · OnDestroy · testability

document.modelContext only exists on the client and after the document is active.

Separating the client component, loading, and server API avoids accessing Document during SSR.

use client · hydration · SSR · API route

SPAs need to remove tools from the previous route and register only the capabilities of the new screen.

A stale catalog is stale UI: the agent sees an action that the person can no longer perform.

router · unmount · current catalog · transition

Different frameworks must fulfill the same observable contract for registration, execution, UI, and cleanup.

A shared matrix separates differences in ergonomics from actual differences in behavior.

same contract · same tests · proven cleanup · compatibility