:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(mcp): stamp error code on cli tool-call events (#120080)
Vasco de Krijgerb6899cb403f1
diff --git a/services/mcp/src/cli/tool-call-properties.ts b/services/mcp/src/cli/tool-call-properties.tsindex 0f05c2eb83b7..158213684e64 100644--- a/services/mcp/src/cli/tool-call-properties.ts+++ b/services/mcp/src/cli/tool-call-properties.ts@@ -1,5 +1,5 @@-import { MCPToolResultError } from '@/lib/errors'-import { AnalyticsEvent } from '@/lib/posthog/analytics'+import { MCPToolResultError, PostHogValidationError, findRecoverableApiError } from '@/lib/errors'+import { AnalyticsEvent, sanitizeErrorToken } from '@/lib/posthog/analytics'import { isPrivateScoutTrialTool } from '@/lib/tool-privacy'import type { ExecInnerCallProperties } from '@/tools/exec'import { getToolCategory, getToolDescription } from '@/tools/toolDefinitions'@@ -8,11 +8,12 @@ import type { Context } from '@/tools/types'/*** `$mcp_tool_call` properties for the CLI. Value-free by design: raw error* messages and inputs can carry caller-supplied content and API response- * bodies, which must never reach usage analytics. Mirrors the hosted server,- * whose tool-call events carry only the error flag — plus a bounded- * classification so failures stay diagnosable. Category and clipped- * description come from the tool catalog (never the caller), matching the- * hosted server's stamps so per-tool analytics see one schema.+ * bodies, which must never reach usage analytics. Unlike the hosted server,+ * the CLI never sends an error message, even a sanitized one. It sends only a+ * bounded classification and the backend's machine-readable error code, so+ * failures stay diagnosable. Category and clipped description come from the+ * tool catalog (never the caller), matching the hosted server's stamps so+ * per-tool analytics see one schema.*/export function buildToolCallProperties(toolName: string,@@ -20,6 +21,7 @@ export function buildToolCallProperties(): Record<string, unknown> {const category = getToolCategory(toolName)const description = getToolDescription(toolName)+ const code = errorCode(properties.error)return {tool_name: toolName,$mcp_tool_name: toolName,@@ -28,7 +30,13 @@ export function buildToolCallProperties(output_format: properties.output_format,...(category ? { $mcp_tool_category: category } : {}),...(description ? { $mcp_tool_description: description } : {}),- ...(properties.success ? {} : { error_class: errorClass(properties), $mcp_error_type: errorType(properties) }),+ ...(properties.success+ ? {}+ : {+ error_class: errorClass(properties),+ $mcp_error_type: errorType(properties),+ ...(code ? { $mcp_error_code: code } : {}),+ }),...(properties.error_status !== undefined? { error_status: properties.error_status, $mcp_error_status: properties.error_status }: {}),@@ -80,3 +88,13 @@ function errorType(properties: ExecInnerCallProperties): MCPToolResultError['err}return status >= 500 ? 'api_5xx' : 'api_4xx'}++function errorCode(error: unknown): string | undefined {+ const code = error instanceof MCPToolResultError ? error.errorCode : apiValidationErrorCode(error)+ return code ? sanitizeErrorToken(code) : undefined+}++function apiValidationErrorCode(error: unknown): string | undefined {+ const apiError = findRecoverableApiError(error)+ return apiError instanceof PostHogValidationError ? apiError.code : undefined+}diff --git a/services/mcp/src/hono/tool-executor.ts b/services/mcp/src/hono/tool-executor.tsindex e6dd8570014a..d31f496e3b98 100644--- a/services/mcp/src/hono/tool-executor.ts+++ b/services/mcp/src/hono/tool-executor.ts@@ -28,6 +28,7 @@ import { estimateTokens } from '@/lib/estimate-tokens'import { resolveGatewayTools } from '@/lib/gateway-tools'import { findIgnoredInputKeys, withIgnoredInputKeys } from '@/lib/ignored-input-keys'import { getPostHogClient } from '@/lib/posthog'+import { sanitizeErrorToken } from '@/lib/posthog/analytics'import { isPrivateScoutTrialTool } from '@/lib/tool-privacy'import {createExecTool,@@ -1039,22 +1040,6 @@ function resolveToolErrorClassification(error: unknown): ToolErrorClassification// the bound external servers get when they pass `error` to the SDK.const MAX_ERROR_MESSAGE_LENGTH = 2048-// Matches the truncation the MCP analytics queries apply to `$mcp_error_type`.-const MAX_ERROR_TOKEN_LENGTH = 200--/**- * DRF error codes and attrs are server-generated (field names and error codes,- * never caller values), but they cross a network boundary — strip control- * characters and cap length so a malformed body can't pollute the property.- */-function sanitizeErrorToken(token: string): string | undefined {- const sanitized = token- .replace(/[\x00-\x1f\x7f]/g, '')- .trim()- .slice(0, MAX_ERROR_TOKEN_LENGTH)- return sanitized || undefined-}-/*** Collapses array indexes in a DRF attr path (`actions__2__inputs__email`) to* `N` so one leaf failure mode groups to one value regardless of where in thediff --git a/services/mcp/src/lib/posthog/analytics.ts b/services/mcp/src/lib/posthog/analytics.tsindex 4d8afbe97b76..74b5735f2e8f 100644--- a/services/mcp/src/lib/posthog/analytics.ts+++ b/services/mcp/src/lib/posthog/analytics.ts@@ -10,6 +10,9 @@ export enum AnalyticsEvent {// keeps the property stable for dashboards that already filter on it.export const MCP_ANALYTICS_VERSION = 2+// Matches the truncation the MCP analytics queries apply to `$mcp_error_type`.+const MAX_ERROR_TOKEN_LENGTH = 200+export type MCPAnalyticsContext = {organizationId?: stringprojectId?: string@@ -48,3 +51,16 @@ export const buildMCPContextProperties = (...(ctx.projectUuid ? { [`${prefix}project_uuid`]: ctx.projectUuid } : {}),...(ctx.projectName ? { [`${prefix}project_name`]: ctx.projectName } : {}),})++/**+ * Backend error codes and DRF field paths come from server code, never caller+ * values, but they cross a network boundary. Strip control characters and cap+ * the length so a malformed body can't pollute the property.+ */+export function sanitizeErrorToken(token: string): string | undefined {+ const sanitized = token+ .replace(/[\x00-\x1f\x7f]/g, '')+ .trim()+ .slice(0, MAX_ERROR_TOKEN_LENGTH)+ return sanitized || undefined+}diff --git a/services/mcp/tests/cli/tool-call-properties.test.ts b/services/mcp/tests/cli/tool-call-properties.test.tsindex 4d289c79e04a..ffaede81c046 100644--- a/services/mcp/tests/cli/tool-call-properties.test.ts+++ b/services/mcp/tests/cli/tool-call-properties.test.ts@@ -1,7 +1,7 @@import { describe, expect, it } from 'vitest'import { buildToolCallProperties } from '@/cli/tool-call-properties'-import { MCPToolResultError } from '@/lib/errors'+import { MCPToolResultError, PostHogValidationError } from '@/lib/errors'import type { ExecInnerCallProperties } from '@/tools/exec'import { getToolCategory, getToolDescription } from '@/tools/toolDefinitions'@@ -85,6 +85,32 @@ describe('buildToolCallProperties', () => {{ error: new MCPToolResultError('Private query details', 'memory_limit') },{ error_class: 'error', $mcp_error_type: 'memory_limit' },],+ [+ 'backend failure with a malformed error code',+ { error: new MCPToolResultError('Private SQL input', 'validation', ' query_\nsyntax\x00 ') },+ { error_class: 'error', $mcp_error_type: 'validation', $mcp_error_code: 'query_syntax' },+ ],+ [+ 'backend API validation failure',+ {+ error_status: 400,+ error: new PostHogValidationError({+ detail: 'Private field value',+ attr: 'name',+ code: 'required',+ extra: undefined,+ url: 'https://example.com/api/projects/1/feature_flags/',+ method: 'POST',+ }),+ },+ {+ error_class: 'api_error',+ error_status: 400,+ $mcp_error_type: 'api_4xx',+ $mcp_error_status: 400,+ $mcp_error_code: 'required',+ },+ ],])('classifies a %s without carrying the message', (_name, extra, expected) => {expect(buildToolCallProperties('execute-sql', { ...base, ...extra })).toEqual({tool_name: 'execute-sql',@@ -98,7 +124,8 @@ describe('buildToolCallProperties', () => {})it('omits error fields entirely on success', () => {- expect(buildToolCallProperties('feature-flag-get-all', { ...base, success: true })).toEqual({+ const coded = new MCPToolResultError('Private details', 'validation', 'unknown_identifier')+ expect(buildToolCallProperties('feature-flag-get-all', { ...base, success: true, error: coded })).toEqual({tool_name: 'feature-flag-get-all',$mcp_tool_name: 'feature-flag-get-all',$mcp_duration_ms: 42,