feat(clerk-js): dispatch a clerk:webmcp event for each WebMCP tool call

Apps can listen on window and send agent activity to their own analytics. The event carries the tool name, result status and sign-in strategy, never the identifier or code.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: djgould

.changeset/experimental-webmcp-tools.md

@@ -3,4 +3,4 @@
 '@clerk/shared': minor
 ---
 
-Add an experimental `webmcp` option (`experimental: { webmcp: true }`). In browsers that support [WebMCP](https://webmachinelearning.github.io/webmcp/), Clerk registers tools that let browser agents check auth state, sign in, submit verification codes, switch organizations and sign out. The tools never take a password or return a token; password and passkey sign-in go through the browser's own prompts.
+Add an experimental `webmcp` option (`experimental: { webmcp: true }`). In browsers that support [WebMCP](https://webmachinelearning.github.io/webmcp/), Clerk registers tools that let browser agents check auth state, sign in, submit verification codes, switch organizations and sign out, without ever taking a password or returning a token. Each tool call dispatches a `clerk:webmcp` event on `window` with the tool name, result status and sign-in strategy, so you can track agent activity in your own analytics.

packages/clerk-js/src/core/modules/webmcp/__tests__/webmcp.test.ts

@@ -159,6 +159,25 @@ describe('registerWebMcpTools', () => {
     expect(setup.clerk.setActive).toHaveBeenCalledWith({ session: 'sess_1' });
   });
 
+  it('dispatches a clerk:webmcp event for each tool call', async () => {
+    const { signIn, update } = setup;
+    const factor = { strategy: 'email_code', emailAddressId: 'idn_1', safeIdentifier: 'j***@acme.com' };
+    signIn.create.mockImplementation(update({ status: 'needs_first_factor', supportedFirstFactors: [factor] }));
+    const events: unknown[] = [];
+    const listener = (event: Event) => events.push((event as CustomEvent).detail);
+    window.addEventListener('clerk:webmcp', listener);
+    await register();
+
+    await call('clerk_get_auth_state');
+    await call('clerk_sign_in', { method: 'email_code', identifier: 'jane@acme.com' });
+    window.removeEventListener('clerk:webmcp', listener);
+
+    expect(events).toEqual([
+      { tool: 'clerk_get_auth_state', status: 'signed_out' },
+      { tool: 'clerk_sign_in', status: 'needs_code', strategy: 'email_code' },
+    ]);
+  });
+
   it('asks for an authenticator app code when the account has MFA', async () => {
     const { signIn, update } = setup;
     signIn.status = 'needs_first_factor';

packages/clerk-js/src/core/modules/webmcp/index.ts

@@ -42,9 +42,19 @@ const toError = (error: unknown): ToolResult => {
   };
 };
 
+const getStatus = (result: ToolResult) =>
+  typeof result.status === 'string' ? result.status : result.signedIn ? 'signed_in' : 'signed_out';
+
 const defineTool = (tool: WebMcpTool): WebMcpTool => ({
   ...tool,
-  execute: input => tool.execute(input ?? {}).catch(toError),
+  execute: async input => {
+    const result = await tool.execute(input ?? {}).catch(toError);
+    const strategy = typeof input?.method === 'string' ? { strategy: input.method } : {};
+    window.dispatchEvent(
+      new CustomEvent('clerk:webmcp', { detail: { tool: tool.name, status: getStatus(result), ...strategy } }),
+    );
+    return result;
+  },
 });
 
 const getAppName = (clerk: Clerk) => clerk.__internal_environment?.displayConfig.applicationName || 'this app';