@W-23146707 Add telemetry for errors and URL button clicks in MCP app

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tableau/mcp-server",
   "description": "Helping agents see and understand data.",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/tableau/tableau-mcp.git"

src/server/oauth/scopes.ts

@@ -297,6 +297,11 @@ const toolScopeMap: Record<
     mcp: [],
     api: new Set<TableauApiScope>(),
   },
+  // MCP-app event telemetry relay: no Tableau REST API calls, no content scope required.
+  'record-event': {
+    mcp: [],
+    api: new Set<TableauApiScope>(),
+  },
   // Dispatches on `kind` to ts-events, site-content, job-performance (raw VDS) or stale-content
   // (server-side anti-join). Union of the scopes required by all four kinds.
   'query-admin-insights': {
@@ -362,6 +367,7 @@ async function getEnabledToolNames(): Promise<Set<WebToolName>> {
   // human-gesture confirm steps for their preview tools and only exist when the iframe can render.
   if (!mcpAppsEnabled) {
     enabledTools.delete('get-embed-token');
+    enabledTools.delete('record-event');
     enabledTools.delete('confirm-update-cloud-extract-refresh-task');
     enabledTools.delete('confirm-delete-content');
   }

src/server/passthroughAuthMiddleware.test.ts

@@ -21,6 +21,9 @@ const TOOLS_WITHOUT_API_SCOPES_WITH_PASSTHROUGH_GUARD: ReadonlyArray<WebToolName
   // Consent lifecycle tool: no Tableau REST API call. The tool callback explicitly returns an error
   // for non-Bearer auth types, so passthrough callers are rejected.
   'reset-consent',
+  // MCP app event telemetry: no Tableau REST API call. App-only tool that records telemetry
+  // regardless of auth type. Safe with passthrough auth as it only sends telemetry events.
+  'record-event',
 ];
 
 describe('passthroughAuthMiddleware', () => {

src/telemetry/productTelemetry/telemetryForwarder.ts

@@ -7,7 +7,7 @@ type PropertiesType = { [key: string]: ValidPropertyValueType };
 const DEFAULT_HOST_NAME = 'External';
 const SERVICE_NAME = 'tableau-mcp';
 
-export type TelemetryEventType = 'tool_call';
+export type TelemetryEventType = 'tool_call' | 'tableau_mcp_event';
 
 export type ProductTelemetryBase = {
   endpoint: string;

src/tools/web/recordEvent/recordEvent.test.ts

@@ -0,0 +1,83 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { WebMcpServer } from '../../../server.web.js';
+import { Provider } from '../../../utils/provider.js';
+import { getMockRequestHandlerExtra } from '../toolContext.mock.js';
+import { getRecordEventTool } from './recordEvent.js';
+
+// Mock getProductTelemetry so we can assert on the forwarder's send(). Note that
+// WebTool.logAndExecute also emits an automatic 'tool_call' event through the same
+// forwarder, so the spy is called for both 'tool_call' and 'tableau_mcp_event'.
+vi.mock('../../../telemetry/productTelemetry/telemetryForwarder.js', async (importOriginal) => {
+  const actual =
+    await importOriginal<
+      typeof import('../../../telemetry/productTelemetry/telemetryForwarder.js')
+    >();
+  return { ...actual, getProductTelemetry: vi.fn() };
+});
+
+import { getProductTelemetry } from '../../../telemetry/productTelemetry/telemetryForwarder.js';
+
+type Extra = ReturnType<typeof getMockRequestHandlerExtra>;
+
+describe('getRecordEventTool', () => {
+  let sendSpy: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    sendSpy = vi.fn();
+    vi.mocked(getProductTelemetry).mockReturnValue({ send: sendSpy } as never);
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should create a tool instance with correct properties', async () => {
+    const tool = getRecordEventTool(new WebMcpServer());
+    const annotations = await Provider.from(tool.annotations);
+    expect(tool.name).toBe('record-event');
+    expect(annotations?.readOnlyHint).toBe(true);
+    expect(annotations?.openWorldHint).toBe(false);
+  });
+
+  it('should set visibility to app-only', () => {
+    const tool = getRecordEventTool(new WebMcpServer());
+    expect(tool.meta?.ui?.visibility).toEqual(['app']);
+  });
+
+  it('sends an tableau_mcp_event event with the event_type, message and server context', async () => {
+    const extra = getMockRequestHandlerExtra();
+    const result = await getToolResult(extra, { event_type: 'PARSE_ERROR', message: 'bad json' });
+
+    expect(result.isError).toBe(false);
+    expect(sendSpy).toHaveBeenCalledWith(
+      'tableau_mcp_event',
+      expect.objectContaining({
+        event_type: 'PARSE_ERROR',
+        message: 'bad json',
+        podname: extra.config.server,
+        is_hyperforce: extra.config.isHyperforce,
+      }),
+    );
+  });
+
+  it('defaults message to empty string when omitted', async () => {
+    const extra = getMockRequestHandlerExtra();
+    await getToolResult(extra, { event_type: 'EMBED_LOAD_ERROR', message: undefined });
+
+    expect(sendSpy).toHaveBeenCalledWith(
+      'tableau_mcp_event',
+      expect.objectContaining({ event_type: 'EMBED_LOAD_ERROR', message: '' }),
+    );
+  });
+});
+
+async function getToolResult(
+  extra: Extra,
+  args: { event_type: string; message: string | undefined },
+): Promise<CallToolResult> {
+  const tool = getRecordEventTool(new WebMcpServer());
+  const callback = await Provider.from(tool.callback);
+  return await callback(args, extra);
+}

src/tools/web/recordEvent/recordEvent.ts

@@ -0,0 +1,76 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { Ok } from 'ts-results-es';
+import { z } from 'zod';
+
+import { getFeatureGate } from '../../../features/init.js';
+import { WebMcpServer } from '../../../server.web.js';
+import { getProductTelemetry } from '../../../telemetry/productTelemetry/telemetryForwarder.js';
+import { WebTool } from '../tool.js';
+
+// Starting field set — the final app-supplied schema is expected to grow later.
+const paramsSchema = {
+  event_type: z
+    .string()
+    .describe(
+      'The event type for product telemetry, e.g. TOOL_ERROR, PARSE_ERROR, AUTH_ERROR, EMBED_LOAD_ERROR, MCP_APP_CLICKED.',
+    ),
+  message: z.string().optional().describe('Optional detail or context for the event.'),
+};
+
+/**
+ * Records a product-telemetry event from the MCP app UI (errors, user actions, etc.).
+ * Called by the app (never the model) via app.callServerTool. Mirrors the
+ * server-side 'tool_call' telemetry pattern, enriching the event with request
+ * context the browser bundle does not have.
+ */
+export const getRecordEventTool = (server: WebMcpServer): WebTool<typeof paramsSchema> => {
+  const recordEventTool = new WebTool({
+    server,
+    name: 'record-event',
+    description:
+      'Records a product-telemetry event from the MCP app UI (errors, user actions, etc.). This tool is only visible to the app, never the model. It takes an event type and optional detail, forwards a telemetry event, and returns immediately.',
+    paramsSchema,
+    annotations: {
+      title: 'Record Event',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+    meta: {
+      ui: {
+        visibility: ['app'], // Only visible to the app, not the model
+      },
+    },
+    disabled: !getFeatureGate().isFeatureEnabled('mcp-apps'),
+    callback: async (args, extra): Promise<CallToolResult> => {
+      return recordEventTool.logAndExecute<{ recorded: true }>({
+        extra,
+        args,
+        callback: async () => {
+          const { config } = extra;
+
+          const productTelemetryForwarder = getProductTelemetry(
+            config.productTelemetryEndpoint,
+            config.productTelemetryEnabled,
+            config.server,
+          );
+
+          productTelemetryForwarder.send('tableau_mcp_event', {
+            event_type: args.event_type,
+            message: args.message ?? '',
+            site_luid: extra.getSiteLuid(),
+            user_luid: extra.getUserLuid(),
+            podname: config.server,
+            is_hyperforce: config.isHyperforce,
+          });
+
+          return Ok({ recorded: true as const });
+        },
+        constrainSuccessResult: (result) => ({ type: 'success', result }),
+      });
+    },
+  });
+
+  return recordEventTool;
+};

src/tools/web/tool.test.ts

@@ -230,6 +230,7 @@ describe('Tool', () => {
           is_hyperforce: false,
           success: true,
           error_code: '',
+          error_message: '',
         }),
       );
     });
@@ -252,6 +253,7 @@ describe('Tool', () => {
           is_hyperforce: false,
           success: false,
           error_code: '500',
+          error_message: 'requestId: 2, error: Callback failed',
         }),
       );
     });
@@ -582,6 +584,16 @@ describe('Tool', () => {
       const parsed = JSON.parse(result.content[0].text);
       expect(parsed.data).toEqual(rawApiData.toString());
       expect(parsed.warning).toContain('Expected string, received object');
+
+      // The passthrough result carries the full API payload but is isError: false, so it must
+      // NOT leak into telemetry's error_message (keyed off isError, not the false `success`).
+      expect(mockTelemetrySend).toHaveBeenCalledWith(
+        'tool_call',
+        expect.objectContaining({
+          success: false,
+          error_message: '',
+        }),
+      );
     });
 
     it('should return isError: false with validation warning for discriminatedUnion schema errors', async () => {

src/tools/web/tool.ts

@@ -12,6 +12,7 @@ import {
 } from '../../telemetry/clientDisplayName.js';
 import { getTelemetryProvider } from '../../telemetry/init.js';
 import { getProductTelemetry } from '../../telemetry/productTelemetry/telemetryForwarder.js';
+import { extractToolErrorMessage } from '../../utils/extractToolErrorMessage.js';
 import { getExceptionMessage } from '../../utils/getExceptionMessage.js';
 import { getHttpStatus } from '../../utils/getHttpStatus.js';
 import { LogAndExecuteParams, Tool, ToolParams } from '../tool.js';
@@ -162,7 +163,7 @@ export class WebTool<Args extends ZodRawShape | undefined = undefined> extends T
 
     let success = false;
     let errorCode = ''; // HTTP status category: "4xx", "5xx", or empty for successful calls
-    let toolResult: CallToolResult;
+    let toolResult: CallToolResult | undefined;
 
     try {
       const result = await callback();
@@ -232,6 +233,10 @@ export class WebTool<Args extends ZodRawShape | undefined = undefined> extends T
         is_hyperforce: config.isHyperforce,
         success,
         error_code: errorCode,
+        // Only populated for genuine error results (isError: true). The ZodiosValidationError
+        // passthrough returns isError: false with the full API payload, so keying off isError
+        // (not !success) keeps successful response data out of telemetry.
+        error_message: toolResult?.isError ? extractToolErrorMessage(toolResult) : '',
         oauth_client_id: sanitizeClientIdForTelemetry(oauthClientId),
         oauth_client_display_name:
           getClientDisplayName(oauthClientId) ?? sanitizeClientIdForTelemetry(oauthClientId),

src/tools/web/toolName.ts

@@ -14,6 +14,7 @@ export const webToolNames = [
   'get-datasource-metadata',
   'resolve-datasource-luid',
   'get-embed-token',
+  'record-event',
   'get-workbook',
   'get-view',
   'get-flow',
@@ -94,7 +95,7 @@ export const webToolGroups = {
   ],
   jobs: ['list-jobs'],
   users: ['list-users', 'update-user'],
-  'token-management': ['get-embed-token', 'revoke-access-token', 'reset-consent'],
+  'token-management': ['get-embed-token', 'record-event', 'revoke-access-token', 'reset-consent'],
   'admin-insights': ['query-admin-insights'],
   content: ['delete-content', 'confirm-delete-content'],
 } as const satisfies Record<WebToolGroupName, Array<WebToolName>>;

src/tools/web/tools.ts

@@ -22,6 +22,7 @@ import { getListPulseMetricsFromMetricDefinitionIdTool } from './pulse/listMetri
 import { getListPulseMetricsFromMetricIdsTool } from './pulse/listMetricsFromMetricIds/listPulseMetricsFromMetricIds.js';
 import { getListPulseMetricSubscriptionsTool } from './pulse/listMetricSubscriptions/listPulseMetricSubscriptions.js';
 import { getQueryDatasourceTool } from './queryDatasource/queryDatasource.js';
+import { getRecordEventTool } from './recordEvent/recordEvent.js';
 import { getResetConsentTool } from './resetConsent/resetConsent.js';
 import { getRevokeAccessTokenTool } from './revokeAccessToken/revokeAccessToken.js';
 import { getListUsersTool } from './users/listUsers.js';
@@ -39,6 +40,7 @@ import { getListWorkbooksTool } from './workbooks/listWorkbooks.js';
 export const webToolFactories = [
   getGetDatasourceMetadataTool,
   getEmbedTokenTool,
+  getRecordEventTool,
   getListDatasourcesTool,
   getResolveDatasourceLuidTool,
   getListExtractRefreshTasksTool,

src/utils/extractToolErrorMessage.test.ts

@@ -0,0 +1,62 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+
+import { extractToolErrorMessage } from './extractToolErrorMessage.js';
+
+describe('extractToolErrorMessage', () => {
+  it('returns the text of a single text content block', () => {
+    const result: CallToolResult = {
+      isError: true,
+      content: [{ type: 'text', text: 'Request failed with status code 404' }],
+    };
+
+    expect(extractToolErrorMessage(result)).toBe('Request failed with status code 404');
+  });
+
+  it('joins multiple text blocks with a space', () => {
+    const result: CallToolResult = {
+      isError: true,
+      content: [
+        { type: 'text', text: 'first' },
+        { type: 'text', text: 'second' },
+      ],
+    };
+
+    expect(extractToolErrorMessage(result)).toBe('first second');
+  });
+
+  it('ignores non-text content blocks', () => {
+    const result = {
+      isError: true,
+      content: [
+        { type: 'image', data: 'abc', mimeType: 'image/png' },
+        { type: 'text', text: 'only this' },
+      ],
+    } as unknown as CallToolResult;
+
+    expect(extractToolErrorMessage(result)).toBe('only this');
+  });
+
+  it('returns an empty string when there are no text blocks', () => {
+    const result = {
+      isError: true,
+      content: [{ type: 'image', data: 'abc', mimeType: 'image/png' }],
+    } as unknown as CallToolResult;
+
+    expect(extractToolErrorMessage(result)).toBe('');
+  });
+
+  it('returns an empty string when the text is empty or whitespace only', () => {
+    const result: CallToolResult = {
+      isError: true,
+      content: [{ type: 'text', text: '   ' }],
+    };
+
+    expect(extractToolErrorMessage(result)).toBe('');
+  });
+
+  it('returns an empty string when content is not an array', () => {
+    const result = { isError: true, content: undefined } as unknown as CallToolResult;
+
+    expect(extractToolErrorMessage(result)).toBe('');
+  });
+});