exploring-mcp-sessions

探索 MCP 会话

一个 MCP 会话就是一次 Agent 运行：一组共享同一个 $session_id、按 timestamp 排序的 $mcp_tool_call 事件。

列出会话、读取会话的工具调用以及总结会话目标，各自都有一个类型化工具——优先使用这些工具。只有在确实无法通过类型化工具完成以下三件事时，才改用 HogQL（参见何时改用 SQL）。完整的 $mcp_* 属性架构和查询示例见共享参考文档： models-mcp.md。

工具

工具	用途
posthog:mcp-analytics-sessions-list	列出会话——每个会话一行，按时间从新到旧排列
posthog:mcp-analytics-sessions-tool-calls	某个会话的工具调用，按时间顺序排列
posthog:mcp-analytics-sessions-generate-intent	总结会话目标的大模型（首次调用后会缓存）
posthog:execute-sql	查询出错的会话、有效工具名称和跨会话数据

这三个 mcp-analytics-* 工具运行的代码与会话界面相同，因此结果与界面显示一致。如果工具列表中没有这些工具，请改用 posthog:execute-sql。

日期窗口陷阱——请先阅读

两个详情工具默认回溯 7 天。如果列表中找到的会话时间更早，那么除非将它的 session_start 作为 date_from 传入，否则结果会为空：

• posthog:mcp-analytics-sessions-tool-calls——date_from 是绝对 ISO 时间戳；请传入从 posthog:mcp-analytics-sessions-list 获取的 session_start。
• posthog:mcp-analytics-sessions-generate-intent——同样使用 date_from 查询参数，原因也相同。

对于一个显然存在的会话，如果工具调用结果为空，几乎总是这个原因，而非数据问题。请从列表行中获取 session_start 并继续传递。

工作流：列出最近的会话

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

每行包含：session_id、tool_calls、session_start、session_end、tools_used、mcp_client_name、distinct_id（以及解析出的 person_email / person_name）和 intent（生成前为空）。响应为 { results, has_next }——使用 limit / offset 翻页。

需要注意的三个地方：

• order_by 接受的是列名，而不是响应字段名。 按调用次数排序时应使用 tool_call_count（而非 tool_calls）。duration_seconds 即使不会返回，也可以用于排序。无法识别的键会静默地退回按时间从新到旧排列——因此请核实实际顺序是否与请求一致。有效值：session_id、session_start、session_end、duration_seconds、tool_call_count、mcp_client_name、distinct_id；加上 - 前缀表示降序。
• 没有错误筛选条件，会话行中也没有错误计数。“哪些会话出错了？”需要通过 SQL 查询——见下文。
• distinct_id_count 始终为 0。 响应中包含此字段，但后端从不填充它，所以不要将它理解为“每个会话对应一个 distinct id”——它不表示任何信息。要统计会话中的 distinct id，请使用 SQL。

search 会对 session_id、distinct_id、mcp_client_name 和 tools_used 执行不区分大小写的子串匹配。

工作流：读取单个会话的工具调用

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

按时间顺序排列的 tool_name、intent、timestamp、duration_ms、is_error、 error_message — 从上到下阅读即可还原运行过程。limit 默认为 500（也是上限），几乎所有会话的整页内容都在其中；has_next 会告知你是否还有更多内容。

注意：这里的 tool_name 是原始的 $mcp_tool_name。 与工具质量和工具详情 工具不同，此端点不会解析单次执行包装调用中的内部工具，因此包装调用会显示包装器。 当内部工具才是关注重点时（例如与工具质量排名比较，或跟踪某个特定工具的运行情况）， 请改用下方的 SQL 方案。会话列表中的 tools_used 也是如此。

工作流：总结 Agent 的目标

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

通过 LLM 总结会话中记录的 $mcp_intent 值并保存结果；后续调用会返回缓存的摘要。 返回 { session_id, intent }。如果返回 503，表示未配置 LLM 摘要功能 — 请改为 从工具调用列表中读取原始 $mcp_intent 值。

何时改用 SQL

以下四种情况均通过 posthog:execute-sql 处理。

1. 工具列表中没有类型化工具。 以下内容仍然适用； 此查询是普通的会话列表：

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. 出错的会话。 会话列表无法筛选或统计错误 — 在上方的查询中添加 HAVING errors > 0，并按 errors DESC 排序。

3. 会话中的有效工具名称 — 类型化工具调用端点不会应用的合并逻辑：

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. 跨会话聚合 — “每天的会话数”、“使用工具 X 后失败的会话”、自定义细分。 相关方案见 models-mcp.md。

请注意，$session_id 是一个物化事件列 — 与 $mcp_session_id 是同一个 ID。 请直接引用它，不要写成 properties.$session_id：properties. 访问器在 SELECT 中会 显示为 null 包装值，但在 HAVING/ORDER 中会显示为原始列，因此 HAVING 搜索会与 GROUP BY 键不匹配。

构建 UI 链接

• 会话列表：https://app.posthog.com/project/<project_id>/mcp-analytics/sessions

提示

• 一个会话包含许多调用、没有错误，却突然结束，这通常意味着 Agent 放弃了 — 检查 最后一次调用是否返回了大量或空结果
• 只有客户端提供 $mcp_intent 时才会有此值；缺失很常见，因此生成的 intent 是更 可靠的目标信号
• 若要从一个失败的工具（参见 exploring-mcp-tool-quality）找到调用过它的 会话，请按工具名称对会话列表执行 search — 记住，tools_used 保存的是原始名称， 因此应搜索注册名称，而不是内部名称

相关技能

• exploring-mcp-tool-usage — 入口：将宽泛的“我的 MCP 运行得怎么样？”问题导向合适的工具
• exploring-mcp-tool-quality — 所有工具的错误率 和延迟
• exploring-mcp-intent-clusters — 对多个会话中的目标进行分组