Event and property reference

This page is the wire-level contract for the MCP Analytics SDKs. TypeScript-only properties are marked below. All property keys are prefixed with $mcp_* so they never collide with PostHog autocapture, Web analytics, or other product events.

Events

The event enum reserves $mcp_resources_list, $mcp_resource_read, $mcp_prompts_list, and $mcp_prompt_get, but the server wrappers don't emit them yet. Resource and prompt payloads still pass through unchanged.

Core properties

Present on most mcp_* events.

How the harness label is resolved

The harness — the friendly client label on the dashboard's breakdown ("Claude Code", "Cursor", "ChatGPT", …) — is resolved at query time from exactly three of the properties above, checked in priority order:

1. $mcp_vendor_client — the vendor header (e.g. x-anthropic-client), the only signal separating Anthropic's pooled surfaces (Claude.ai, Cowork, Claude Design) from each other, since they all report the same clientInfo.name.
2. $mcp_client_user_agent — carries the build surface for Claude Code ((cli) vs (sdk-ts) vs (claude-vscode) vs (claude-desktop)), and acts as the generic fallback when no client name arrived.
3. $mcp_client_name — the clientInfo.name the client reported.

A call carrying none of the three shows as unattributed, and an unrecognized client collapses into "Other". If your breakdown reads mostly "Other", check that these properties are populated — on HTTP transports the SDK captures the headers automatically (TypeScript ≥ 0.11.0, Python ≥ 7.42.0); a custom dispatcher has to pass them itself, and stdio/in-memory transports carry no headers at all, so there the client name is the only signal.

Exception properties

Present on $exception events emitted alongside any failed tool call. The SDK reuses @posthog/core's error-tracking parser, so these are the same $exception_list properties every other PostHog SDK emits — they slot straight into Error tracking. Set enableExceptionAutocapture: false (default true) to stop a failed tool call from emitting the $exception sibling.

Plus $session_id, $mcp_conversation_id, $mcp_resource_name, $mcp_tool_name, $mcp_tool_description and $mcp_tool_category (tool calls only), $mcp_server_*, $mcp_client_* (including $mcp_client_user_agent and $mcp_vendor_client), $mcp_protocol_version, and the model properties when captured.

Person properties ($set)

Set on $identify events when identify() returns a user.

$set is sent on the wire to update the person profile, but isn't retained on the stored event. Query the resulting values as person properties rather than filtering events by $set.

Groups ($groups)

If identify() returns a groups field (a Record<string, string> of groupType → groupKey), the SDK stamps it onto every event as $groups. You never hand-write $groups yourself. See Identifying users.

Person profiles for anonymous sessions

Events for sessions with no resolved identity are sent with $process_person_profile: false, so anonymous MCP sessions don't each mint a person profile. Once identify() resolves an identity for the session, person processing stays on and the events attribute to that user.

Constants exported from the package

For product code that queries against the SDK's contract, the package exports:

• POSTHOG_MCP_ANALYTICS_SOURCE — the constant "posthog_mcp_analytics" (matches $mcp_source)
• PostHogMCPAnalyticsEvent — enum of canonical event names
• PostHogMCPAnalyticsProperty — enum of canonical property names

Use them instead of hard-coding strings so renames stay typesafe:

import { PostHogMCPAnalyticsEvent, PostHogMCPAnalyticsProperty } from "@posthog/mcp";

const event = PostHogMCPAnalyticsEvent.ToolCall; // "$mcp_tool_call"
const key = PostHogMCPAnalyticsProperty.ToolName; // "$mcp_tool_name"