: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
feat(mcp-analytics): add the setup mode connect step and calls panel (#128671)
Lucas Faria25f21b59f799
diff --git a/products/mcp_analytics/frontend/components/HedgehogTipCard.tsx b/products/mcp_analytics/frontend/components/HedgehogTipCard.tsxnew file mode 100644index 000000000000..a7e91f0840a0--- /dev/null+++ b/products/mcp_analytics/frontend/components/HedgehogTipCard.tsx@@ -0,0 +1,48 @@+import type { ComponentType } from 'react'++import { IconExternal } from '@posthog/icons'+import { LemonButton } from '@posthog/lemon-ui'++import type { HoggiePngProps } from 'lib/brand/hoggies'++export interface HedgehogTipCardLink {+ label: string+ to: string+ dataAttr: string+ onClick?: () => void+}++export function HedgehogTipCard({+ Hedgehog,+ title,+ body,+ link,+}: {+ Hedgehog: ComponentType<Pick<HoggiePngProps, 'className' | 'loading'>>+ title: string+ body: string+ link: HedgehogTipCardLink+}): JSX.Element {+ return (+ <div className="@container flex items-start gap-4 rounded border border-primary bg-surface-primary p-4">+ {/* Eager because a lazy image in `display: none` never gets fetched. */}+ <Hedgehog className="hidden w-20 shrink-0 @min-[22rem]:block" loading="eager" />+ <div className="flex min-w-0 flex-1 flex-col items-start gap-1 text-sm">+ <span className="text-base font-semibold">{title}</span>+ <span className="text-secondary">{body}</span>+ <LemonButton+ className="mt-2"+ size="small"+ type="secondary"+ to={link.to}+ targetBlank+ sideIcon={<IconExternal />}+ onClick={link.onClick}+ data-attr={link.dataAttr}+ >+ {link.label}+ </LemonButton>+ </div>+ </div>+ )+}diff --git a/products/mcp_analytics/frontend/emptyState/MCPToolCallPreview.tsx b/products/mcp_analytics/frontend/emptyState/MCPToolCallPreview.tsxindex 7676f96a69ab..5374dd0d6973 100644--- a/products/mcp_analytics/frontend/emptyState/MCPToolCallPreview.tsx+++ b/products/mcp_analytics/frontend/emptyState/MCPToolCallPreview.tsx@@ -10,27 +10,7 @@ import { inStorybook, inStorybookTestRunner } from 'lib/utils/dom'import { type BrandMarkName } from '../brandMarks'import { BrandMark } from '../components/BrandMark'--type PreviewHarness = 'claude' | 'cursor' | 'openai'--interface PreviewCall {- tool: string- mark: BrandMarkName- harness: PreviewHarness- time: string- error?: boolean-}--// Example tool calls - hand-authored, not real data. MCP tools are bare snake_case-// names (no parentheses - these are tool invocations, not function calls).-// `harness` tags a row for the filter chips.-const CALLS: PreviewCall[] = [- { tool: 'search_docs', mark: 'Claude', harness: 'claude', time: '142ms' },- { tool: 'create_issue', mark: 'Cursor', harness: 'cursor', time: 'err', error: true },- { tool: 'run_query', mark: 'OpenAI', harness: 'openai', time: '210ms' },- { tool: 'list_feature_flags', mark: 'Claude', harness: 'claude', time: '53ms' },- { tool: 'get_schema', mark: 'Cursor', harness: 'cursor', time: '190ms' },-]+import { EXAMPLE_TOOL_CALLS } from './exampleToolCalls'const FILTERS: { id: string; label: string; mark?: BrandMarkName }[] = [{ id: 'all', label: 'All' },@@ -95,7 +75,7 @@ export function MCPToolCallPreview({ mode }: { mode: ProductEmptyStateMode }): J) : null}<div className="MCPPreview__rows">- {CALLS.map((call, i) => (+ {EXAMPLE_TOOL_CALLS.map((call, i) => (<divkey={i}className={cn('MCPPreview__row', call.error && 'MCPPreview__row--error')}diff --git a/products/mcp_analytics/frontend/emptyState/exampleToolCalls.ts b/products/mcp_analytics/frontend/emptyState/exampleToolCalls.tsnew file mode 100644index 000000000000..9f83d3e3bf40--- /dev/null+++ b/products/mcp_analytics/frontend/emptyState/exampleToolCalls.ts@@ -0,0 +1,22 @@+import type { BrandMarkName } from '../brandMarks'++export type ExampleHarness = 'claude' | 'cursor' | 'openai'++export interface ExampleToolCall {+ tool: string+ mark: BrandMarkName+ harness: ExampleHarness+ time: string+ error?: boolean+}++// Example tool calls - hand-authored, not real data. MCP tools are bare snake_case+// names (no parentheses - these are tool invocations, not function calls).+// `harness` tags a row for the filter chips.+export const EXAMPLE_TOOL_CALLS: ExampleToolCall[] = [+ { tool: 'search_docs', mark: 'Claude', harness: 'claude', time: '142ms' },+ { tool: 'create_issue', mark: 'Cursor', harness: 'cursor', time: 'err', error: true },+ { tool: 'run_query', mark: 'OpenAI', harness: 'openai', time: '210ms' },+ { tool: 'list_feature_flags', mark: 'Claude', harness: 'claude', time: '53ms' },+ { tool: 'get_schema', mark: 'Cursor', harness: 'cursor', time: '190ms' },+]diff --git a/products/mcp_analytics/frontend/setupMode/SetupCallsPanel.tsx b/products/mcp_analytics/frontend/setupMode/SetupCallsPanel.tsxnew file mode 100644index 000000000000..91753460bbef--- /dev/null+++ b/products/mcp_analytics/frontend/setupMode/SetupCallsPanel.tsx@@ -0,0 +1,132 @@+import '../emptyState/MCPToolCallPreview.scss'++import { LemonTag, Spinner } from '@posthog/lemon-ui'++import { cn } from 'lib/utils/css-classes'++import type { BrandMarkName } from '../brandMarks'+import { BrandMark } from '../components/BrandMark'+import { harnessMark } from '../dashboard/harnessRegistry'+import { EXAMPLE_TOOL_CALLS } from '../emptyState/exampleToolCalls'+import type { MCPActivityRecentCallApi } from '../generated/api.schemas'+import { formatDuration } from '../sessions/utils'+import { callClientLabel } from './callClient'++const COPY = {+ title: 'Tool calls',+ example: 'example data',+ yours: 'from your server',+ loading: 'Loading your tool calls',+ none: 'No tool calls in the last 30 days',+}++/** As many rows as the example has, so the panel keeps its size when real calls replace it. */+const MAX_ROWS = EXAMPLE_TOOL_CALLS.length++/** `example` before the server has sent anything, `null` while the user's own calls load. */+export type SetupCallsPanelCalls = 'example' | readonly MCPActivityRecentCallApi[] | null++export interface SetupCallsPanelStatus {+ kind: 'listening' | 'live'+ text: string+}++function callTime(call: MCPActivityRecentCallApi): string {+ if (call.is_error) {+ return 'err'+ }+ return call.duration_ms === null ? '' : formatDuration(Math.round(call.duration_ms))+}++function Row({+ mark,+ tool,+ intent,+ time,+ error,+}: {+ mark: BrandMarkName+ tool: string+ intent?: string | null+ time: string+ error?: boolean+}): JSX.Element {+ return (+ <div className={cn('MCPPreview__row', error && 'MCPPreview__row--error')}>+ <span className="MCPPreview__logo">+ <BrandMark name={mark} className="size-3.5" />+ </span>+ <span className="MCPPreview__tool">{tool}</span>+ {intent ? <span className="min-w-0 flex-1 truncate text-xs text-secondary">{intent}</span> : null}+ <span className="MCPPreview__time">{time}</span>+ </div>+ )+}++export function SetupCallsPanel({+ calls,+ status,+ empty = COPY.none,+}: {+ calls: SetupCallsPanelCalls+ status?: SetupCallsPanelStatus+ /** What an empty list says, or nothing when the status line already covers it. */+ empty?: string | null+}): JSX.Element {+ return (+ <div className="MCPPreview">+ <div className="MCPPreview__head">+ <span className="MCPPreview__title">{COPY.title}</span>+ {calls === 'example' ? (+ <LemonTag size="small">{COPY.example}</LemonTag>+ ) : (+ <LemonTag size="small" type="success">+ {COPY.yours}+ </LemonTag>+ )}+ </div>+ {status ? (+ <div className="MCPPreview__listening pt-2.5">+ {status.kind === 'listening' ? (+ <Spinner className="text-sm" />+ ) : (+ <span+ className="size-2 shrink-0 rounded-full bg-success animate-pulse motion-reduce:animate-none"+ aria-hidden="true"+ />+ )}+ {status.text}+ </div>+ ) : null}+ <div className="MCPPreview__rows">+ {calls === 'example' ? (+ EXAMPLE_TOOL_CALLS.map((call) => (+ <Row key={call.tool} mark={call.mark} tool={call.tool} time={call.time} error={call.error} />+ ))+ ) : calls === null ? (+ <div className="MCPPreview__listening py-1.5">+ <Spinner className="text-sm" />+ {COPY.loading}+ </div>+ ) : calls.length === 0 ? (+ empty ? (+ <div className="MCPPreview__listening py-1.5">{empty}</div>+ ) : null+ ) : (+ calls+ .slice(0, MAX_ROWS)+ .map((call) => (+ <Row+ key={`${call.timestamp}-${call.tool}`}+ mark={harnessMark(callClientLabel(call))}+ tool={call.tool}+ intent={call.intent}+ time={callTime(call)}+ error={call.is_error}+ />+ ))+ )}+ </div>+ </div>+ )+}diff --git a/products/mcp_analytics/frontend/setupMode/SetupConnectStep.tsx b/products/mcp_analytics/frontend/setupMode/SetupConnectStep.tsxnew file mode 100644index 000000000000..894a947d9951--- /dev/null+++ b/products/mcp_analytics/frontend/setupMode/SetupConnectStep.tsx@@ -0,0 +1,154 @@+import * as asleepPng from '@posthog/brand/hoggies/png/asleep'+import * as handClaspPng from '@posthog/brand/hoggies/png/hand-clasp'+import * as magnifyingGlassPng from '@posthog/brand/hoggies/png/magnifying-glass'+import * as reporterPng from '@posthog/brand/hoggies/png/reporter'+import { IconCopy } from '@posthog/icons'+import { LemonButton, Spinner } from '@posthog/lemon-ui'++import { pngHoggie } from 'lib/brand/hoggies'+import { copyToClipboard } from 'lib/utils/copyToClipboard'++import { HedgehogTipCard } from '../components/HedgehogTipCard'+import { SetupCallsPanel } from './SetupCallsPanel'+import type { MCPConnectState } from './setupMode'+import { SetupStepHero } from './SetupStepHero'+import { SetupStepLayout } from './SetupStepLayout'++const HedgehogSearching = pngHoggie(magnifyingGlassPng)+const HedgehogHandClasp = pngHoggie(handClaspPng)+const HedgehogReporter = pngHoggie(reporterPng)+const HedgehogAsleep = pngHoggie(asleepPng)++const INSTALL_GUIDE_URL = 'https://posthog.com/docs/mcp-analytics/installation'++const COPY = {+ waiting: {+ title: 'Waiting for your server to connect',+ help: 'Need help?',+ installGuide: 'Read the install guide',+ },+ nextSteps: {+ title: 'Your next steps',+ restart: 'Restart your server when setup is done',+ connect: 'Waiting for your server to connect',+ },+ proTip: {+ title: 'Pro tip while you wait',+ body: "We ask agents what they were trying to achieve when they call your server. It's like a mini user interview to help you make better tools.",+ link: 'Learn about Agent Intent',+ },+ connected: {+ title: 'Your server is connected. Now call a tool.',+ lead: 'Ask your agent to do something that uses one of your tools. The first call shows up here within seconds.',+ prompt: 'Use one of the tools on my MCP server and tell me what it returned.',+ },+ funFact: {+ title: 'Fun fact while you wait',+ body: 'We group tasks in stateless and serverless servers in the same session for simpler debugging.',+ link: 'Learn how we identify users',+ },+ listening: 'Listening for your first tool call',+}++function NextSteps(): JSX.Element {+ const copy = COPY.nextSteps+ return (+ <div className="flex flex-col gap-3 rounded border border-primary bg-surface-primary p-4">+ <span className="text-xs font-semibold text-secondary">{copy.title}</span>+ <ol className="m-0 flex list-none flex-col p-0" aria-label={copy.title}>+ <li className="flex gap-3">+ <div className="flex flex-col items-center pt-0.5">+ <span className="size-4 rounded-full border-2 border-secondary" />+ <div className="my-1 min-h-3 w-px flex-1 bg-border" />+ </div>+ <span className="min-w-0 flex-1 pb-3 text-sm font-semibold">{copy.restart}</span>+ </li>+ <li className="flex gap-3">+ <div className="flex flex-col items-center pt-0.5">+ <Spinner className="text-base" textColored />+ </div>+ <span className="min-w-0 flex-1 text-sm font-semibold">{copy.connect}</span>+ </li>+ </ol>+ </div>+ )+}++function ConnectWaiting(): JSX.Element {+ return (+ <>+ <SetupStepHero Hedgehog={HedgehogSearching} title={COPY.waiting.title} />+ <NextSteps />+ <div className="flex flex-wrap items-center gap-x-2 gap-y-1 text-sm">+ <span className="text-secondary">{COPY.waiting.help}</span>+ <LemonButton+ size="small"+ type="tertiary"+ to={INSTALL_GUIDE_URL}+ targetBlank+ data-attr="mcp-analytics-setup-mode-install-guide"+ >+ {COPY.waiting.installGuide}+ </LemonButton>+ </div>+ </>+ )+}++function ConnectConnected(): JSX.Element {+ return (+ <>+ <SetupStepHero Hedgehog={HedgehogHandClasp} title={COPY.connected.title} lead={COPY.connected.lead} />+ <div className="flex flex-wrap items-center gap-2 rounded border border-primary bg-surface-primary p-3">+ <span className="min-w-0 flex-1 font-mono text-xs">{COPY.connected.prompt}</span>+ <LemonButton+ size="small"+ type="secondary"+ icon={<IconCopy />}+ onClick={() => void copyToClipboard(COPY.connected.prompt, 'prompt')}+ data-attr="mcp-analytics-setup-mode-copy-try-prompt"+ >+ Copy+ </LemonButton>+ </div>+ </>+ )+}++export function SetupConnectStep({ connectState }: { connectState: MCPConnectState }): JSX.Element {+ const connected = connectState.kind === 'connected'+ return (+ <SetupStepLayout+ aside={+ <>+ <SetupCallsPanel calls="example" status={{ kind: 'listening', text: COPY.listening }} />+ {connected ? (+ <HedgehogTipCard+ Hedgehog={HedgehogAsleep}+ title={COPY.funFact.title}+ body={COPY.funFact.body}+ link={{+ label: COPY.funFact.link,+ to: 'https://posthog.com/docs/mcp-analytics/identifying-users',+ dataAttr: 'mcp-analytics-setup-mode-identify-users',+ }}+ />+ ) : (+ <HedgehogTipCard+ Hedgehog={HedgehogReporter}+ title={COPY.proTip.title}+ body={COPY.proTip.body}+ link={{+ label: COPY.proTip.link,+ to: 'https://posthog.com/docs/mcp-analytics/intent',+ dataAttr: 'mcp-analytics-setup-mode-agent-intent',+ }}+ />+ )}+ </>+ }+ >+ {connected ? <ConnectConnected /> : <ConnectWaiting />}+ </SetupStepLayout>+ )+}diff --git a/products/mcp_analytics/frontend/setupMode/SetupStepHero.tsx b/products/mcp_analytics/frontend/setupMode/SetupStepHero.tsxnew file mode 100644index 000000000000..74b87d97cd20--- /dev/null+++ b/products/mcp_analytics/frontend/setupMode/SetupStepHero.tsx@@ -0,0 +1,28 @@+import type { ComponentType, ReactNode } from 'react'++import type { HoggiePngProps } from 'lib/brand/hoggies'++/** The title and lead every setup step opens with, beside a hedgehog unless the step shows its own. */+export function SetupStepHero({+ Hedgehog,+ title,+ lead,+}: {+ Hedgehog?: ComponentType<Pick<HoggiePngProps, 'className' | 'loading'>>+ title: ReactNode+ lead?: ReactNode+}): JSX.Element {+ return (+ <div className="flex items-center gap-4">+ {/* The hedgehog is the first thing to go when the window is narrow, so the title keeps its width.+ It loads eagerly because a lazy image in `display: none` never gets fetched. */}+ {Hedgehog ? (+ <Hedgehog className="hidden w-20 shrink-0 @min-[36rem]/setup-mode:block" loading="eager" />+ ) : null}+ <div className="flex min-w-0 flex-col gap-1">+ <h2 className="m-0 text-2xl font-semibold">{title}</h2>+ {lead ? <p className="m-0 text-sm text-secondary">{lead}</p> : null}+ </div>+ </div>+ )+}diff --git a/products/mcp_analytics/frontend/setupMode/SetupStepLayout.tsx b/products/mcp_analytics/frontend/setupMode/SetupStepLayout.tsxnew file mode 100644index 000000000000..384c05aa6c44--- /dev/null+++ b/products/mcp_analytics/frontend/setupMode/SetupStepLayout.tsx@@ -0,0 +1,10 @@+import type { ReactNode } from 'react'++export function SetupStepLayout({ children, aside }: { children: ReactNode; aside: ReactNode }): JSX.Element {+ return (+ <div className="grid items-start gap-8 @min-[56rem]/setup-mode:grid-cols-[minmax(0,1fr)_minmax(0,26rem)] @min-[72rem]/setup-mode:gap-12">+ <div className="flex min-w-0 flex-col gap-6">{children}</div>+ <aside className="flex min-w-0 flex-col gap-4">{aside}</aside>+ </div>+ )+}