feat(experimental): Add WebMCP Adapter

[Muhammad-Bin-Ali]

Add experimental WebMCP adapter

Bridges tools registered on a Cloudflare McpAgent to Chrome's native navigator.modelContext API so browser-native agents can discover and call them — no extra infrastructure needed. Designed to compose with page-local tools that you register yourself, so the browser AI sees one unified toolbox spanning both execution environments.

import { registerWebMcp } from "agents/experimental/webmcp";

// 1. Register page-local tools — DOM, local state, Web APIs
navigator.modelContext?.registerTool({
  name: "page.scroll_to_top",
  description: "Scroll the demo page back to the top",
  execute: async () => { window.scrollTo({ top: 0 }); return "ok"; }
});

// 2. Bridge remote tools — durable storage, server-side auth, third-party APIs
const handle = await registerWebMcp({
  url: "/mcp",
  prefix: "remote.",
  getHeaders: async () => ({ Authorization: `Bearer ${await getToken()}` })
});

// Cleanup
await handle.dispose();

What's included

• agents/experimental/webmcp — new public export. Uses the official @modelcontextprotocol/sdk Client + StreamableHTTPClientTransport (gets SSE parsing, reconnection, session handling, pagination for free) and registers each discovered tool with navigator.modelContext.registerTool().
• examples/webmcp/ — demo app showing the in-page + remote composition pattern with an invoke UI for in-page tools and connect/disconnect/refresh controls.
• experimental/webmcp.md — design doc covering the pattern, full API reference, error model, concurrency semantics, lifecycle, edge cases, and open questions.
• 36 tests running in Chromium via Playwright — tool discovery, registration, prefix namespacing, async dispose, idempotency, post-dispose execute rejection, concurrent refresh() coalescing, watch mode (SSE re-sync), pagination, custom logger / quiet mode, init-failure-no-onError contract, plus regressions for HTTP errors, image content, and 405-on-GET.

API surface

interface WebMcpOptions {
  url: string;
  headers?: Record<string, string>;
  getHeaders?: () => Promise<Record<string, string>> | Record<string, string>;
  watch?: boolean;        // default true
  prefix?: string;        // namespace bridged tool names
  timeoutMs?: number;     // per-request timeout
  logger?: WebMcpLogger;  // default: console with [webmcp-adapter] prefix
  quiet?: boolean;
  onSync?: (tools: McpTool[]) => void;
  onError?: (error: Error) => void; // background sync errors only
}

interface WebMcpHandle {
  readonly tools: ReadonlyArray<string>; // current names (with prefix)
  readonly disposed: boolean;
  refresh(): Promise<void>;              // coalesces with in-flight syncs
  dispose(): Promise<void>;              // idempotent
}

Design decisions

• MCP SDK over hand-rolled HTTP. The transport, session handling, reconnection backoff, and pagination all come from @modelcontextprotocol/sdk. The adapter is just glue.
• Coherent error model. Init failures reject the promise; watch-mode re-sync failures call onError; per-tool execute failures reject so the browser host surfaces them. No double-fire, no surprise channels — documented in JSDoc.
• syncTools is serialized. refresh() and watch-mode notifications share an in-flight promise, so the unregister/list/register sequence can't interleave with itself.
• dispose() is async and idempotent. Aborts in-flight listTools/callTool via an internal AbortController, awaits the in-flight sync, then closes the transport.
• prefix for safe composition. Bridged tools register as ${prefix}${name} in navigator.modelContext but the original name is still used on the wire — the server doesn't need to know. Lets you mix in-page and remote tools (and bridge multiple servers) without name collisions.
• No-op on missing navigator.modelContext. Non-Chrome browsers (and Chrome without the experimental flags) get an empty handle, no fetch is made, onSync([]) still fires for symmetry. No need to feature-detect at the call site.

Stability

Shipped under experimental/ and the changeset is a patch. Both this adapter and Chrome's navigator.modelContext are early-preview; expect API breakage between releases.

Closes #1216

---

[changeset-bot]

🦋 Changeset detected

Latest commit: 303c5b8

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
agents	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[Muhammad-Bin-Ali]

/bonk review this PR

[ask-bonk]

Review: feat(experimental): Add WebMCP Adapter

Overall this is a well-structured addition. The adapter design is clean, the test coverage is solid, the example follows repo conventions, and the experimental warning is appropriately prominent. Below are the issues I found, organized by severity.

---

Issues to address

1. onChanged callback signature mismatch (bug)

In webmcp.ts:118-121, the listChanged.tools.onChanged callback is typed as () => void:

onChanged: () => {
  this._onToolsChanged?.();
}

But ListChangedCallback<Tool> from @modelcontextprotocol/sdk expects (error: Error | null, items: Tool[] | null) => void. This works at runtime (JS ignores extra args), but:

• It silently swallows errors the SDK passes to the callback
• It discards the items array, forcing a redundant listTools() round-trip on every change notification

Suggested fix:

onChanged: (error: Error | null, _items: Tool[] | null) => {
  if (error) {
    console.warn("[webmcp-adapter] listChanged error:", error);
    return;
  }
  this._onToolsChanged?.();
}

You could also use the items parameter to skip the extra listTools() call when the SDK already provides the updated list.

2. Missing dependencies in examples/webmcp/package.json (consistency)

server.ts imports @modelcontextprotocol/sdk and zod, but neither is declared in the example's package.json. Every other MCP example in the repo (mcp, mcp-worker, mcp-elicitation, x402-mcp, etc.) explicitly declares both. This works today due to hoisting but is fragile and inconsistent.

Add to examples/webmcp/package.json:

"@modelcontextprotocol/sdk": "1.28.0",
"zod": "^4.3.6"

3. tools getter returns the internal mutable array by reference (footgun)

At webmcp.ts:358-360:

get tools() {
  return registeredTools as readonly string[];
}

The as readonly string[] cast doesn't prevent mutation — callers can still do (handle.tools as string[]).push("evil"). The no-op handle at line 263 correctly returns [] as readonly string[] (a fresh empty array each time), creating an inconsistency: one code path is safe, the other leaks internals.

Fix with return [...registeredTools] or return Object.freeze([...registeredTools]).

4. Test key stability issue in client.tsx

At client.tsx:392, log entries use key={log.timestamp}. If two logs arrive in the same millisecond (entirely possible in the onSync + onError paths), React will see duplicate keys. Use a counter or crypto.randomUUID() instead.

---

Minor / nit-level observations

5. _client field used as InstanceType<typeof Client> but typed implicitly — The McpHttpClient class stores _client and _transport as private fields with inferred types. Since this is a browser-only module that gets bundled, this is fine, but adding explicit type annotations would improve readability for contributors.

6. Image content handling is lossy — In webmcp.ts:309, image data is prefixed with data:image;base64, (no specific MIME type) even though mimeType is available on the content item. The mimeType field from the MCP response is discarded. This means all images are treated identically regardless of format. Consider data:${c.mimeType ?? 'image/png'};base64,${c.data}.

7. eslint-disable comment in client.tsx:165 — The repo uses oxlint, not eslint. The // eslint-disable-next-line react-hooks/exhaustive-deps comment is dead. Replace with the oxlint equivalent or just add initWebMcp to the dependency array (it's already wrapped in useCallback with stable deps).

8. PR title says "28 tests" — I count 20 it() blocks in the test file, not 28. Minor but worth correcting in the PR description.

---

What looks good

• Clean separation between McpHttpClient (transport) and registerWebMcp (registration logic)
• Proper pagination support in listTools() with cursor handling
• Graceful no-op when navigator.modelContext is unavailable
• Good test coverage: no-op path, headers, dynamic headers, merge precedence, tool execution, watch mode, error handling, edge cases
• Example follows all repo conventions (Kumo UI, dark mode toggle, connection indicator, explainer card, PoweredByCloudflare footer, correct wrangler.jsonc/vite.config.ts/tsconfig.json structure)
• Changeset, build entry, package.json export, and AGENTS.md documentation all properly updated

[ask-bonk]

Review posted on PR #1222. Here's a summary of the findings:

4 actionable issues:

1. onChanged callback signature mismatch — The listChanged.tools.onChanged handler ignores the error and items parameters from the SDK, silently swallowing errors and forcing redundant listTools() calls.
2. Missing dependencies in example — examples/webmcp/package.json is missing @modelcontextprotocol/sdk and zod, which every other MCP example declares explicitly.
3. tools getter leaks internal array — The as readonly string[] cast doesn't prevent runtime mutation; callers get a reference to the actual internal array.
4. Duplicate React keys — Log entries use timestamp as key, which will collide when two logs arrive in the same millisecond.

4 minor observations on image MIME handling, dead eslint-disable comment, implicit typing on private fields, and incorrect test count in the PR description.

github run

[pkg-pr-new]

Open in StackBlitz

agents

npm i https://pkg.pr.new/agents@1222

@cloudflare/ai-chat

npm i https://pkg.pr.new/@cloudflare/ai-chat@1222

@cloudflare/codemode

npm i https://pkg.pr.new/@cloudflare/codemode@1222

hono-agents

npm i https://pkg.pr.new/hono-agents@1222

@cloudflare/shell

npm i https://pkg.pr.new/@cloudflare/shell@1222

@cloudflare/think

npm i https://pkg.pr.new/@cloudflare/think@1222

@cloudflare/voice

npm i https://pkg.pr.new/@cloudflare/voice@1222

@cloudflare/worker-bundler

npm i https://pkg.pr.new/@cloudflare/worker-bundler@1222

commit: 303c5b8