Explorer les sessions MCP

Une session MCP est une exécution d'agent : l'ensemble des événements $mcp_tool_call partageant un $session_id, ordonnés par timestamp.

Lister les sessions, lire les appels d'outils d'une session et résumer son objectif ont chacun un tool typé — commencez par ceux-là. Passez à HogQL uniquement pour les trois choses que les outils typés ne peuvent vraiment pas faire (voir Quand passer à SQL). Le schéma complet de la propriété $mcp_* et les recettes de requête se trouvent dans la référence partagée : models-mcp.md.

Tools

Les trois outils mcp-analytics-* sont derrière le drapeau mcp-analytics et exécutent le même code que l'UI des sessions, donc les résultats correspondent à l'écran. S'ils ne figurent pas dans votre liste d'outils, le projet n'a pas le drapeau — recourez à posthog:execute-sql, qui n'est pas bloqué.

Le piège de la fenêtre de dates — lisez ceci d'abord

Les deux outils de détail définissent par défaut un lookback de 7 jours. Une session que vous avez trouvée dans une liste remontant plus loin reviendra vide à moins de passer son session_start comme date_from :

• posthog:mcp-analytics-sessions-tool-calls — date_from est un timestamp ISO absolu ; passez le session_start obtenu de posthog:mcp-analytics-sessions-list.
• posthog:mcp-analytics-sessions-generate-intent — même paramètre de requête date_from, même raison.

Des appels d'outils vides pour une session qui existe visiblement est presque toujours cela, pas un problème de données. Portez session_start en avant depuis la ligne de la liste.

Flux : lister les sessions récentes

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

Chaque ligne : session_id, tool_calls, session_start, session_end, tools_used, mcp_client_name, distinct_id (+ person_email / person_name résolus), et intent (vide jusqu'à génération). La réponse est { results, has_next } — paginez avec limit / offset.

Trois pièges :

• order_by prend les noms de colonnes, pas les noms de champs de réponse. Triez le volume d'appels comme tool_call_count (pas tool_calls). duration_seconds trie correctement même s'il n'est pas renvoyé. Une clé non reconnue bascule silencieusement à plus récent en premier — vérifiez donc que l'ordre obtenu est celui demandé. Valides : session_id, session_start, session_end, duration_seconds, tool_call_count, mcp_client_name, distinct_id ; préfixez - pour descendre.
• Il n'y a pas de filtre d'erreur ni de comptage d'erreurs sur une ligne de session. « Quelles sessions ont eu des erreurs ? » est une question SQL — voir ci-dessous.
• distinct_id_count est toujours 0. Le champ est dans la réponse mais le backend ne le remplit jamais, donc ne le lisez pas comme « un distinct_id par session » — il ne dit rien. Pour compter les distinct_ids dans une session, utilisez SQL.

search fait une correspondance de sous-chaîne insensible à la casse sur session_id, distinct_id, mcp_client_name, et tools_used.

Flux : lire les appels d'outils d'une session

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 chronologiques — lisez du haut en bas pour reconstruire l'exécution. limit par défaut est 500 (aussi le maximum), ce qui est la page entière pour presque toute session ; has_next vous dit s'il en reste.

Caveat : tool_name ici est le $mcp_tool_name brut. Contrairement aux outils de qualité et de détail d'outils, ce point de terminaison ne résout pas l'outil interne d'un appel single-exec wrapper, donc les appels wrapper affichent le wrapper. Quand l'outil interne est ce qui importe (comparaison avec un classement de qualité d'outil, traçage d'un outil spécifique dans une exécution), utilisez plutôt la recette SQL ci-dessous. La même règle s'applique à tools_used sur la liste de sessions.

Flux : résumer l'objectif de l'agent

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

Résume les valeurs $mcp_intent enregistrées de la session via un LLM et persiste le résultat ; les appels ultérieurs retournent le résumé en cache. Retourne { session_id, intent }. Un 503 signifie que la résumérisation LLM n'est pas configurée — recourez à la lecture des valeurs $mcp_intent brutes de la liste d'appels d'outils.

Quand passer à SQL

Quatre cas, tous via posthog:execute-sql, qui — contrairement aux outils typés ci-dessus — est non bloqué par le drapeau mcp-analytics.

1. Le projet n'a pas le drapeau mcp-analytics. Les outils typés ne seront simplement pas dans votre liste d'outils. Tout ce qui suit fonctionne toujours ; cette requête est le listing de sessions brut :

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. Sessions en erreur. La liste de sessions ne peut pas filtrer ou compter les erreurs — ajoutez HAVING errors > 0 à la requête ci-dessus et triez par errors DESC.

3. Noms d'outils effectifs dans une session — la fusion que le point de terminaison des appels d'outils typés n'applique pas :

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. Agrégation entre sessions — « sessions par jour », « sessions qui ont utilisé l'outil X puis ont échoué », ventilations personnalisées. Recettes dans models-mcp.md.

Notez que $session_id est une colonne d'événements matérialisée — le même id que $mcp_session_id. Référencez-la nu, jamais comme properties.$session_id : l'accesseur properties. rend null-enrobé en SELECT mais comme la colonne brute en HAVING/ORDER, donc une recherche HAVING ne correspondrait pas à la clé GROUP BY.

Construction de liens UI

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

Conseils

• Une session avec beaucoup d'appels mais pas d'erreurs qui se termine abruptement signifie souvent que l'agent a abandonné — vérifiez si le dernier appel a retourné un grand résultat ou vide
• $mcp_intent n'est présent que quand le client l'a fourni ; son absence est courante, donc generate-intent est le signal d'objectif le plus fiable
• Pour aller d'un outil défaillant (voir exploring-mcp-tool-quality) aux sessions qui l'ont atteint, search la liste de sessions par nom d'outil — en vous souvenant que tools_used contient les noms bruts, donc recherchez le nom enregistré, pas l'interne

Skills connexes

• exploring-mcp-tool-usage — la porte d'entrée : achemine une large question « comment fonctionne mon MCP ? » vers le bon tool
• exploring-mcp-tool-quality — taux d'erreur et latence sur tous les outils
• exploring-mcp-intent-clusters — grouper les objectifs sur de nombreuses sessions