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 TypeScript, Python, and Ruby SDKs capture resource events. The Go SDK doesn't yet. The Go SDK sends neither $mcp_tools_list nor $mcp_initialize. Only the Ruby SDK emits $mcp_prompts_list and $mcp_prompt_get. Prompt payloads pass through unchanged.

Core properties

Present on most mcp_* events.

Session resolution

The SDK checks these sources in order and uses the first match:

1. An accepted agent-provided conversation_id, when conversation IDs are enabled.
2. A session ID carried by the request on 2025-11-25.
3. The server instance's session ID, which rotates after 30 minutes of inactivity.

In Go, source 3 applies only to sessionless one-client connections (stdio and in-memory). A stateless HTTP request with neither a handle nor a session header gets a new ID per request.

2026-07-28 has no protocol sessions, so only sources 1 and 3 apply. Conversation handles support correlation across reconnects, restarts, and server instances. The SDK derives the session ID deterministically, without a salt. Separate pods therefore derive the same session ID from the same handle.

How the harness label is resolved

A harness is the client label on the dashboard, such as "Claude Code", "Cursor", or "ChatGPT". PostHog derives it at query time from these properties, 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 – identifies the Claude Code interface: (cli), (sdk-ts), (claude-vscode), or (claude-desktop). It is also the fallback when no client name is available.
3. $mcp_client_name – the clientInfo.name the client reported.

Requests through a vendor's gateway identify the gateway, not necessarily the original client. Claude.ai web, desktop, and mobile connectors use the same Anthropic fetcher. They share the Claude-User user agent and vendor header value. These requests resolve to "Claude.ai" because the request does not distinguish the three clients.

A call without these properties is unattributed. An unrecognized client appears as "Other".

If you see mostly "Other", check whether these properties contain values. On HTTP transports, the SDK captures headers automatically. Custom dispatchers must pass them explicitly, as in the Python example. In Go, set ClientUserAgent and VendorClient on ToolCall. Stdio and in-memory transports have no headers, so only the client name is available.

Model capture

MCP has no standard field for the calling model. The SDK reads recognized client metadata first, then the agent's self-reported llm_model argument, which the SDK adds to compatible tool schemas. Events include $mcp_llm_model and $mcp_llm_model_source ("client_metadata" or "self_reported").

The recognized metadata field is Codex's params._meta["x-codex-turn-metadata"].model. The Go SDK reads io.modelcontextprotocol/aiInvocation first, then x-codex-turn-metadata. Other clients can pass the llm_model argument. Some clients report an exact model, others a model family. Missing, blank, and unknown values are omitted, and reasoning effort isn't captured.

Both sources are unverified client input. Use them to compare tool quality, latency, and errors by model, not for billing or security decisions. To turn model capture off, see the configuration on your language's installation page.

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.

In Go, the $exception has type, value, and mechanism but no stack trace, and no user agent, vendor client, or model properties.

Person properties ($set)

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

The SDK sends $set to update the person profile. PostHog does not retain $set on the stored event. Query the resulting values as person properties rather than filtering events by $set.

In Go, $set rides on $mcp_tool_call, $mcp_unknown_tool, and $mcp_input_required, not on a $identify event. It needs an explicit DistinctID. The SDK drops it without one, or if the event is too large.

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 do not each create 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"