Event and property reference
Contents
This page is the wire-level contract for the @posthog/mcp SDK. Every event the SDK emits and every property name it uses is listed here. All property keys are prefixed with $mcp_* so they never collide with PostHog autocapture, Web analytics, or other product events.
Events
| Event name | When it fires | Notable extras |
|---|---|---|
$mcp_tool_call | Every tools/call request | $mcp_tool_name, $mcp_tool_description, $mcp_parameters, $mcp_response, $mcp_duration_ms, $mcp_is_error, optionally $mcp_intent/$mcp_intent_source |
$mcp_tools_list | Every tools/list response | $mcp_listed_tool_names (string[] of advertised tool names) |
$mcp_initialize | Every client/server handshake | $mcp_client_name, $mcp_client_version, $mcp_server_name, $mcp_server_version |
$mcp_resources_list | Every resources/list request | — |
$mcp_resource_read | Every resources/read request | $mcp_resource_name, $mcp_parameters, $mcp_response |
$mcp_prompts_list | Every prompts/list request | — |
$mcp_prompt_get | Every prompts/get request | $mcp_resource_name (the prompt name) |
| (your event name) | A call to analytics.capture({ event, properties }) | Sent under the verbatim event name you pass (a customer event, not $-prefixed), with your properties merged in. See Custom events. |
$mcp_missing_capability | The get_more_tools virtual tool is invoked (reportMissing: true) | The agent's reasoning is captured as $mcp_intent. See Tracking missing capabilities. |
$identify | identify() returns a new identity for a session | $set populated from the identity's properties |
$exception | Sibling event whenever a tool errors (unless enableExceptionAutocapture: false) | $exception_list, $exception_level, plus the same $mcp_* context as the main event |
Core properties
Present on most mcp_* events.
| Wire key | Type | Source |
|---|---|---|
$session_id | string | The MCP session id (ses_<32-hex>). Derived deterministically from the MCP protocol session id when available; otherwise minted and rotated after 30 minutes of inactivity. |
$mcp_source | string | Always "posthog_mcp_analytics". Use this to filter out non-MCP events when querying mixed projects. |
$mcp_resource_name | string | Tool, resource, or prompt name |
$mcp_tool_name | string | Same as $mcp_resource_name, but only on $mcp_tool_call |
$mcp_tool_description | string | The tool's description at the moment of the call. Cached from tools/list and (for McpServer) seeded from _registeredTools. Only on $mcp_tool_call and the paired $exception event. |
$mcp_listed_tool_names | string[] | Names of tools advertised in a tools/list response. Only on $mcp_tools_list. Useful for joining against $mcp_tool_call via $session_id to find tools advertised but never called. |
$mcp_duration_ms | number (ms) | Wall-clock duration of the tool call |
$mcp_is_error | boolean | True if the tool threw or returned isError: true |
$mcp_server_name | string | server._serverInfo.name |
$mcp_server_version | string | server._serverInfo.version |
$mcp_client_name | string | server.getClientVersion().name |
$mcp_client_version | string | server.getClientVersion().version |
$mcp_intent | string | From the context argument the agent passed, or from your intentFallback callback. See Capturing agent intent. |
$mcp_intent_source | "context_parameter" \| "inferred" | Tells you which path produced the intent. Absent when no intent was captured. |
$mcp_parameters | object | Sanitized request arguments. Excludes the SDK-injected context and conversation_id arguments. |
$mcp_response | object | Sanitized tool result |
$mcp_conversation_id | string | Present when enableConversationId is on. See Conversation IDs. |
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.
| Wire key | Source |
|---|---|
$exception_list | Array of structured exceptions. Each has type, value (the message), mechanism, and a stacktrace with parsed frames (filename, function, lineno, colno, in_app). An Error.cause chain appears as additional entries. |
$exception_level | Severity, always "error". |
Plus $session_id, $mcp_resource_name, $mcp_tool_name, $mcp_tool_description (tool calls only), $mcp_server_*, and $mcp_client_* for context.
Stack frames from a bundled/minified MCP server symbolicate the same way as any other PostHog backend SDK — upload your source maps with the PostHog CLI. Source-context lines and project-relative path rewriting (the optional Node frame modifiers) aren't applied by the MCP SDK yet.
Person properties ($set)
Set on $identify events when identify() returns a user.
| Key | Source |
|---|---|
| (any) | Keys of the identity's properties are written to $set (e.g. return properties: { name, email } to set a person's name and email) |
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 namesPostHogMCPAnalyticsProperty— enum of canonical property names
Use them instead of hard-coding strings so renames stay typesafe: