exploring-mcp-sessions

MCP セッションの調査

MCP セッションは1回のエージェント実行です。$session_id を共有する一連の $mcp_tool_call イベントを、timestamp 順に並べたものです。

セッションの一覧表示、セッションのツール呼び出しの読み取り、目標の要約には、それぞれ型付きツールがあります。まずはこれらを使ってください。HogQL を使うのは、型付きツールでは実行できない3つのことに限ります（SQL に切り替えるタイミングを参照）。$mcp_* プロパティのスキーマ全体とクエリのレシピは、共通リファレンスにあります。 models-mcp.md。

ツール

ツール	目的
posthog:mcp-analytics-sessions-list	セッションを一覧表示します。セッションごとに1行で、新しい順です
posthog:mcp-analytics-sessions-tool-calls	1つのセッションのツール呼び出しを時系列順に表示します
posthog:mcp-analytics-sessions-generate-intent	セッションの目標を LLM で要約します（初回呼び出し後はキャッシュされます）
posthog:execute-sql	エラーが発生したセッション、有効なツール名、セッション横断の分析

3つの mcp-analytics-* ツールはセッション UI と同じコードを実行するため、結果は画面の表示と一致します。ツール一覧にこれらのツールがない場合は、posthog:execute-sql に切り替えてください。

日付範囲の落とし穴 — まずお読みください

2つの詳細ツールのデフォルトの参照期間は過去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 でページ分割してください。

注意点は3つあります。

• order_by に指定するのは、レスポンスフィールド名ではなく列名です。 呼び出し件数で並べ替えるには、tool_calls ではなく tool_call_count を指定します。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 が1つある」という意味として読み取らないでください。このフィールドからは何もわかりません。セッション内の distinct ID を数えるには、SQL を使ってください。

search は、session_id、distinct_id、mcp_client_name、tools_used を対象に、大文字と小文字を区別せず部分一致で検索します。

ワークフロー：1 つのセッションのツール呼び出しを読む

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 にも同じことが当てはまります。

ワークフロー：エージェントの目標を要約する

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

LLM を使用して、セッションに記録された $mcp_intent の値を要約し、その結果を保存します。 以降の呼び出しではキャッシュされた要約が返されます。{ session_id, intent } を 返します。503 が返された場合、LLM による要約が設定されていません。代わりに、ツール呼び出し一覧から 生の $mcp_intent の値を確認してください。

SQL を使う場合

4 つの場合があり、すべて 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. セッション内の実効ツール名 — 型付きのツール呼び出しエンドポイントでは coalesce が適用されません。

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

ヒント

• 多数の呼び出しがあり、エラーがないままセッションが突然終了している場合、エージェントが諦めた可能性があります。最後の呼び出しが大きな結果または空の結果を返したか確認してください。
• $mcp_intent はクライアントが値を指定した場合にのみ存在します。存在しないことはよくあるため、目標を示すシグナルとしては generate-intent のほうが信頼できます。
• 失敗したツール（exploring-mcp-tool-quality を参照）から、そのツールを実行したセッションを探すには、セッション一覧をツール名で search してください。tools_used には生の名前が含まれるため、内部の名前ではなく登録名で検索する点に注意してください。

関連スキル

• exploring-mcp-tool-usage — 入口となるスキルです。「自分の MCP の状況は？」といった幅広い質問を適切なツールへ案内します。
• exploring-mcp-tool-quality — すべてのツールにわたるエラー率とレイテンシーを確認します。
• exploring-mcp-intent-clusters — 複数のセッションにまたがる目標をグループ化します。