Skip to content

: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.

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.ts
index 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.ts
index 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 the
diff --git a/services/mcp/src/lib/posthog/analytics.ts b/services/mcp/src/lib/posthog/analytics.ts
index 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?: string
projectId?: 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.ts
index 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,