Skip to content

: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.

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.tsx
new file mode 100644
index 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.tsx
index 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) => (
<div
key={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.ts
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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>
+ )
+}