PostHog MCP Analytics 探索指南用exploring-mcp-tool-usage技能从问题路由到 MCP 工具调用数据【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog导读任何用posthog/mcpSDK 埋点的 MCP 服务器都会在 Agent 每次调用工具时发出一个$mcp_tool_call事件PostHog 的 MCP Analytics 能力仪表盘、工具质量、工具详情、会话、意图聚类全部建立在这单一事件之上。本文围绕 PostHog 仓库中exploring-mcp-tool-usage这个入口技能展开当用户只想知道我的 MCP 用得怎么样却还没选定具体问题时如何先调用治理指标得到权威失败率再通过建议问题菜单路由到对应的 typed tool或专用技能以及何时该降级手写 HogQL。读完你就能掌握一套从宽泛提问到单工具深度下钻的完整探索路径。一次 Agent 调用一个$mcp_tool_call事件先建立数据模型MCP 服务器只要用 PostHog 的 MCP analytics SDK 埋点Agent 每次调用工具都会在共享的events表上产生一个$mcp_tool_call事件。没有专门的 ClickHouse 表——所有字段都以$mcp_*前缀的属性挂在events上MCP Analytics 仪表盘、tool-quality、tool-detail 等屏幕上的每个指标都是对这个事件做聚合得到的且都可以用 HogQL 复现。仓库中products/mcp_analytics/backend/constants.py明确了事件名约束# Key on this canonical event only — also matching the legacy mcp_tool_call alias # (frozen, pre-2026-06-16 history) would double-count every call. MCP_TOOL_CALL_EVENT $mcp_tool_call注意这里的细节PostHog 自托管的 MCP 服务器在过渡期会双发无前缀的mcp_tool_call别名事件因此查询时只能匹配规范的$mcp_tool_call写event IN (mcp_tool_call, $mcp_tool_call)会对 PostHog 自己的服务器重复计数。这是理解本文所有工具与 SQL 配方的前提。本技能的角色MCP 工具使用探索的大门exploring-mcp-tool-usage位于 products/mcp_analytics/skills/exploring-mcp-tool-usage/SKILL.md定位是front door用户知道想查看 MCP 工具使用情况但还没选定具体问题。它的做法是先向用户展示一份建议问题菜单每个问题背后都有一个对应的查询工具然后把用户选中的问题路由到该工具——或路由到更聚焦的专用技能如 tool-quality、sessions、intent-clusters。它的触发场景包括我的 MCP 怎么样了、我该看什么、探索我的工具调用、谁在用我的 MCP 工具、Agent 们用 MCP 在做什么或用户贴了一个 MCP Analytics 的 URL 却没有带具体问题。权威指标优先Governed metric first技能的第一条纪律是当问题涉及 MCP 失败率或百分比时先走治理指标再碰 typed tool 或 SQL 配方。先调用posthog:metric-list在结果中查找mcp_tool_call_fail_pct若存在一个已批准approved且未漂移non-drifted的匹配项用posthog:data-catalog-metric-run运行它把结果作为权威 headline汇报若用户还追问是哪个工具/哪个 harness 导致了失败先回答 headline再用下面的 per-tool 工作流做**非权威noncanonical**分解若治理指标目录里没有匹配项明确说明catalog 无匹配并把自行推导的失败率标注为非权威。这条规则的用意是MCP 失败率的官方数字必须来自被治理的指标定义任何临时 SQL 算出的百分比只能作为补充性下钻不能冒充权威口径。建议问题菜单12 个问题路由到正确工具当用户不确定该问什么时直接抛出下面这份菜单原技能核心内容完整保留问用户…由谁来回答哪些工具失败最多或最慢exploring-mcp-tool-quality先对所有工具排序再用posthog:query-mcp-tool-stats下钻工具 X 整体表现如何posthog:query-mcp-tool-stats— 调用数、错误数、p50/p95、用户、会话、意图工具 X 的趋势如何posthog:query-mcp-tool-daily-stats— 逐日序列工具 X 为什么失败posthog:query-mcp-tool-failures— 按 harness 分组的 top 错误信息谁最常用工具 Xposthog:query-mcp-tool-top-users— top 调用者含 person 邮箱/姓名工具 X 前后通常被什么调用posthog:query-mcp-tool-neighborsneighborDirection: before/afterAgent 用工具 X 想做什么posthog:query-mcp-tool-sample-intents— 最近的 Agent 意图工具 X 注册时带什么描述posthog:query-mcp-tool-descriptions— 观察到的不同描述哪些 harness 在用我的 MCP可靠性如何posthog:query-mcp-harness-breakdown— 每个客户端的调用/错误/会话跨所有工具Agent 们在做什么exploring-mcp-intent-clusters— 语义目标聚类谁在连接活跃度如何posthog:mcp-analytics-sessions-list— 每个会话一行含客户端与 person这个会话具体做了什么exploring-mcp-sessions— 单次 Agent 运行的工具序列关键前提所有 per-tool 工具都受mcp-analyticsflag 门控技能文档强调上述每个 per-tool 工具都被mcp-analytics特性开关门控——项目的 flag 未开启时这些工具根本不会出现在工具列表里接受toolName服务端解析后的有效工具名即 Agent 实际调用的那个名字加dateRange运行与tool-detail UI 完全相同的查询 runner因此结果与界面一致你无需手写 HogQL。这个门控在源码里有明确落点。products/mcp_analytics/backend/hogql_queries/base.py定义了 flag 常量与访问校验MCP_ANALYTICS_FEATURE_FLAG mcp-analytics def validate_mcp_analytics_access(team, user): ... enabled posthoganalytics.feature_enabled( MCP_ANALYTICS_FEATURE_FLAG, ... ) if not enabled: raise UserAccessControlError(mcp_analytics, viewer) return UserAccessControl(useruser, teamteam).assert_access_level_for_resource(mcp_analytics, viewer)也就是说这些查询 runner 与产品的 DRF 端点共用同一个 flag RBAC 资源检查/query/通用端点无法绕过。工具级定义enabled、scopes、annotations、feature_flag: mcp-analytics则集中在 products/mcp_analytics/mcp/tools.yaml例如query-mcp-tool-stats: schema_ref: MCPToolStatsQuery enabled: true scopes: - query:read - mcp_analytics:read annotations: readOnly: true destructive: false idempotent: true feature_flag: mcp-analytics找到正确的toolName有效工具名effective tool nameper-tool 工具都需要一个toolName取值规则用户直接点名了某个工具 → 直接传它用户问的是宽泛的哪个工具…… → 先跑exploring-mcp-tool-quality对所有工具排序选出最突出的那个再用 per-tool 工具下钻。关键概念是effective tool name有效工具名新版 SDK 的事件把真实工具包在单次 exec 调用single-exec wrapper里如果直接按原始$mcp_tool_name分组所有调用都会塌缩到 wrapper 名下。因此要传服务端解析出的内层真实工具名——这正是 tool-quality 排序返回的字符串。源码层面这个表达式在 products/mcp_analytics/backend/hogql_queries/base.py 中定义为共享常量EFFECTIVE_TOOL_SQLEFFECTIVE_TOOL_SQL ( coalesce(nullIf(toString(properties.$mcp_exec_tool_call_name), ), toString(properties.$mcp_tool_name)) )它被所有按工具收敛的 runner 复用见tool_scope_exprs且工具名以ast.Constant绑定、绝不字符串插值。同样的口径也给出了 effective descriptionEFFECTIVE_DESCRIPTION_SQL ( coalesce(nullIf(toString(properties.$mcp_exec_tool_call_description), ), toString(properties.$mcp_tool_description)) )一处值得注意的口径差异本技能 SKILL.md 中提到一个例外posthog:query-mcp-tool-failures匹配$exception事件、因此要传原始注册名$mcp_tool_name。但从当前仓库源码看这一说法已经过时products/mcp_analytics/mcp/tools.yaml 中query-mcp-tool-failures的描述明确写着 Failures are the errored$mcp_tool_callevents ($mcp_is_error true)… Pass toolName (effective tool name, resolved server-side, matching the other tool-detail tools)products/mcp_analytics/backend/hogql_queries/tool_tables.py中MCPToolFailuresQueryRunner的注释也印证了迁移Previously this read$exceptionevents, which dont carry MCP tool markers, so the table was always empty while the error rate showed failures——现在它与其他工具详情表共享同一数据源errored$mcp_tool_call effective tool name两者不可能互相矛盾。因此实际使用时query-mcp-tool-failures与其余 per-tool 工具一样传 effective tool name 即可以 models-mcp.md 和 tools.yaml 为准。如何调用一个 per-tool 工具以某工具的 headline 数字为例技能原文示例posthog:query-mcp-tool-stats { toolName: tool, dateRange: { date_from: -7d } }拿到结果后根据菜单自然跟进若posthog:query-mcp-tool-stats显示错误率偏高 → 接posthog:query-mcp-tool-failures若显示覆盖面广 → 接posthog:query-mcp-tool-top-users或posthog:query-mcp-tool-neighbors。这些工具在源码中的 runner 集中在 products/mcp_analytics/backend/hogql_queries/tool_tables.py每个 runner 都先构建单工具 时间窗的 WHERE_tool_call_where再拼出各自的聚合形状工具对应 QueryRunner核心聚合口径源码依据query-mcp-tool-statsMCPToolStatsQueryRunnercount()调用数、countIf(toBool($mcp_is_error))错误数、quantile(0.5)/(0.95)(toFloat($mcp_duration_ms))p50/p95、uniq(distinct_id)用户数、uniq(conversation_id)会话数、带 intent 的调用数query-mcp-tool-daily-statsMCPToolDailyStatsQueryRunnerdateTrunc(interval, timestamp)分桶逐日/逐小时调用、错误、p50/p95、用户、会话query-mcp-tool-failuresMCPToolFailuresQueryRunner按$mcp_error_type HTTP$mcp_error_status分组unknown兜底输出组成 type (HTTP status) 标签与 harness 列表query-mcp-tool-failure-occurrencesMCPToolFailureOccurrencesQueryRunner单个失败桶内的逐条错误调用最多 50 条时间、distinct_id、会话、harness、intent、$mcp_error_message截断到 2048 字符query-mcp-tool-top-usersMCPToolTopUsersQueryRunner按distinct_id分组调用数、错误率、harness 标签、最后活跃时间以及 person 邮箱/姓名只返回渲染所需字段不泄整个 person blobquery-mcp-tool-neighborsMCPToolNeighborsQueryRunnerlagInFrame/leadInFrame窗口函数按会话取前/后一个工具统计共现次数query-mcp-tool-sample-intentsMCPToolSampleIntentsQueryRunner最近 5 条非空$mcp_intent附$mcp_intent_source与 harnessquery-mcp-tool-descriptionsMCPToolDescriptionsQueryRunner去重后的 effective description 列表notEmpty过滤按最后出现时间排序一个值得说明的实现细节错误类型/状态是事件自带的、无界字符串源码在分组前先用substring(..., 1, 200)/substring(..., 1, 20)截断_RAW_ERROR_TYPE/_RAW_ERROR_STATUS防止恶意事件用海量唯一值撑爆分组键错误消息同理截断到 2048 字符_ERROR_MESSAGE。toolName全程以常量绑定杜绝注入。harness 标签的解析同样在服务端完成——products/mcp_analytics/backend/mcp_harness.pyHARNESS_TOKEN_SQL/harness_label_sql是唯一权威前端只负责把解析出的标签映射成 Logo。如果手写 SQL 与界面不一致说明你的分桶逻辑偏离了mcp_harness.py此时应优先用 typed toolposthog:query-mcp-harness-breakdown而不是继续手工推导。何时降级到 SQL技能给出了一条清晰的边界避免在已有 typed tool 的场景下手写 SQL已被 typed tool 覆盖——不要手写 SQL问题工具单个工具的 headline 数字posthog:query-mcp-tool-stats单个工具的逐日趋势posthog:query-mcp-tool-daily-stats单个工具的 top 错误posthog:query-mcp-tool-failures单个工具的 top 调用者posthog:query-mcp-tool-top-users某个工具前后调用的工具posthog:query-mcp-tool-neighbors单个工具最近的 Agent 意图posthog:query-mcp-tool-sample-intents单个工具的注册描述posthog:query-mcp-tool-descriptions按客户端 harness 拆分使用量posthog:query-mcp-harness-breakdown列出会话posthog:mcp-analytics-sessions-list单个会话的工具调用posthog:mcp-analytics-sessions-tool-calls未被覆盖——使用posthog:execute-sql跨工具排名tool-quality 矩阵如哪个工具错误最多错误会话过滤会话列表没有错误过滤器或错误计数会话内的有效工具名posthog:mcp-analytics-sessions-tool-calls返回的是原始$mcp_tool_name不是 wrapper 调用的内层工具任意自定义分解。posthog:execute-sql同时也是mcp-analyticsflag 关闭时的兜底路径——上表所有工具都被该 flag 门控而execute-sql不受门控。此时直接查询$mcp_tool_call即可完整的$mcp_*属性 schema 与现成查询配方tool-quality 矩阵、harness 分桶、工具共现等都在共享参考文档 products/posthog_ai/skills/querying-posthog-data/references/models-mcp.md 中查询前建议先读它不要重新推导。作为示例跨工具的哪个工具错误率最高非权威分解在exploring-mcp-tool-quality技能中给出了完整配方核心是 effective tool name 小样本防护posthog:execute-sql SELECT coalesce(nullIf(toString(properties.$mcp_exec_tool_call_name), ), toString(properties.$mcp_tool_name)) AS tool, count() AS total_calls, countIf(toBool(properties.$mcp_is_error)) AS errors, round(countIf(toBool(properties.$mcp_is_error)) * 100.0 / count(), 1) AS error_rate_pct FROM events WHERE event $mcp_tool_call AND coalesce(nullIf(toString(properties.$mcp_exec_tool_call_name), ), toString(properties.$mcp_tool_name)) ! AND timestamp now() - INTERVAL 30 DAY GROUP BY tool HAVING total_calls 20 ORDER BY error_rate_pct DESC, total_calls DESC LIMIT 20汇报时同时给出错误率与调用量3 次调用 100% 错误率通常不是真相50,000 次调用 12% 才是。技能还提醒两条铁律$mcp_is_error永远用toBool(...)读取、$mcp_duration_ms用toFloat(...)强转这两个属性在事件里是字符串并且永远设置时间范围否则这些查询会全表扫描events。相关技能从大门走向纵深exploring-mcp-tool-usage是路由入口选好方向后由三个专用技能接力exploring-mcp-tool-quality — 按错误率/延迟/覆盖面给所有工具排序再下钻到单个工具exploring-mcp-sessions — 单次 Agent 运行及其工具调用序列注意其两个详情工具默认 7 天回看窗口老会话要携带session_start作为date_fromexploring-mcp-intent-clusters — 按语义相似度聚类的 Agent 目标回答Agent 们想做什么、是否如愿。它们共同构成一套完整的分层先治理指标定权威口径再按问题路由到 typed tool最后在 typed tool 覆盖不到的地方用 HogQL 兜底。掌握了这条链路任何我的 MCP 用得怎么样的宽泛提问都能一步步收敛为对单个工具、单个 harness、甚至单次会话的确凿数据。【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考