: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
import { randomUUID } from 'node:crypto'
import type { MCPAnalyticsIntentSource, MCPAnalyticsModelSource } from '@posthog/mcp-analytics'
import type { McpAuthFailure } from '@/lib/auth-errors'
import { classifyAuthMethod } from '@/lib/auth-method'
import { MCP_ANALYTICS_SOURCE, MCP_SERVER_NAME, MCP_SERVER_VERSION } from '@/lib/constants'
import { EVENT_SOURCE, resolveEventSource } from '@/lib/event-source'
import { gatewayServerSlug, isGatewayToolName, THIRD_PARTY_TOOL_CATEGORY } from '@/lib/gateway-tools'
import { getPostHogClient } from '@/lib/posthog'
import {
buildMCPAnalyticsGroups,
buildMCPContextProperties,
MCP_ANALYTICS_VERSION,
type MCPAnalyticsContext,
} from '@/lib/posthog/analytics'
import { type RequestProperties, sanitizeToolFilterNames } from '@/lib/request-properties'
import { resolveScopePreset } from '@/lib/scope-preset'
import { isPrivateScoutTrialTool } from '@/lib/tool-privacy'
import type { SkillInvocation } from '@/tools/exec-learn'
import { EXECUTE_SQL_TOOL_NAME } from '@/tools/posthogAiTools/executeSql'
import { MAX_CAPTURED_DESCRIPTION_LENGTH, getToolCategory, getToolDescription } from '@/tools/toolDefinitions'
import { APP_DATA_META_KEY } from '@/ui-apps/types'
import { MCP_INBOX_FIRST_FLAG } from './constants'
import { MCP_INTENT_PROMPT_FLAG } from './intent-prompt'
import { interviewRecruitmentProperties } from './interview-recruitment'
import { buildMCPSessionAnalyticsProperties, getEffectiveMCPClientIdentity } from './mcp-context'
import type { ResolvedState } from './request-state-resolver'
function buildBaseProperties(
state: ResolvedState,
analyticsContext: MCPAnalyticsContext | undefined
): {
properties: Record<string, unknown>
groups: Record<string, string>
} {
const groups = analyticsContext ? buildMCPAnalyticsGroups(analyticsContext) : {}
const requestContext = state.requestContext
// Live-first per-field: `clientInfo` only arrives on `initialize`, so a mid-session
// `tools/call` has no live client identity of its own. Falls back to the
// session-pinned value per field (not swapping in the whole session object) so a
// live value from a concurrent request on the same server always wins. See
// `getEffectiveMCPClientIdentity` for why this must differ from
// `getEffectiveMCPClientContext`.
const clientIdentity = getEffectiveMCPClientIdentity(requestContext, state.sessionContext)
const properties: Record<string, unknown> = {
$ai_product: 'mcp',
is_impersonated: state.isImpersonated === true,
suppress_analytics: state.suppressAnalytics === true,
// The same property `posthog/event_usage.py` stamps on product events, so an MCP call
// and the API work it causes land in one breakdown. Distinct from `$mcp_source`, which
// names the emitting SDK rather than the surface.
source: resolveEventSource({
mcpConsumer: clientIdentity.mcpConsumer,
clientUserAgent: requestContext.clientUserAgent,
apiKeyScopes: state.apiKeyScopes,
oauthClientId: state.oauthClientId,
}),
$mcp_source: MCP_ANALYTICS_SOURCE,
$mcp_server_name: MCP_SERVER_NAME,
$mcp_server_version: MCP_SERVER_VERSION,
$mcp_version: MCP_ANALYTICS_VERSION,
$mcp_client_name: clientIdentity.mcpClientName,
$mcp_client_version: clientIdentity.mcpClientVersion,
$mcp_client_user_agent: requestContext.clientUserAgent,
$mcp_protocol_version: clientIdentity.mcpProtocolVersion,
$mcp_transport: requestContext.transport,
$mcp_session_id: requestContext.mcpSessionId,
// Present only when there is a handle. An explicit `undefined` would erase the value the
// SDK maps from its own `conversationId` field, because caller properties merge last.
...(requestContext.mcpConversationId ? { $mcp_conversation_id: requestContext.mcpConversationId } : {}),
$mcp_consumer: clientIdentity.mcpConsumer,
$mcp_mode: requestContext.mode,
$mcp_region: requestContext.region,
$mcp_auth_method: requestContext.authMethod,
// Which kind of caller minted this token — scout, research run, implementation run, or
// ordinary user — so scratchpad and notes calls split by caller in one breakdown.
$mcp_scope_preset: resolveScopePreset(state.apiKeyScopes),
// Server-derived from introspection, so a refused call can be traced to the run it came from.
...(state.sandboxTaskId ? { sandbox_task_id: state.sandboxTaskId } : {}),
...(analyticsContext
? {
$mcp_organization_id: analyticsContext.organizationId,
$mcp_project_id: analyticsContext.projectId,
$mcp_project_uuid: analyticsContext.projectUuid,
$mcp_project_name: analyticsContext.projectName,
...buildMCPContextProperties(analyticsContext),
}
: {}),
mcp_runtime: 'hono',
$mcp_vendor_client: clientIdentity.mcpVendorClient,
...buildMCPSessionAnalyticsProperties(state.sessionContext),
}
return { properties, groups }
}
export async function trackInitEvent(state: ResolvedState): Promise<void> {
try {
const analyticsContext = await state.reqCtx.safelyGetAnalyticsContext(state.context)
const requestContext = state.requestContext
const sessionUuid = await state.reqCtx.getEffectiveSessionUuid(requestContext)
const initDurationMs = requestContext.requestStartTime
? Date.now() - requestContext.requestStartTime
: undefined
const { properties, groups } = buildBaseProperties(state, analyticsContext)
const requestedFeatures = sanitizeToolFilterNames(requestContext.features)
const requestedTools = sanitizeToolFilterNames(requestContext.tools)
// Emits `$mcp_initialize`. The SDK maps `durationMs` → `$mcp_duration_ms`
// and `sessionId` → `$session_id`; everything else rides on `properties`.
getPostHogClient().captureInitialize({
distinctId: state.distinctId,
groups,
durationMs: initDurationMs ?? 0,
...(sessionUuid ? { sessionId: sessionUuid } : {}),
// Omitted rather than set to `undefined`: the SDK applies caller properties last, so
// an explicit `undefined` erases the value it maps from this field.
...(requestContext.mcpConversationId ? { conversationId: requestContext.mcpConversationId } : {}),
properties: {
...properties,
$mcp_is_error: false,
tool_count: state.allTools.length,
has_organization_id: !!requestContext.organizationId,
has_project_id: !!requestContext.projectId,
read_only: !!requestContext.readOnly,
via_sse_redirect: !!requestContext.viaSseRedirect,
...(requestedFeatures ? { requested_features: requestedFeatures } : {}),
...(requestedTools ? { requested_tools: requestedTools } : {}),
...(requestContext.excludeTools ? { requested_exclude_tools: requestContext.excludeTools } : {}),
},
})
} catch {
// never break the request for analytics
}
}
type ModelMissingReason = 'missing' | 'unknown' | 'invalid' | 'not_captured' | 'capture_error'
export function getModelMissingReason(modelArgument: unknown): ModelMissingReason {
if (modelArgument === undefined) {
return 'missing'
}
if (typeof modelArgument !== 'string' || !modelArgument.trim()) {
return 'invalid'
}
if (modelArgument.trim().toLowerCase() === 'unknown') {
return 'unknown'
}
return 'not_captured'
}
export interface ToolCallAnalyticsMeta {
/** The agent's stated intent (the injected `context` arg) → `$mcp_intent`. */
intent?: string
/** Where it came from → `$mcp_intent_source`. */
intentSource?: MCPAnalyticsIntentSource
/** The calling model -> `$mcp_llm_model`. */
llmModel?: string
/** Where the model identifier came from -> `$mcp_llm_model_source`. */
llmModelSource?: MCPAnalyticsModelSource
llmModelMissingReason?: ModelMissingReason
}
export async function trackToolCall(
toolName: string,
durationMs: number,
isError: boolean,
state: ResolvedState,
extraProperties?: Record<string, unknown>,
analyticsMeta?: ToolCallAnalyticsMeta,
servedDescription?: string
): Promise<void> {
// Operator tokens are ordinary tokens, but comparison details must stay out of scout-readable analytics.
if (isPrivateScoutTrialTool(toolName) || isPrivateScoutTrialTool(extraProperties?.$mcp_exec_target_tool)) {
return
}
try {
const analyticsContext = state.analyticsContext ?? (await state.reqCtx.safelyGetAnalyticsContext(state.context))
const requestContext = state.requestContext
const sessionUuid = await state.reqCtx.getEffectiveSessionUuid(requestContext)
const { properties, groups } = buildBaseProperties(state, analyticsContext)
// The producer stamps the tool's category so the dashboard groups by it verbatim
// (it never maps tool→category itself). Omitted when unknown (e.g. the `exec`
// wrapper), which the dashboard buckets as "Uncategorized".
// A proxied third-party tool has no catalog entry, so without the fallback every
// gateway call would land uncategorized and drop out of category-sliced views.
const gatewayServer = gatewayServerSlug(toolName)
const toolCategory = getToolCategory(toolName) ?? (gatewayServer ? THIRD_PARTY_TOOL_CATEGORY : undefined)
if (!isError && !gatewayServer && toolName.startsWith('inbox-') && properties.source === EVENT_SOURCE.MCP) {
// The Inbox banner flag targets this permanent adoption property.
properties.$set_once = { has_used_inbox_mcp: true }
}
// The description the agent saw when it picked this tool, clipped. Powers the
// tool-detail Descriptions table and description-vs-intent fit in MCP
// analytics. Callers pass servedDescription when the advertised text differs
// from the catalog (execute-sql's is formatted per request); otherwise the
// catalog text is what was served. Inner exec calls reach here with the
// resolved inner tool name, so the fallback lands on the inner tool's own
// description.
const toolDescription = servedDescription
? servedDescription.slice(0, MAX_CAPTURED_DESCRIPTION_LENGTH)
: getToolDescription(toolName)
// Emits `$mcp_tool_call` (+ `$mcp_is_error`). The SDK maps `toolName` →
// `$mcp_tool_name`, `durationMs` → `$mcp_duration_ms`, `isError` →
// `$mcp_is_error`, `intent` → `$mcp_intent`, and `sessionId` →
// `$session_id`. `$exception` fan-out is disabled on the client, so an
// errored call stays a single event.
getPostHogClient().captureToolCall({
toolName,
durationMs,
isError,
distinctId: state.distinctId,
groups,
...(sessionUuid ? { sessionId: sessionUuid } : {}),
// Omitted rather than set to `undefined`: the SDK applies caller properties last, so
// an explicit `undefined` erases the value it maps from this field.
...(requestContext.mcpConversationId ? { conversationId: requestContext.mcpConversationId } : {}),
...(analyticsMeta?.intent ? { intent: analyticsMeta.intent } : {}),
...(analyticsMeta?.intentSource ? { intentSource: analyticsMeta.intentSource } : {}),
...(analyticsMeta?.llmModel ? { llmModel: analyticsMeta.llmModel } : {}),
...(analyticsMeta?.llmModelSource ? { llmModelSource: analyticsMeta.llmModelSource } : {}),
properties: {
...properties,
tool_name: toolName,
...(state.interviewRecruitmentDiagnostics && !state.isImpersonated && !state.suppressAnalytics
? interviewRecruitmentProperties(state.interviewRecruitmentDiagnostics)
: {}),
...(!analyticsMeta?.llmModel && analyticsMeta?.llmModelMissingReason
? { $mcp_llm_model_missing_reason: analyticsMeta.llmModelMissingReason }
: {}),
...(toolCategory ? { $mcp_tool_category: toolCategory } : {}),
...(toolDescription ? { $mcp_tool_description: toolDescription } : {}),
// Which vendor ran the tool, so "who do people actually call" is a
// breakdown rather than a string split over `tool_name` in HogQL.
...(gatewayServer ? { mcp_gateway_server: gatewayServer } : {}),
...extraProperties,
[`$feature/${MCP_INTENT_PROMPT_FLAG}`]: state.toolFeatureFlags?.[MCP_INTENT_PROMPT_FLAG],
[`$feature/${MCP_INBOX_FIRST_FLAG}`]: state.toolFeatureFlags?.[MCP_INBOX_FIRST_FLAG],
is_impersonated: state.isImpersonated === true,
suppress_analytics: state.suppressAnalytics === true,
},
})
} catch {
// never break the request for analytics
}
}
export interface ExecuteSqlGenerationMeta {
durationMs: number
isError: boolean
errorMessage?: string
}
/**
* Manually captures an `$ai_generation` per `execute-sql` call — the client's LLM
* authored the query; this server is the observer that sees intent and output
* together. Lands in LLM analytics, where online evaluations (LLM judge / Hog) can
* score it for anti-patterns on live traffic. `$ai_trace_id` is the MCP session
* uuid, so a session's queries group into one trace.
*/
export async function trackExecuteSqlGeneration(
toolName: string,
args: unknown,
state: ResolvedState,
meta: ExecuteSqlGenerationMeta,
analyticsMeta?: ToolCallAnalyticsMeta
): Promise<void> {
if (toolName !== EXECUTE_SQL_TOOL_NAME) {
return
}
const query = (args as { query?: unknown } | null | undefined)?.query
if (typeof query !== 'string' || query.length === 0) {
return
}
try {
const analyticsContext = await state.reqCtx.safelyGetAnalyticsContext(state.context)
const sessionUuid = await state.reqCtx.getEffectiveSessionUuid(state.requestContext)
const { properties, groups } = buildBaseProperties(state, analyticsContext)
getPostHogClient().capture({
distinctId: state.distinctId,
event: '$ai_generation',
groups,
properties: {
...properties,
...(sessionUuid ? { $session_id: sessionUuid } : {}),
$ai_trace_id: sessionUuid ?? randomUUID(),
$ai_span_name: EXECUTE_SQL_TOOL_NAME,
$ai_input: [{ role: 'user', content: analyticsMeta?.intent ?? '' }],
$ai_output_choices: [{ role: 'assistant', content: query }],
$ai_latency: meta.durationMs / 1000,
$ai_is_error: meta.isError,
...(meta.errorMessage ? { $ai_error: meta.errorMessage } : {}),
},
})
} catch {
// never break the request for analytics
}
}
const METADATA_QUERY_MARKER = 'information_schema'
const MAX_SPAN_STATE_LENGTH = 30_000
export interface ToolSpanMeta {
durationMs: number
isError: boolean
errorMessage?: string
input?: unknown
output?: unknown
}
// Comments and single-quoted string literals can carry the metadata marker
// without the query actually reading a metadata relation, so they're stripped
// before the check — otherwise a data query like `... WHERE 'information_schema'
// != ''` would be mis-tagged as metadata and its result captured.
function stripSqlCommentsAndLiterals(query: string): string {
return query
.replace(/--[^\n]*/g, ' ')
.replace(/\/\*[\s\S]*?\*\//g, ' ')
.replace(/'(?:''|[^'])*'/g, ' ')
}
function isMetadataQuery(query: string): boolean {
return stripSqlCommentsAndLiterals(query).toLowerCase().includes(METADATA_QUERY_MARKER)
}
// Its result is a live presigned S3 POST — a policy, signature and credential fields
// that grant write access to one object-storage key until they expire. Key-based
// redaction can't reach them: they're byte-identical output fields (`upload_url`,
// `form_fields`), not fields whose *name* looks like a secret, and the policy
// document also embeds the credential in a form redaction wouldn't recognize either
// way. `$mcp_tool_call` still records that the call happened.
const PRESIGNED_UPLOAD_TOOL_NAME = 'media-image-upload-start'
// Their output is another project's data, possibly from another region: a wrapped
// execute-sql result or any API response. The execute-sql exemption below checks only
// the outer tool name, so without this check the wrapped query's rows land in
// `$ai_output_state`.
const POSTHOG_CONNECTION_TOOL_NAMES: ReadonlySet<string> = new Set([
'posthog-connection-call',
'posthog-connection-forward',
])
// A send's recipient address, subject and distinct ID are a customer's own customer data, and the list takes an
// address as its search. Key-based redaction catches none of them. `$mcp_tool_call` still records the call.
const EMAIL_RECIPIENT_TOOL_NAMES: ReadonlySet<string> = new Set([
'workflows-transactional-emails-list',
'workflows-transactional-email-get',
])
const EMAIL_SEND_TOOL_PREFIX = 'workflows-send-email'
function sendsEmailContent(toolName: string, input: unknown): boolean {
if (toolName.startsWith(EMAIL_SEND_TOOL_PREFIX)) {
return true
}
// Match the whole exec command, not its parsed inner tool: a send forwarded through
// posthog-connection-call, or a command exec rejects, still carries the email body.
const command = (input as { command?: unknown } | null | undefined)?.command
return toolName === 'exec' && typeof command === 'string' && command.includes(EMAIL_SEND_TOOL_PREFIX)
}
function readsEmailRecipients(toolName: string, input: unknown): boolean {
if (EMAIL_RECIPIENT_TOOL_NAMES.has(toolName)) {
return true
}
const command = (input as { command?: unknown } | null | undefined)?.command
return (
toolName === 'exec' &&
typeof command === 'string' &&
[...EMAIL_RECIPIENT_TOOL_NAMES].some((name) => command.includes(name))
)
}
function shouldCaptureToolSpan(toolName: string, input: unknown): boolean {
if (isPrivateScoutTrialTool(toolName)) {
return false
}
if (sendsEmailContent(toolName, input)) {
return false
}
// A proxied third-party tool's args and result are the vendor's content — an issue
// body, a support ticket, a CRM record — passing through our gateway on its way
// somewhere else. Key-based redaction only catches credential-shaped fields, so
// capturing these would put arbitrary customer content in analytics to serve
// evaluations that target PostHog's own tools. `$mcp_tool_call` still records that
// the call happened, with its server, duration and outcome.
if (isGatewayToolName(toolName)) {
return false
}
if (toolName === PRESIGNED_UPLOAD_TOOL_NAME) {
return false
}
if (POSTHOG_CONNECTION_TOOL_NAMES.has(toolName)) {
return false
}
if (readsEmailRecipients(toolName, input)) {
return false
}
// execute-sql can't be captured wholesale: its payload is the query result,
// which is the bulk of MCP response volume. Metadata queries are the
// exception, because their results are small and describe what the agent
// learned about the workspace before writing its next query, which is the
// context an evaluation needs to judge that query.
if (toolName !== EXECUTE_SQL_TOOL_NAME) {
return true
}
const query = (input as { query?: unknown } | null | undefined)?.query
return typeof query === 'string' && isMetadataQuery(query)
}
const REDACTED_VALUE = '[redacted]'
// Capturing every tool's raw args would land credentials in telemetry: tools
// like user-settings-update carry `password`/`current_password`, warehouse
// sources carry `client_secret`, and hog-function inputs carry `secret` values.
// Match errs toward redaction — an over-redacted eval field is harmless, a
// leaked credential is not.
//
// Enumerating credential prefixes missed most of them: our own warehouse sources
// name their secret `api_token`, `database_token`, `consumer_key`,
// `signing_key`, and a dozen more, none of which the prefix list matched. The
// trailing-segment rule catches that whole shape. Plural `*_tokens` stays out on
// purpose — it is LLM token counts and Adjust's `app_tokens` app ids, never a
// secret. `connection_string` gets its own name: Postgres, MSSQL, Redshift,
// Snowflake and friends all accept one as an alternative to discrete
// host/user/password fields, and it carries the credentials inline
// (`postgres://user:pass@host/db`) — MongoDB's source has no other field for them.
// `certificate` covers Temporal Cloud's `client_certificate`: the source config
// itself marks it `secret: true` even though the name reads as public key
// material, and a client cert is namespace-identifying enough to keep out of
// telemetry too. `server_client_root_ca` stays unmatched on purpose — it is
// the CA the client uses to verify the *server*, public key material with no
// private half, marked `secret: true` only because the UI groups it with the
// real credentials.
//
// `app_id`/`api_id` and the trailing `username` case cover sources whose
// credential is an identifier rather than a token: Open Exchange Rates'
// `app_id` and Veracode's `api_id` are the whole usable credential, and
// Pipeliner generates its `username` alongside `password` as one half of a
// one-time API key pair (`secret: true` on the source config), unlike every
// other source's plain login `username`. Aircall's `api_id` and
// AppsFlyer/AppSignal/Churnkey's `app_id` are not credentials — they select
// which account or app an already-redacted token applies to — but the
// pattern can't tell those apart by name, and over-redacting a non-secret
// identifier is harmless where under-redacting a credential is not.
const SENSITIVE_KEY_PATTERN =
/password|passwd|passphrase|secret|credential|certificate|private[_-]?key|access[_-]?key|api[_-]?key|access[_-]?token|refresh[_-]?token|auth[_-]?token|session[_-]?token|authorization|bearer|keypair|key[_-]?file|token[_-]?request|connection[_-]?string|app[_-]?id|api[_-]?id|(^|[_-])(token|key|keys|username)$/i
function redactSecrets(value: unknown): unknown {
if (Array.isArray(value)) {
return value.map(redactSecrets)
}
if (value !== null && typeof value === 'object') {
return Object.fromEntries(
Object.entries(value).map(([key, val]) => [
key,
SENSITIVE_KEY_PATTERN.test(key) ? REDACTED_VALUE : redactSecrets(val),
])
)
}
return value
}
function serializeSpanState(value: unknown): string | undefined {
if (value === undefined) {
return undefined
}
try {
const redacted = redactSecrets(value)
const serialized = typeof redacted === 'string' ? redacted : JSON.stringify(redacted)
return serialized?.slice(0, MAX_SPAN_STATE_LENGTH)
} catch {
return undefined
}
}
function omitAppData(output: unknown): unknown {
if (typeof output !== 'object' || output === null || Array.isArray(output)) {
return output
}
const result = output as Record<string, unknown>
const meta = result._meta
if (typeof meta !== 'object' || meta === null || Array.isArray(meta) || !(APP_DATA_META_KEY in meta)) {
return output
}
const sanitizedMeta: Record<string, unknown> = { ...meta }
delete sanitizedMeta[APP_DATA_META_KEY]
return { ...result, _meta: sanitizedMeta }
}
/**
* Captures an `$ai_span` for a tool call, joining the same MCP-session trace as
* the execute-sql `$ai_generation` events. Trace-target online evaluations then
* see a call's args AND result, neither of which `$mcp_tool_call` carries.
*
* Every tool is captured by default. `execute-sql` is the one exception: its
* payload is the query result and it serves the bulk of MCP volume, so only its
* metadata queries are captured (see {@link shouldCaptureToolSpan}).
*/
export async function trackToolSpan(toolName: string, state: ResolvedState, meta: ToolSpanMeta): Promise<void> {
try {
if (!shouldCaptureToolSpan(toolName, meta.input)) {
return
}
const analyticsContext = await state.reqCtx.safelyGetAnalyticsContext(state.context)
const sessionUuid = await state.reqCtx.getEffectiveSessionUuid(state.requestContext)
const { properties, groups } = buildBaseProperties(state, analyticsContext)
const toolCategory = getToolCategory(toolName)
const inputState = serializeSpanState(meta.input)
const outputState = serializeSpanState(
state.clientProfile.consumer === 'posthog_ai' ? omitAppData(meta.output) : meta.output
)
getPostHogClient().capture({
distinctId: state.distinctId,
event: '$ai_span',
groups,
properties: {
...properties,
...(sessionUuid ? { $session_id: sessionUuid } : {}),
$ai_trace_id: sessionUuid ?? randomUUID(),
$ai_span_name: toolName,
...(toolCategory ? { $mcp_tool_category: toolCategory } : {}),
...(inputState !== undefined ? { $ai_input_state: inputState } : {}),
...(outputState !== undefined ? { $ai_output_state: outputState } : {}),
$ai_latency: meta.durationMs / 1000,
$ai_is_error: meta.isError,
...(meta.errorMessage ? { $ai_error: meta.errorMessage } : {}),
},
})
} catch {
// never break the request for analytics
}
}
/**
* Emits `$mcp_auth_failed` for a request the PostHog API refused. These requests die
* before `RequestStateResolver.resolve` returns, so they never reach
* `trackInitEvent`/`trackToolCall` and are otherwise invisible in analytics — a
* connector stuck in an authorize loop looks like a gap in the data rather than a
* failure. Keyed on `userHash` (a hash of the bearer token, never the token itself)
* so affected credentials can be counted without identifying anyone.
*
* Only PostHog's own server emits this; no SDK does. It reuses the canonical `$mcp_*`
* client-identity fields so one query can group it and real MCP traffic by the same
* dimensions.
*/
export function trackAuthFailure(props: RequestProperties, failure: McpAuthFailure): void {
try {
getPostHogClient().capture({
distinctId: props.userHash,
event: '$mcp_auth_failed',
properties: {
$ai_product: 'mcp',
suppress_analytics: props.suppressAnalytics === true,
// Resolved without scopes — the request never authenticated, so nothing can
// vouch for a declared consumer and anything unproven lands as `mcp`.
source: resolveEventSource({
mcpConsumer: props.mcpConsumer,
clientUserAgent: props.clientUserAgent,
}),
$mcp_source: MCP_ANALYTICS_SOURCE,
$mcp_server_name: MCP_SERVER_NAME,
$mcp_server_version: MCP_SERVER_VERSION,
$mcp_version: MCP_ANALYTICS_VERSION,
$mcp_client_name: props.mcpClientName,
$mcp_client_version: props.mcpClientVersion,
$mcp_client_user_agent: props.clientUserAgent,
$mcp_protocol_version: props.mcpProtocolVersion,
$mcp_transport: props.transport,
$mcp_session_id: props.mcpSessionId,
$mcp_conversation_id: props.mcpConversationId,
$mcp_consumer: props.mcpConsumer,
$mcp_mode: props.mode,
$mcp_region: props.region,
$mcp_auth_method: classifyAuthMethod(props.apiToken),
mcp_runtime: 'hono',
$mcp_vendor_client: props.mcpVendorClient,
$mcp_auth_failure_reason: failure.reason,
...(failure.status ? { $mcp_auth_status: failure.status } : {}),
...(failure.missingScope ? { $mcp_missing_scope: failure.missingScope } : {}),
has_organization_id: !!props.organizationId,
has_project_id: !!props.projectId,
},
})
} catch {
// never break the request for analytics
}
}
export async function trackToolsList(toolNames: string[], state: ResolvedState): Promise<void> {
try {
const analyticsContext = await state.reqCtx.safelyGetAnalyticsContext(state.context)
const requestContext = state.requestContext
const sessionUuid = await state.reqCtx.getEffectiveSessionUuid(requestContext)
const { properties, groups } = buildBaseProperties(state, analyticsContext)
// The SDK maps `toolNames` → `$mcp_listed_tool_names`, which powers
// "advertised but never called" analysis.
getPostHogClient().captureToolsList({
toolNames,
distinctId: state.distinctId,
groups,
...(sessionUuid ? { sessionId: sessionUuid } : {}),
// Omitted rather than set to `undefined`: the SDK applies caller properties last, so
// an explicit `undefined` erases the value it maps from this field.
...(requestContext.mcpConversationId ? { conversationId: requestContext.mcpConversationId } : {}),
properties: {
...properties,
tool_count: toolNames.length,
},
})
} catch {
// never break the request for analytics
}
}
/**
* Captures `skill invoked` when a skill's content is consumed through exec `learn`,
* whichever read kind delivered it (full load, file read, file search, line range) —
* the consumption counterpart of the authoring `llma skill *` events emitted by
* `products/skills`. The caller dedupes per skill identifier per request, so a
* command that reads one skill several ways still counts once. Keep property keys
* additive: they feed the same LLMA skills adoption dashboards.
*/
export async function trackSkillInvoked(state: ResolvedState, invocation: SkillInvocation): Promise<void> {
try {
const analyticsContext = await state.reqCtx.safelyGetAnalyticsContext(state.context)
const sessionUuid = await state.reqCtx.getEffectiveSessionUuid(state.requestContext)
const { properties, groups } = buildBaseProperties(state, analyticsContext)
getPostHogClient().capture({
distinctId: state.distinctId,
event: 'skill invoked',
groups,
properties: {
...properties,
...(sessionUuid ? { $session_id: sessionUuid } : {}),
skill_source: invocation.source,
skill_name: invocation.skill,
skill_identifier: `${invocation.source}:${invocation.skill}`,
skill_read_kind: invocation.readKind,
},
})
} catch {
// never break the request for analytics
}
}