Models MCP

Governed metric first

For an MCP failure-rate headline, call posthog:metric-list before the typed tools or SQL recipes below and look for mcp_tool_call_fail_pct. Run an approved, non-drifted match with posthog:data-catalog-metric-run and report it as the canonical headline. Use the recipes below only for a requested tool, harness, or time breakdown after that run, and label the breakdown noncanonical. If no governed metric matches, state that the catalog has no match and label the derived rate noncanonical.

Query the canonical $-prefixed event name. Servers instrumented with the @posthog/mcp SDK emit only $mcp_tool_call / $mcp_initialize; PostHog’s own hosted server additionally dual-emits legacy un-prefixed mcp_tool_call / mcp_initialize aliases through a transition shim. Match the canonical name only — an event IN ('mcp_tool_call', '$mcp_tool_call') would double-count PostHog’s own server.

For a single tool, prefer the typed tools. Each takes a toolName plus a dateRange, runs the same query runner the tool-detail UI uses, and is gated behind the mcp-analytics flag, so results match the UI exactly and you don’t re-derive the SQL below. toolName is the effective name (resolved server-side — the inner tool of a single-exec wrapper call) for all of them, including posthog:query-mcp-tool-failures:

And posthog:query-mcp-harness-breakdown for the cross-tool harness cut (see below).

Sessions have typed tools too. A session is one agent run — the $mcp_tool_call events sharing a $session_id:

Three things to know before using them:

• 7-day lookback by default. posthog:mcp-analytics-sessions-tool-calls and posthog:mcp-analytics-sessions-generate-intent both scan 7 days back, so an older session returns empty unless you pass its session_start as date_from. Carry that value forward from the list row.
• They report the raw $mcp_tool_name, not the effective inner tool of a single-exec wrapper call — unlike the per-tool tools above.
• The session list has no error filter or error count. “Which sessions failed?” is a SQL question.

And two tools cover what SQL can’t express at all: posthog:mcp-analytics-intent-clusters-retrieve and posthog:mcp-analytics-intent-clusters-recompute (embedding-based intent clustering).

HogQL is the path for everything else — cross-tool rankings (the tool-quality matrix), custom breakdowns, errored-session filtering, effective tool names within a session — query them with execute-sql. It is also the fallback when the mcp-analytics flag is off: every typed tool above is gated behind it, execute-sql is not.

Key properties

Source says where the property comes from: SDK — set by @posthog/mcp (packages/mcp/src/extensions/constants.ts), present on any instrumented customer server; server — stamped only by PostHog’s own hosted MCP server (services/mcp), so it exists only for PostHog’s dogfood data; exec — only present when the server runs in single-exec mode (one exec dispatcher tool instead of one tool per name).

Server-stamped extras (PostHog’s own server only, not the SDK): $mcp_session_id (transport-level session handle — see “Three identifiers” below), $mcp_region (cloud region that handled the request, e.g. us/eu), $mcp_mode (cli for single-exec, tools for one-tool-per-name), $mcp_consumer (upstream surface, e.g. posthog-code/slack), and the non-$-prefixed legacy mcp_vendor_client (older variant of $mcp_vendor_client, the x-anthropic-client vendor header, e.g. ClaudeCode/ClaudeAI — still coalesced when resolving the harness for historical rows) and mcp_runtime (server runtime, e.g. hono), plus $mcp_auth_method (which credential the request authenticated with, from the bearer token’s prefix: oauth, personal_api_key, id_jag, none, unknown), plus $mcp_scope_preset (which kind of caller minted the token, worked out from its scope set: scout, research, implementation, sandbox for any other server-minted run, or user for a person’s own token; research and implementation need the scratchpad scopes and do not occur yet).

Refused requests are a separate event. A request the PostHog API rejects dies before any session, organization, or project is resolved, so it emits none of the events above — it emits $mcp_auth_failed instead, with $mcp_auth_failure_reason (insufficient_scope, inactive_oauth_token, invalid_api_key, unknown), $mcp_missing_scope when the API named a scope, and $mcp_auth_status (401/403). Only PostHog’s own server emits it, so it is absent for customer-instrumented servers.

It does not set $mcp_is_error/$mcp_error_status, which mean “a tool call failed against the PostHog API” — so an auth refusal never inflates tool error rates, and the status it did return lives in $mcp_auth_status instead.

Two consequences for queries: it has no $mcp_organization_id/$mcp_project_id, and its distinct_id is a hash of the bearer token rather than a user id, so count it with uniq(distinct_id) for affected credentials and join to other MCP events by client and time, never by person. A connector looping on authorization shows up here; before this event existed the same outage looked like an absence of traffic.

Three identifiers, not one. $session_id is the materialised column — GROUP BY/join on this one. $mcp_session_id is the transport-level handle the MCP SDK observed (MCP extra.sessionId or a framework session cookie); it rotates on process restart, reconnect, or framework boundary. $mcp_conversation_id is agent-echoed and stable across reconnects — reach for it when a “session” needs to survive a client reconnecting mid-task. In practice $session_id and $mcp_session_id carry the same value; $mcp_conversation_id is the more durable one when they diverge.

Effective tool name. New-SDK events wrap the real tool in a single-exec call, so to filter/group by the tool the agent actually invoked, use:

The advertised catalog: $mcp_tools_list. Each tools/list response emits a $mcp_tools_list event whose $mcp_listed_tool_names property holds the advertised tool names as a JSON array, with tool_count alongside. This is the denominator for “advertised but never called” analysis. Only about half of tool-call sessions carry a tools-list event, and sessions in exec-wrapper mode advertise just the wrapper (['exec', 'render-ui']), so condition per-tool discovery cuts on sessions where the catalog was actually observed. Extract the array with:

The coalesce(..., '[]') is required: the property accessor is Nullable, and JSONExtract of a Nullable into Array(String) is a ClickHouse type error.

Failures with detail. $mcp_tool_call carries $mcp_is_error plus a semantic $mcp_error_type and, for HTTP failures, $mcp_error_status (see the Source column above: $mcp_error_type is an SDK field that PostHog’s own server also stamps itself, while $mcp_error_status is stamped only by PostHog’s server, so a separately-instrumented server on the SDK alone won’t emit it). posthog:query-mcp-tool-failures groups errored tool calls by these two fields and returns each bucket’s raw error_type/error_status; pass those to posthog:query-mcp-tool-failure-occurrences for individual errored calls with the free-text $mcp_error_message (sanitized, truncated to 2048 chars — empty on events captured before PostHog’s server started emitting it). $mcp_response stays empty on PostHog’s hosted server. PostHog’s own tool calls also don’t emit $exception events — those only exist for separately-instrumented MCP servers.

Example queries

The SQL below is the fallback for cross-tool rankings and custom cuts. For a single tool’s numbers, call the typed tool from the table above instead of re-deriving these.

Error rate of one tool (noncanonical breakdown) (single-tool numbers are posthog:query-mcp-tool-stats; use this for a custom predicate after the governed headline):

Tool-quality matrix (noncanonical breakdown) (error rate + latency percentiles + reach, one row per tool) — this cross-tool ranking has no typed tool; once you’ve picked a tool, drill into it with posthog:query-mcp-tool-stats, posthog:query-mcp-tool-failures, or posthog:query-mcp-tool-daily-stats:

Daily activity (success/error split for a time series) — for one tool’s daily series prefer posthog:query-mcp-tool-daily-stats; this all-tools version is the custom cut:

Harness (client) bucketing

A “harness” is the friendly product label for the MCP client that made a call — “Claude Agent SDK”, “OpenAI Codex”, “Cursor”, … It is resolved server-side by MCPHarnessBreakdownQueryRunner, the single source of truth (products/mcp_analytics/backend/mcp_harness.py).

Prefer the typed tool. For “which harnesses use our MCP, and how reliably?”, call the posthog:query-mcp-harness-breakdown tool (gated behind the mcp-analytics flag). It returns calls / errors / error-rate / sessions per harness and accepts the same dateRange / properties / filterTestAccounts filters as the dashboard, so results match the UI exactly — no hand-written bucketing needed. It also accepts an optional toolName to scope the breakdown to one effective tool — but note that scoping also restricts the result to new-SDK events ($mcp_source = 'posthog_mcp_analytics'), so old-SDK and third-party calls for that tool are excluded and a harness can be undercounted. For a one-tool harness cut across all SDK sources, use execute-sql. Anything the typed tools don’t express drops to execute-sql below.

Use execute-sql for custom cuts the typed tool doesn’t cover (share-of-users, latency percentiles, per-tool, a trends breakdown). Resolution is two steps: resolve a normalized token from the strongest signal available, then bucket it. An event carries only raw signals, over exactly three properties — the x-anthropic-client header ($mcp_vendor_client, with the legacy mcp_vendor_client coalesced for historical rows) is the only thing separating Anthropic’s pooled surfaces (Cowork / Claude.ai / Claude Design); Claude Code’s build (cli / sdk / vscode / desktop) rides in the User-Agent ($mcp_client_user_agent, also the generic last fallback); and clientInfo.name arrives as $mcp_client_name. The SQL below mirrors harness_label_sql / HARNESS_TOKEN_SQL in mcp_harness.py; keep them in step until a materialized $mcp_harness property exists. (HogQL has no WITH <expr> AS alias, so the normalized name h is computed in a subquery, not a CTE.)

Share of users by harness (answers “what % of my users are on Claude Code”):

The multiIf above is the canonical bucket list. The denominator is total distinct users, so per-harness shares can sum past 100% (one user may use several harnesses). Swap the outer aggregate for other harness cuts — count() for call volume, quantile(0.95)(toFloat(properties.$mcp_duration_ms)) for latency. For query-trends, pass the inner multiIf(...) over the normalized client name as a HogQL breakdown to get the same buckets in a trends series.

Tool co-occurrence (which tool tends to run right before a given tool, within a session) — prefer posthog:query-mcp-tool-neighbors (neighborDirection: before/after); this SQL is the recipe behind it, for custom window logic:

Swap lagInFrame for leadInFrame to get the tool that runs after.