webmcp-rs
Browser-side WebMCP for Rust and WebAssembly: let the page hand tools to whatever agent is driving the browser.
Live demo: https://webmcp.oxidt.com — a todo list driven by five registered tools, with a console for calling them by hand.
WebMCP is the W3C proposal (Google + Microsoft, Web Machine Learning CG) that
lets a web page register tools on document.modelContext. An in-browser agent
discovers them and calls them instead of scraping the DOM. The tools run inside
the session the user is already logged into: no API key, no second copy of your
authorization rules, and the agent sees exactly what the user can see.
[]
= "0.2"
The package is webmcp-rs (the bare webmcp name on crates.io is a
placeholder); the library is webmcp, so code reads naturally:
use ;
let handle = new
.description
.register_typed?;
// `handle` keeps the tool alive; dropping it unregisters.
Why not just js_sys::eval
Five lines of eval will register a tool. The two things it will not do are the
two things that break in practice:
- Schema drift. The JSON Schema the agent plans against and the struct the
handler destructures are written twice and diverge on the first refactor.
register_typedderives the schema from the argument type (doc comments become field descriptions), so they are one declaration. - Ghost tools. A tool registered for a component that has since unmounted
still answers calls, acting on state the user is no longer looking at. This is
the failure mode that got
provideContext()removed from the spec.ToolHandleunregisters on drop; with thedioxusfeature,use_toolparks it in a component's hook state so unmounting is enough.
Dioxus
use *;
use ;
Enable it with features = ["dioxus"]. Handlers run on a browser callback,
outside the framework's runtime: reach for Rc<RefCell<_>> or a coroutine
channel for state, not a Signal.
Leptos
use *;
use ;
Enable it with features = ["leptos"]. The handle is parked in the component's
reactive owner, so cleaning that owner up unregisters the tool. Registering with
no owner in scope leaks the registration until the page unloads, so use_tool
warns when it finds none.
Both features export use_tool; with exactly one enabled it is also available
unqualified as webmcp::use_tool.
Handlers
register(|args: serde_json::Value| ...)— hand-writteninputSchema.register_typed(|args: T| ...)— schema derived fromT: JsonSchema(schemafeature, on by default). Bad arguments come back to the agent as an error result naming the field, not as a panic.register_async(...)— awaits the browser's verdict, so a rejected descriptor (a duplicate name, say) is a realErrinstead of a console warning.register_typed_async(...)— combines derived schemas and typed arguments with the awaited registration verdict.
Every tool needs a non-blank .description(...); say what the tool does and
when to use it. Names are 1–128 ASCII letters, digits, _, - or .. Missing
descriptions and invalid names return Error::Descriptor before reaching the
browser, including on native targets. Invalid JS arguments return an error result without invoking the handler;
only an omitted (undefined) argument defaults to an empty object.
new
.title
.description
.read_only // a pure query: no state or view changes
.untrusted_content // returns text other users wrote
Behaviour hints are opt-in and sent only when set. .consequential() marks
irreversible actions (payments, deletions) so the agent can confirm first;
.debugging() marks developer-only tools.
When the agent cancels a call, the handler's future is dropped, so its work
stops at the next .await; the agent gets an error result reading cancelled.
A handler returns Result<ToolResult, E> for any E: Display; an Err reaches
the agent as isError: true with the message, which is the protocol's soft
failure channel. ToolResult::json(&value) pretty-prints structured data into a
text block, which models read more reliably than compact JSON.
Targets
Off wasm — SSR, native, tests — registration returns Error::Unsupported
instead of failing to compile, so the same component code builds for both halves
of a fullstack app. Descriptor validation still runs there, so cargo test
catches a malformed schema without a browser.
Browser requirements
- Chrome 149+ in the origin trial,
or locally with
chrome://flags/#enable-webmcp-testingenabled. Edge ships it behind a flag. - The page must be origin-isolated, which is the default. Do not send
Origin-Agent-Cluster: ?0(it re-enablesdocument.domainand disables WebMCP). - The
toolsPermissions Policy defaults toself: top-level and same-origin frames may register, cross-origin iframes needallow="tools".
webmcp::is_supported() reports whether the current page has a model context,
for an "agent-ready" affordance. Registering on an unsupported page is already a
harmless Error::Unsupported, so there is no need to guard on it.
Spec drift
The browser API is not stable. This crate tracks the April 2026 draft:
| Status | |
|---|---|
document.modelContext.registerTool(tool, { signal }) |
what this crate calls |
navigator.modelContext |
deprecated alias, used as a fallback |
provideContext() / clearContext() |
removed March 2026, not implemented |
unregisterTool() |
removed April 2026, replaced by aborting the signal |
Declarative API (toolname on <form>) |
out of scope; plain HTML already covers it |
title, annotations, execution signal |
supported |
getTools() / executeTool(), toolactivated / toolcancel |
consumer side, out of scope |
The interface is reached reflectively rather than through extern bindings, so
a browser with an older or different surface degrades to Error::Unsupported
rather than throwing.
Features
schema(default) —register_typed/Tool::args::<T>()viaschemars.dioxus—use_tool, tying a registration to a component's lifetime.leptos— the same, tied to the component's reactive owner.
Site
site/ is the Dioxus web app behind the live demo: one client-rendered page,
excluded from the published crate, deployed to GitHub Pages by
.github/workflows/site.yml on every push to main.
site/src/demo.rs is the demo in full — five tools registered with use_tool,
and the read-snapshot / coroutine-channel pattern that keeps handlers off the
Dioxus runtime. Mutation calls await a reply after the state and read snapshot
are updated; add_todo returns the created item, including its ID. The page
shows that file verbatim.
The demo works in any browser because the page loads Google's
WebMCP polyfill (Apache-2.0)
before the wasm starts; it is vendored at site/assets/webmcp-polyfill.js with
its copyright header intact, and stands down when the browser has the native
API.
Testing
just test runs host tests and checks the docs. just test-browser runs the
crate's WASM tests with and without default features, plus the demo tests, in
headless Chrome using wasm-pack. The browser suite installs a controlled model
context to exercise registration, execution, errors, and cleanup without an
experimental browser flag. It also mounts Dioxus components and cleans up Leptos
owners to check tool lifetimes, and reads immediately following mutations. This validates the Rust/JS
integration; it does not certify a particular native WebMCP implementation.
In a real browser, inspect and call tools in DevTools (Application > WebMCP) or with Google's webmcp-extension.
License
MIT