: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
from datetime import datetime
from typing import Any, cast
from django.db.models import QuerySet
from django.utils.dateparse import parse_datetime
from drf_spectacular.types import OpenApiTypes
from drf_spectacular.utils import OpenApiParameter, OpenApiResponse, extend_schema
from rest_framework import status, viewsets
from rest_framework.decorators import action
from rest_framework.request import Request
from rest_framework.response import Response
from rest_framework.serializers import BaseSerializer
from posthog.api.mixins import ValidatedRequest, validated_request
from posthog.api.pagination import BoundedLimitOffsetPagination, page_link, previous_offset
from posthog.api.routing import TeamAndOrgViewSetMixin
from posthog.event_usage import report_user_action
from posthog.models.user import User
from posthog.permissions import PostHogFeatureFlagPermission
from products.mcp_analytics.backend import logic
from products.mcp_analytics.backend.facade import api, contracts, enums
from products.mcp_analytics.backend.models import MCPAnalyticsSubmission, MCPCustomHarness
from .serializers import (
MCP_SESSION_LIST_DEFAULT_LIMIT,
MCP_SESSION_LIST_MAX_LIMIT,
MCPActivityOverviewQuerySerializer,
MCPActivityOverviewSerializer,
MCPAnalyticsSubmissionSerializer,
MCPCustomHarnessSerializer,
MCPFeedbackCreateSerializer,
MCPIntentClusterSnapshotSerializer,
MCPIntentDigestSerializer,
MCPMissingCapabilityCreateSerializer,
MCPSessionIntentSerializer,
MCPSessionListQuerySerializer,
MCPSessionSerializer,
MCPSessionToolCallsQuerySerializer,
MCPToolCallSerializer,
)
def _parse_detail_date_from(raw: str | None) -> datetime | None:
"""Parse the optional session-start bound for detail queries (an absolute ISO timestamp).
Returns None on missing or unparseable input so the logic layer falls back to its default
lookback rather than 400-ing — the bound is only a scan-pruning hint, never a filter.
"""
return parse_datetime(raw) if raw else None
class MCPAnalyticsPagination(BoundedLimitOffsetPagination):
default_limit = 100
max_limit = 500
class MCPSessionPagination(BoundedLimitOffsetPagination):
"""Returns ``{next, previous, results, has_next}`` without a ``count``. The list is an
on-the-fly ClickHouse aggregate with no cheap total, so ``has_next`` comes from the
logic layer over-fetching one row rather than a count query.
"""
default_limit = MCP_SESSION_LIST_DEFAULT_LIMIT
max_limit = MCP_SESSION_LIST_MAX_LIMIT
def get_page_response(self, request: Request, data: Any, *, offset: int, limit: int, has_next: bool) -> Response:
return Response(
{
"next": page_link(request, self.offset_query_param, offset + limit) if has_next else None,
"previous": page_link(request, self.offset_query_param, previous_offset(offset, limit)),
"results": data,
"has_next": has_next,
}
)
def get_paginated_response_schema(self, schema: dict) -> dict:
return {
"type": "object",
"required": ["next", "previous", "results", "has_next"],
"properties": {
"next": {
"type": "string",
"format": "uri",
"nullable": True,
"description": "URL of the next page, or null on the last page.",
},
"previous": {
"type": "string",
"format": "uri",
"nullable": True,
"description": "URL of the previous page, or null on the first page.",
},
"results": schema,
"has_next": {
"type": "boolean",
"description": "Whether more results exist beyond this page; the client fetches the next page with a larger offset.",
},
},
}
class BaseMCPAnalyticsSubmissionViewSet(TeamAndOrgViewSetMixin, viewsets.GenericViewSet):
serializer_class = MCPAnalyticsSubmissionSerializer
# create -> write, list -> read map to the default scope actions.
scope_object = "mcp_analytics"
pagination_class = MCPAnalyticsPagination
user_action_name: str = ""
def _submission_context(self, validated_data: dict[str, Any]) -> contracts.SubmissionContext:
return contracts.SubmissionContext(
attempted_tool=validated_data.get("attempted_tool", ""),
mcp_client_name=validated_data.get("mcp_client_name", ""),
mcp_client_version=validated_data.get("mcp_client_version", ""),
mcp_protocol_version=validated_data.get("mcp_protocol_version", ""),
mcp_transport=validated_data.get("mcp_transport", ""),
mcp_session_id=validated_data.get("mcp_session_id", ""),
mcp_trace_id=validated_data.get("mcp_trace_id", ""),
)
def _report_submission_created(self, request: Request, submission: contracts.Submission) -> None:
report_user_action(
cast(User, request.user),
self.user_action_name,
self._submission_event_properties(submission),
team=self.team,
request=request,
)
def _submission_event_properties(self, submission: contracts.Submission) -> dict[str, Any]:
return {
"submission_id": str(submission.id),
"kind": submission.kind,
"attempted_tool": submission.attempted_tool,
"mcp_client_name": submission.mcp_client_name,
"mcp_session_id_present": bool(submission.mcp_session_id),
"mcp_trace_id_present": bool(submission.mcp_trace_id),
}
def _list_response(self, request: Request, kind: enums.SubmissionKind) -> Response:
paginator = self.pagination_class()
page = paginator.paginate_queryset(logic.list_submissions(self.team, kind), request, view=self)
assert page is not None
serializer = self.get_serializer(page, many=True)
return paginator.get_paginated_response(serializer.data)
class MCPFeedbackViewSet(BaseMCPAnalyticsSubmissionViewSet):
user_action_name = "mcp analytics feedback created"
@validated_request(
request_serializer=MCPFeedbackCreateSerializer,
responses={201: OpenApiResponse(response=MCPAnalyticsSubmissionSerializer)},
operation_id="mcp_analytics_feedback_create",
description="Create a new MCP feedback submission for the current project.",
)
def create(self, request: ValidatedRequest, *args: Any, **kwargs: Any) -> Response:
submission = api.create_feedback_submission(
self.team,
cast(User, request.user),
contracts.CreateFeedbackSubmission(
goal=request.validated_data["goal"],
feedback=request.validated_data["feedback"],
category=request.validated_data["category"],
context=self._submission_context(request.validated_data),
),
)
self._report_submission_created(request, submission)
return Response(self.get_serializer(submission).data, status=status.HTTP_201_CREATED)
@extend_schema(
operation_id="mcp_analytics_feedback_list",
description="List MCP feedback submissions for the current project, newest first.",
)
def list(self, request: Request, *args: Any, **kwargs: Any) -> Response:
return self._list_response(request, enums.SubmissionKind.FEEDBACK)
class MCPSessionViewSet(TeamAndOrgViewSetMixin, viewsets.GenericViewSet):
serializer_class = MCPSessionSerializer
scope_object = "mcp_analytics"
# tool_calls, activity_overview, and intent_digest are GETs in spirit (they just read/compute
# cached data, not persist a mutation the caller controls) even though intent_digest is wired
# as a POST; generate_intent actually persists a per-session summary, so it maps to the write
# scope. The default read/write action lists don't cover custom @action names, so
# APIScopePermission/AccessControlPermission would otherwise reject viewer-level access.
scope_object_read_actions = ["list", "retrieve", "tool_calls", "activity_overview", "intent_digest"]
scope_object_write_actions = ["generate_intent"]
pagination_class = MCPSessionPagination
def dangerously_get_queryset(self) -> QuerySet:
# Sessions live in ClickHouse, not a Django model, but GenericViewSet still needs a
# queryset for its plumbing. The model is arbitrary — we borrow MCPAnalyticsSubmission
# (a plain manager) so .none() can't trip a team-scoped manager's guard.
return MCPAnalyticsSubmission.objects.none()
@validated_request(
query_serializer=MCPSessionListQuerySerializer,
responses={200: OpenApiResponse(response=MCPSessionSerializer(many=True))},
operation_id="mcp_analytics_sessions_list",
description="List MCP sessions for the current project, derived by grouping $mcp_tool_call events by $mcp_session_id. Ordered by newest session start first by default.",
)
def list(self, request: ValidatedRequest, *args: Any, **kwargs: Any) -> Response:
params = request.validated_query_data
page = api.list_mcp_sessions(
self.team,
limit=params["limit"],
offset=params["offset"],
search=params["search"],
order_by=params["order_by"],
date_from=params.get("date_from") or None,
date_to=params.get("date_to") or None,
has_errors=params["has_errors"],
properties=params["properties"],
filter_test_accounts=params["filter_test_accounts"],
user=cast(User, request.user),
)
serializer = self.get_serializer(page.results, many=True)
# Instantiate the concrete class (not self.pagination_class()) so the typed
# get_page_response(...) is visible to the type checker.
return MCPSessionPagination().get_page_response(
request, serializer.data, offset=params["offset"], limit=params["limit"], has_next=page.has_next
)
@validated_request(
query_serializer=MCPSessionToolCallsQuerySerializer,
responses={200: OpenApiResponse(response=MCPToolCallSerializer(many=True))},
operation_id="mcp_analytics_sessions_tool_calls",
description="List a page of the $mcp_tool_call events that belong to a given $session_id, in chronological order.",
)
@action(detail=True, methods=["get"], url_path="tool_calls")
def tool_calls(self, request: ValidatedRequest, pk: str | None = None, *args: Any, **kwargs: Any) -> Response:
params = request.validated_query_data
page = api.list_mcp_tool_calls(
self.team,
session_id=str(pk or ""),
limit=params["limit"],
offset=params["offset"],
date_from=params.get("date_from"),
properties=params["properties"],
filter_test_accounts=params["filter_test_accounts"],
user=cast(User, request.user),
)
serializer = MCPToolCallSerializer(page.results, many=True)
return MCPSessionPagination().get_page_response(
request, serializer.data, offset=params["offset"], limit=params["limit"], has_next=page.has_next
)
@extend_schema(
operation_id="mcp_analytics_sessions_generate_intent",
description=(
"Generate (or return the cached) LLM summary of the agent's goal for a session, derived from its "
"recorded $mcp_intents. The first call summarises and persists the result; subsequent calls return "
"the stored summary."
),
request=None,
parameters=[
OpenApiParameter(
name="date_from",
type=OpenApiTypes.DATETIME,
location=OpenApiParameter.QUERY,
required=False,
description=(
"Absolute ISO timestamp lower bound for the intent scan — pass the session's "
"start so older sessions resolve. Defaults to a 7-day lookback when omitted."
),
),
],
responses={200: MCPSessionIntentSerializer},
)
@action(detail=True, methods=["post"], url_path="generate_intent")
def generate_intent(self, request: Request, pk: str | None = None, *args: Any, **kwargs: Any) -> Response:
session_id = str(pk or "")
if not session_id:
return Response({"detail": "session_id is required."}, status=status.HTTP_400_BAD_REQUEST)
date_from = _parse_detail_date_from(request.query_params.get("date_from"))
try:
intent = api.generate_session_intent(self.team, session_id=session_id, date_from=date_from)
except contracts.IntentGenerationUnavailable:
return Response(
{"detail": "Intent generation is unavailable (LLM not configured)."},
status=status.HTTP_503_SERVICE_UNAVAILABLE,
)
serializer = MCPSessionIntentSerializer({"session_id": session_id, "intent": intent})
return Response(serializer.data)
@extend_schema(
operation_id="mcp_analytics_sessions_intent_digest",
description=(
"Generate (or return the cached) LLM digest of what agents are trying to do with this MCP server, "
"derived from the most recent recorded $mcp_intents across all sessions: a one-sentence summary "
"plus semantic themes, each sized and attributed to tools from the intents themselves. Cached by "
"intent corpus and by recency, so repeated calls are cheap and a busy server regenerates at a "
"bounded rate. Powers the dashboard's activity tab."
),
request=None,
responses={
200: MCPIntentDigestSerializer,
503: OpenApiResponse(description="Intent digest generation is unavailable (LLM not configured)."),
},
)
@action(detail=False, methods=["post"], url_path="intent_digest")
def intent_digest(self, request: Request, *args: Any, **kwargs: Any) -> Response:
try:
digest = api.generate_intent_digest(self.team)
except contracts.IntentGenerationUnavailable:
return Response(
{"detail": "Intent digest generation is unavailable (LLM not configured)."},
status=status.HTTP_503_SERVICE_UNAVAILABLE,
)
return Response(MCPIntentDigestSerializer(digest).data)
@validated_request(
query_serializer=MCPActivityOverviewQuerySerializer,
responses={200: OpenApiResponse(response=MCPActivityOverviewSerializer)},
operation_id="mcp_analytics_sessions_activity_overview",
description=(
"Aggregate counters, top tools, agent clients, and the most recent tool calls for the last 30 days, "
"computed in one request. Powers the dashboard's activity view. Results are cached for up to 5 minutes, "
"or 20 seconds when the caller has property restrictions. An empty result is never cached. "
"Pass refresh to skip the cache."
),
)
@action(detail=False, methods=["get"], url_path="activity_overview", pagination_class=None)
def activity_overview(self, request: ValidatedRequest, *args: Any, **kwargs: Any) -> Response:
params = request.validated_query_data
overview = api.get_activity_overview(
self.team,
properties=params["properties"],
filter_test_accounts=params["filter_test_accounts"],
user=cast(User, request.user),
refresh=params["refresh"],
)
return Response(MCPActivityOverviewSerializer(overview).data)
class MCPIntentClusterViewSet(TeamAndOrgViewSetMixin, viewsets.GenericViewSet):
serializer_class = MCPIntentClusterSnapshotSerializer
scope_object = "mcp_analytics"
# recompute is a POST that kicks off the async clustering task (a state change), so it maps to
# the write scope; the snapshot read stays on the read scope.
scope_object_read_actions = ["list", "retrieve"]
scope_object_write_actions = ["recompute"]
posthog_feature_flag = contracts.MCP_ANALYTICS_INTENT_ROUTING_FEATURE_FLAG
permission_classes = [PostHogFeatureFlagPermission]
pagination_class = None
def dangerously_get_queryset(self) -> QuerySet:
# Snapshots are read directly via the facade; this satisfies GenericViewSet plumbing.
return MCPAnalyticsSubmission.objects.none()
@extend_schema(
operation_id="mcp_analytics_intent_clusters_retrieve",
description=(
"Return the most recent intent cluster snapshot for the current project. "
"Returns an empty IDLE snapshot when no clustering run has happened yet."
),
parameters=[
OpenApiParameter(
name="tool",
type=str,
location=OpenApiParameter.QUERY,
required=False,
description=(
"Narrow the response to one tool: its pivot entry, the clusters it serves or switches "
"with, and the overlap pairs it belongs to. Coverage meta stays whole-snapshot. Use "
"this for single-tool views so they don't download every cluster and pivot to render "
"one row. An unknown tool returns empty sections, not a 404."
),
)
],
responses={200: MCPIntentClusterSnapshotSerializer},
)
def list(self, request: Request, *args: Any, **kwargs: Any) -> Response:
snapshot = api.get_intent_cluster_snapshot(self.team, tool=request.query_params.get("tool") or None)
serializer = self.get_serializer(snapshot)
return Response(serializer.data)
@extend_schema(
operation_id="mcp_analytics_intent_clusters_recompute",
description=(
"Trigger an asynchronous recompute of the intent cluster snapshot. The task runs in the "
"background; poll the GET endpoint for progress (status transitions to 'idle' or 'error')."
),
request=None,
responses={202: MCPIntentClusterSnapshotSerializer},
)
@action(detail=False, methods=["post"], url_path="recompute")
def recompute(self, request: Request, *args: Any, **kwargs: Any) -> Response:
api.trigger_intent_cluster_recompute(self.team, cast(User, request.user))
snapshot = api.get_intent_cluster_snapshot(self.team)
serializer = self.get_serializer(snapshot)
return Response(serializer.data, status=status.HTTP_202_ACCEPTED)
class MCPMissingCapabilityViewSet(BaseMCPAnalyticsSubmissionViewSet):
def _report_submission_created(self, request: Request, submission: contracts.Submission) -> None:
distinct_id = str(getattr(request.user, "distinct_id", "") or f"mcp-missing-capability-{self.team.id}")
api.capture_missing_capability_event(self.team, distinct_id, submission)
@validated_request(
request_serializer=MCPMissingCapabilityCreateSerializer,
responses={201: OpenApiResponse(response=MCPAnalyticsSubmissionSerializer)},
operation_id="mcp_analytics_missing_capabilities_create",
description="Create a new missing capability report for the current project.",
)
def create(self, request: ValidatedRequest, *args: Any, **kwargs: Any) -> Response:
submission = api.create_missing_capability_submission(
self.team,
cast(User, request.user),
contracts.CreateMissingCapabilitySubmission(
goal=request.validated_data["goal"],
missing_capability=request.validated_data["missing_capability"],
blocked=request.validated_data["blocked"],
context=self._submission_context(request.validated_data),
),
)
self._report_submission_created(request, submission)
return Response(self.get_serializer(submission).data, status=status.HTTP_201_CREATED)
@extend_schema(
operation_id="mcp_analytics_missing_capabilities_list",
description="List missing capability reports for the current project, newest first.",
)
def list(self, request: Request, *args: Any, **kwargs: Any) -> Response:
return self._list_response(request, enums.SubmissionKind.MISSING_CAPABILITY)
class MCPCustomHarnessViewSet(TeamAndOrgViewSetMixin, viewsets.ModelViewSet):
"""A team's own harness names, shown in place of "Other" in MCP analytics."""
serializer_class = MCPCustomHarnessSerializer
scope_object = "mcp_analytics"
queryset = MCPCustomHarness.objects.unscoped()
pagination_class = None
def safely_get_queryset(self, queryset: QuerySet[MCPCustomHarness]) -> QuerySet[MCPCustomHarness]:
# Rows save under the parent team (`TeamScopedRootMixin.save()`), so a child environment filters on it too.
return queryset.filter(team_id=self.team.parent_team_id or self.team.pk)
def _should_skip_parents_filter(self) -> bool:
# The default parent-lookup filter adds the raw URL team id, which hides the rows a child environment
# saved under its parent. safely_get_queryset already scopes every read.
return True
def perform_create(self, serializer: BaseSerializer[Any]) -> None:
super().perform_create(serializer)
api.invalidate_custom_harness_rules(self.team)
def perform_update(self, serializer: BaseSerializer[Any]) -> None:
super().perform_update(serializer)
api.invalidate_custom_harness_rules(self.team)
def perform_destroy(self, instance: MCPCustomHarness) -> None:
super().perform_destroy(instance)
api.invalidate_custom_harness_rules(self.team)