Exploring MCP Sessions

Exploring MCP sessions

An MCP session is one agent run: the set of $mcp_tool_call events sharing a

$session_id, ordered by timestamp.

Listing sessions, reading a session's tool calls, and summarising its goal each

have a typed tool — reach for those first. Drop to HogQL only for the three

things the typed tools genuinely can't do (see

When to drop to SQL). The full $mcp_* property schema

and query recipes live in the shared reference:

models-mcp.md.

Tools

| Tool | Purpose |

| ------------------------------------------------ | ---------------------------------------------------------- |

| posthog:mcp-analytics-sessions-list | List sessions — one row per session, newest first |

| posthog:mcp-analytics-sessions-tool-calls | One session's tool calls, chronological |

| posthog:mcp-analytics-sessions-generate-intent | LLM summary of a session's goal (cached after first call) |

| posthog:execute-sql | Errored sessions, effective tool names, cross-session cuts |

The three mcp-analytics-* tools are gated behind the mcp-analytics flag and

run the same code as the sessions UI, so results match the screen. If they aren't

in your tool list, the project doesn't have the flag — fall back to

posthog:execute-sql, which is ungated.

The date-window trap — read this first

The two detail tools default to a 7-day lookback. A session you found in a

list that reaches further back will come back empty unless you pass its

session_start as date_from:

• posthog:mcp-analytics-sessions-tool-calls — date_from is an absolute ISO

timestamp; pass the session_start you got from

posthog:mcp-analytics-sessions-list.

• posthog:mcp-analytics-sessions-generate-intent — same date_from query

param, same reason.

Empty tool calls for a session that visibly exists is almost always this, not a

data problem. Carry session_start forward from the list row.

Workflow: list recent sessions

posthog:mcp-analytics-sessions-list
{ "date_from": "-7d", "order_by": "-session_start", "limit": 100 }

Each row: session_id, tool_calls, session_start, session_end,

tools_used, mcp_client_name, distinct_id (+ resolved person_email /

person_name), and intent (empty until generated). Response is

{ results, has_next } — page with limit / offset.

Three sharp edges:

• order_by takes column names, not response field names. Sort call volume

as tool_call_count (not tool_calls). duration_seconds sorts fine even

though it isn't returned. An unrecognised key silently falls back to

newest-first — so verify the order you got is the order you asked for. Valid:

session_id, session_start, session_end, duration_seconds,

tool_call_count, mcp_client_name, distinct_id; prefix - to descend.

• There is no error filter and no error count on a session row. "Which

sessions had errors?" is a SQL question — see below.

• distinct_id_count is always 0. The field is in the response but the

backend never populates it, so don't read it as "one distinct id per session"

— it says nothing. To count distinct ids in a session, use SQL.

search does a case-insensitive substring match across session_id,

distinct_id, mcp_client_name, and tools_used.

Workflow: read one session's tool calls

posthog:mcp-analytics-sessions-tool-calls
{ "id": "<session_id>", "date_from": "<session_start>", "limit": 500 }

Chronological tool_name, intent, timestamp, duration_ms, is_error,

error_message — read top to bottom to reconstruct the run. limit defaults to

500 (also the max), which is the whole page for almost every session; has_next

tells you if more remain.

Caveat: tool_name here is the raw $mcp_tool_name. Unlike the tool-quality

and tool-detail tools, this endpoint does not resolve the inner tool of a

single-exec wrapper call, so wrapper calls show the wrapper. When the inner tool

is what matters (comparing against a tool-quality ranking, tracing a specific

tool through a run), use the SQL recipe below instead. The same applies to

tools_used on the session list.

Workflow: summarise the agent's goal

posthog:mcp-analytics-sessions-generate-intent
{ "id": "<session_id>", "date_from": "<session_start>" }

Summarises the session's recorded $mcp_intent values via an LLM and persists

the result; later calls return the cached summary. Returns

{ session_id, intent }. A 503 means LLM summarisation isn't configured — fall

back to reading the raw $mcp_intent values from the tool-call list.

When to drop to SQL

Four cases, all via posthog:execute-sql, which — unlike the typed tools above —

is not gated behind the mcp-analytics flag.

1. The project doesn't have the mcp-analytics flag. The typed tools simply

won't be in your tool list. Everything below still works; this query is the

plain session listing:

SELECT
    $session_id AS session_id,
    min(timestamp) AS session_start,
    max(timestamp) AS session_end,
    dateDiff('second', min(timestamp), max(timestamp)) AS duration_seconds,
    count() AS tool_calls,
    countIf(toBool(properties.$mcp_is_error)) AS errors,
    any(properties.$mcp_client_name) AS client
FROM events
WHERE event = '$mcp_tool_call'
    AND $session_id != ''
    AND timestamp >= now() - INTERVAL 7 DAY
GROUP BY session_id
ORDER BY session_start DESC
LIMIT 50

2. Errored sessions. The session list can't filter or count errors — add

HAVING errors > 0 to the query above and order by errors DESC.

3. Effective tool names within a session — the coalesce the typed tool-calls

endpoint doesn't apply:

SELECT
    timestamp,
    coalesce(nullIf(toString(properties.$mcp_exec_tool_call_name), ''), toString(properties.$mcp_tool_name)) AS tool,
    toBool(properties.$mcp_is_error) AS is_error,
    toString(properties.$mcp_error_message) AS error_message,
    round(toFloat(properties.$mcp_duration_ms)) AS duration_ms
FROM events
WHERE event = '$mcp_tool_call'
    AND $session_id = '<session_id>'
ORDER BY timestamp ASC

4. Cross-session aggregation — "sessions per day", "sessions that used tool

X and then failed", custom breakdowns. Recipes in

models-mcp.md.

Note $session_id is a materialised events column — the same id as

$mcp_session_id. Reference it bare, never as properties.$session_id: the

properties. accessor renders null-wrapped in SELECT but as the raw column in

HAVING/ORDER, so a HAVING search would mismatch the GROUP BY key.

Constructing UI links

• Sessions list: https://app.posthog.com/project/<project_id>/mcp-analytics/sessions

Tips

• A session with many calls but no errors that ends abruptly often means the

agent gave up — check whether the last call returned a large or empty result

• $mcp_intent is only present when the client supplied it; absence is common,

so generate-intent is the more reliable goal signal

• To go from a failing tool (see

exploring-mcp-tool-quality) to the

sessions that hit it, search the session list by tool name — remembering

tools_used holds raw names, so search the registered name, not the inner one

Related skills

• exploring-mcp-tool-usage — the front

door: routes a broad "how is my MCP doing?" question to the right tool

• exploring-mcp-tool-quality — error

rates and latency across all tools

• exploring-mcp-intent-clusters —

group goals across many sessions