Frameworks and WebMCP Meta Issue

This is a design discussion rather than a bounded implementation task; start with the related proposals in issues #167 and #196, then review the canonical v3 lifecycle behavior described here. Identify which concern—stable-identity updates, scoped registries, unavailable state, or route persistence—has an agreed solution and can be split into a concrete sub-issue. Done means that one concern has a specific API or specification proposal, expected behavior, and follow-up issue with no unresolved design questions.

I’m establishing this as a meta-issue to discuss WebMCP and Framework considerations. In this issue, I’ll be documenting a few considerations, many already started with @domfarolino and team, but filing this here for both transparency and cataloging. I’ll also be referencing other issues, but from the perspective of how the framework landscape might interact.

Contributions are welcome from everyone. Please feel free to use this meta issue for sharing any ideas that could help further the goal. We can open sub-issues as appropriate.

1. Stale closures

probably the biggest issue right now, and perhaps not just for frameworks. Related to issue #167 – Proposal: Dynamic Tool Definitions, we’ll discuss the framework implications here.

A potential way to think about WebMCP and Frameworks as a rule: register as rarely as possible, but read the state as freshly as possible at execution time.

Currently we can capture whatever state values were in scope when a tool was registered. If you register once and the state later changes, the agent calls a tool that's reading a frozen snapshot. If instead you re-register on every state change to keep the closure fresh, you thrash the tool registry (unregister/register churn, possible name collisions, tools flickering in and out from the agent's view).

This is connected to the updateTool() concept proposed by @domfarolino in #167

We could create a reconciling primitive keyed on stable identity, so re-registering an existing tool updates it in place rather than erroring or duplicating:

// proposed: identity separate from display name, like React's `key`
document.modelContext.registerTool({
  key: "cart:add",        // stable identity for diffing
  name: "addToCart",
  inputSchema,
  execute,
}, { signal });
// calling again with the same key updates schema/handler, no flicker

Almost every framework has the concept of keys (or track). This has the added benefit of protecting a bit against namespace collisions.

Instead of checking if a tool name exists and throwing a duplication error or forcing a tear down. The browser looks at the key. If it sees a match, it performs an in place patch.

So, it updates the memory reference to the new callback function. Without ever removing the tool from the AI agents directory. By shifting to an upsert model based on a key, React can do what it is designed to do. It reruns on every state change, pushes the fresh exposure to the browser and the agent never experiences a disconnected socket.

Why this matters: it makes the fix for the stale-closure problem cheap. The spec can't make a JS closure read fresh React state- which isn’t a spec gap. But if "re-register on render with the latest closure" is a fast, idempotent, flicker-free upsert, then React can do what it does best (re-run on state change) and the tool just stays current. Right now that loop is expensive and risks the agent watching tools blink out and back in.

(Relatedly, the spec already took its single biggest React-friendly step. The canonical v3 surface aborts the controller on unmount. That pattern maps pretty perfectly onto useEffect cleanup and largely solves the leak/duplicate problem that used to require manual unregisterTool bookkeeping, so we’ve got the cleanup in a good place- just not the updating with state change part.)

2. Scoped, composable registries.

Once again, this is important for frameworks, but also more largely applicable- especially for times when agents need to coordinate across many different tools, stateful composition of experiences.

The global namespace makes composition difficult. Two <DatePicker/> instances both wanting to expose selectDate collide, and there's no good answer today beyond manually mangling names.

If registries could attach to container elements or context and have the browser compose them upward into the page-level set—conceptually element.modelContext rather than only document.modelContext. This mirrors how React and others compose a tree, lets a library namespace tools per subtree automatically, and dovetails with allowing agents that collaborate across parent frames and nested contexts. This is the kind of thing userland genuinely cannot build well, because deduplication and scoping need the browser's cooperation—which is exactly why it belongs in the spec rather than in a hook.

This could be solved many ways- we could have a concept of nesting beyond document, etc. Just capturing the problem first.

3. A pending/unavailable tool state

Related to #196.
It’s extremely common for applications to need to wait for a backend for some data for the user/interaction.

For tools whose backing data is still loading behind a Suspense boundary, allowing a tool to be registered as temporarily unavailable is a big improvement. Otherwise, we have "not registered yet" (agent can't see it) and "registered but errors when called" (agent gets a confusing failure). This will end up coming up in debugging issues/tool chaining as well.

If it matters, React/Vue/Solid/Qwik give you a boundary you wrap around suspending children (good for grouping many async things under one fallback and for streaming SSR), while Svelte/Marko/Angular's defer attach the loading state to a specific async value at the point of use.

4. Persistence across routes/views/pages

In a SPA with tools set up in imperative, this is less of an issue. But if all tools are destroyed upon route change, we're going to run into a lot of issues in SSR applications. This also applies broadly beyond Frameworks.