: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
/**
* Shared hook for MCP UI Apps to handle tool results.
*
* This hook provides a simple way to:
* - Connect to the MCP host
* - Receive tool result notifications
* - Apply host styling
* - Handle errors and loading states
* - Track analytics events via PostHog
*
* Usage:
* ```tsx
* function MyApp() {
* const { data, isConnected, error, app, capture } = useToolResult<MyDataType>({
* appName: 'My App',
* appVersion: '1.0.0',
* })
*
* // Capture custom events
* const handleClick = () => {
* capture('button_clicked', { button_name: 'submit' })
* }
*
* if (error) return <div>Error: {error.message}</div>
* if (!isConnected) return <div>Connecting...</div>
* if (!data) return <div>Waiting for data...</div>
*
* return <MyVisualization data={data} />
* }
* ```
*/
import { type App, useApp, useHostStyles } from '@modelcontextprotocol/ext-apps/react'
import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
import {
capture,
captureAppConnected,
captureAppConnectionError,
captureHostContextChanged,
captureLinkOpened,
captureToolCancelled,
captureToolInput,
captureToolResult,
captureWaitTimeout,
identifyUser,
initPostHog,
} from '../analytics/posthog'
import { APP_DATA_META_KEY, extractAnalytics } from '../types'
/**
* How long the app waits for the host before it reports a failure instead of a
* loading state. The host normally pushes the tool result within milliseconds of
* the connection handshake, so this budget only expires when a notification never
* arrives. A result that lands after the budget still clears the error and renders.
*/
export const DEFAULT_WAIT_TIMEOUT_MS = 20_000
export interface UseToolResultOptions {
/** App name shown to the host */
appName: string
/** App version */
appVersion?: string
/**
* How long to wait for the host to connect, and then for it to deliver a tool
* result, before surfacing an error. Set to 0 to wait indefinitely.
*/
waitTimeoutMs?: number
}
export interface ContainerDimensions {
height?: number
maxHeight?: number
width?: number
maxWidth?: number
}
export interface UseToolResultReturn<T> {
/** The parsed tool result data, or null if not yet received */
data: T | null
/** The tool result's `_meta`, or null if not yet received */
resultMeta: Record<string, unknown> | null
/** Whether the app is connected to the host */
isConnected: boolean
/** Connection or parsing error, if any */
error: Error | null
/** Whether the tool call was cancelled by the user or host */
isCancelled: boolean
/** The App instance for advanced usage (e.g., opening links) */
app: App | null
/** Callback to open a link via the host */
openLink: (url: string) => void
/** Capture a custom analytics event */
capture: typeof capture
/** Container dimensions from the host, updated on context changes */
containerDimensions: ContainerDimensions | null
/** Re-read container dimensions from the host context */
refreshContainerDimensions: () => void
}
/** What the app is waiting for, which decides whether a watchdog is armed. */
export type WaitPhase = 'connecting' | 'awaiting-result' | 'settled'
export interface WaitPhaseInput {
isConnected: boolean
hasData: boolean
isCancelled: boolean
/** A connection or parse failure the app can already report on its own. */
hasError: boolean
}
/**
* Decide what the app is still waiting for. `settled` covers every state the app
* can already draw, including failures, so the watchdog never fires on top of an
* error the app is showing.
*/
export function resolveWaitPhase({ isConnected, hasData, isCancelled, hasError }: WaitPhaseInput): WaitPhase {
if (hasData || isCancelled || hasError) {
return 'settled'
}
return isConnected ? 'awaiting-result' : 'connecting'
}
const WAIT_TIMEOUT_MESSAGES: Record<Exclude<WaitPhase, 'settled'>, string> = {
connecting: "Couldn't load this app. Re-run the tool to try again.",
'awaiting-result': "This app didn't get any results. Re-run the tool to try again.",
}
const PARSE_ERROR_MESSAGE = "Couldn't read the results for this app. Re-run the tool to try again."
const TOOL_ERROR_MESSAGE = 'The tool call failed, so there are no results to show. Re-run the tool to try again.'
/**
* Parse tool result content, preferring structuredContent over the `_meta`
* fallback. Never falls back to text content.
*/
export function parseToolResultContent<T>(structuredContent: unknown, meta?: unknown): T | null {
// Prefer structuredContent when the host forwards it.
if (structuredContent !== undefined && structuredContent !== null) {
return structuredContent as T
}
// Coding-agent hosts suppress `structuredContent` so the model reads the
// compact text table; the app's data then rides on `_meta` instead.
const appData = (meta as Record<string, unknown> | undefined)?.[APP_DATA_META_KEY]
if (appData !== undefined && appData !== null) {
return appData as T
}
return null
}
function extractContainerDimensions(ctx: Record<string, unknown> | undefined | null): ContainerDimensions | null {
const dims = ctx?.containerDimensions as Record<string, unknown> | undefined
if (!dims) {
return null
}
// Need this because TS doesn't want us to set keys with `undefined`
const result: ContainerDimensions = {}
if (typeof dims.height === 'number') {
result.height = dims.height
}
if (typeof dims.maxHeight === 'number') {
result.maxHeight = dims.maxHeight
}
if (typeof dims.width === 'number') {
result.width = dims.width
}
if (typeof dims.maxWidth === 'number') {
result.maxWidth = dims.maxWidth
}
return result
}
function log(...args: any[]): void {
console.debug('[PostHog MCP App]', ...args)
}
/**
* Hook for MCP UI Apps to receive and handle tool results.
*
* Handles all the boilerplate for connecting to the host, receiving tool results,
* applying host styling, and tracking analytics.
*/
export function useToolResult<T = unknown>({
appName,
appVersion = '1.0.0',
waitTimeoutMs = DEFAULT_WAIT_TIMEOUT_MS,
}: UseToolResultOptions): UseToolResultReturn<T> {
const [data, setData] = useState<T | null>(null)
const [resultMeta, setResultMeta] = useState<Record<string, unknown> | null>(null)
const [parseError, setParseError] = useState<Error | null>(null)
const [isCancelled, setIsCancelled] = useState(false)
const [timedOutPhase, setTimedOutPhase] = useState<Exclude<WaitPhase, 'settled'> | null>(null)
const [containerDimensions, setContainerDimensions] = useState<ContainerDimensions | null>(null)
const hasLoggedConnection = useRef(false)
// Initialize PostHog on first render
useEffect(() => {
log('Initializing PostHog', { appName, appVersion })
initPostHog(appName, appVersion)
}, [appName, appVersion])
const {
app,
isConnected,
error: connectionError,
} = useApp({
appInfo: { name: appName, version: appVersion },
capabilities: {},
onAppCreated: (appInstance) => {
log('App created', { appInstance })
// Register tool input handler
appInstance.ontoolinput = (params) => {
captureToolInput({
toolName: 'toolName' in params && params.toolName ? (params.toolName as string) : undefined, // toolName is not defined in the type
hasArguments: !!params.arguments,
})
}
// Do NOT register partial tool input handler (streaming)
// This is too noisy, happens for each chunk of input we get from the server
// appInstance.ontoolinputpartial = () => {}
// Register tool cancelled handler
appInstance.ontoolcancelled = (params) => {
setIsCancelled(true)
captureToolCancelled({
toolName: 'toolName' in params && params.toolName ? (params.toolName as string) : undefined, // toolName is not defined in the type
reason: typeof params.reason === 'string' ? params.reason : undefined,
})
}
// Register host context changed handler
appInstance.onhostcontextchanged = (params) => {
captureHostContextChanged({
hasStyles: !!params.styles,
hasFonts: !!params.styles?.css?.fonts,
theme: typeof params.theme === 'string' ? params.theme : undefined,
})
setContainerDimensions(extractContainerDimensions(params))
}
// Register tool result handler
appInstance.ontoolresult = (params) => {
try {
const meta = (params as { _meta?: Record<string, unknown> })._meta
const parsed = params.isError ? null : parseToolResultContent<T>(params.structuredContent, meta)
// Extract analytics metadata and identify the user
const analytics = extractAnalytics(parsed)
if (analytics) {
identifyUser(analytics.distinctId, analytics.toolName, analytics.mcpClientName)
}
// `hasAppData` and `rendered` separate a healthy result that rode the
// `_meta` channel from one the app could not draw at all, which
// `hasStructuredContent` alone cannot tell apart.
captureToolResult({
hasStructuredContent: !!params.structuredContent,
hasAppData: meta?.[APP_DATA_META_KEY] !== undefined && meta[APP_DATA_META_KEY] !== null,
contentLength: params.content?.length,
rendered: parsed !== null,
isError: !!params.isError,
})
if (parsed !== null) {
setResultMeta(meta ?? null)
setData(parsed)
setParseError(null)
} else {
const err = new Error(params.isError ? TOOL_ERROR_MESSAGE : PARSE_ERROR_MESSAGE)
console.error('[PostHog MCP App UI] Parse error:', err)
setParseError(err)
}
} catch (e) {
const err = e instanceof Error ? e : new Error(String(e))
console.error('[PostHog MCP App UI] Exception:', err)
setParseError(err)
}
}
},
})
// Apply host styles (CSS variables, theme, and fonts)
useHostStyles(app, app?.getHostContext())
// Track connection state and errors
useEffect(() => {
if (connectionError && !hasLoggedConnection.current) {
console.error('[PostHog MCP App UI] Connection error:', connectionError)
captureAppConnectionError(connectionError)
hasLoggedConnection.current = true
}
}, [connectionError])
useEffect(() => {
if (isConnected && app && !hasLoggedConnection.current) {
const hostContext = app.getHostContext()
// Cast to access fonts which may not be in the current SDK type definitions
const hostContextExtended = hostContext as typeof hostContext & { fonts?: unknown }
captureAppConnected({
hasStyles: !!hostContext?.styles,
hasFonts: !!hostContextExtended?.fonts,
availableDisplayModes: hostContext?.availableDisplayModes,
})
setContainerDimensions(extractContainerDimensions(hostContext as unknown as Record<string, unknown>))
hasLoggedConnection.current = true
}
}, [isConnected, app])
// Callback to open links via the host
const openLink = useCallback(
(url: string) => {
captureLinkOpened(url)
if (app) {
app.openLink({ url })
} else {
window.open(url, '_blank', 'noopener,noreferrer')
}
},
[app]
)
// Re-read container dimensions from the current host context
const refreshContainerDimensions = useCallback(() => {
if (!app) {
return
}
const ctx = app.getHostContext()
setContainerDimensions(extractContainerDimensions(ctx as unknown as Record<string, unknown>))
}, [app])
const waitPhase = resolveWaitPhase({
isConnected,
hasData: data !== null,
isCancelled,
hasError: connectionError !== null || parseError !== null,
})
// Without this watchdog a notification that never arrives leaves the app in its
// loading state forever, which reads as a broken render rather than a failure the
// person can retry.
useEffect(() => {
if (timedOutPhase !== null) {
// A late connection or a late result moves the app out of the phase that
// timed out, so drop the error and let the app draw what it now has.
if (timedOutPhase !== waitPhase) {
setTimedOutPhase(null)
}
return
}
if (waitPhase === 'settled' || waitTimeoutMs <= 0) {
return
}
const timer = setTimeout(() => {
log('Timed out waiting for the host', { waitPhase, waitTimeoutMs })
setTimedOutPhase(waitPhase)
captureWaitTimeout({ phase: waitPhase, timeoutMs: waitTimeoutMs })
}, waitTimeoutMs)
return () => clearTimeout(timer)
}, [waitPhase, timedOutPhase, waitTimeoutMs])
const timeoutError = useMemo(
() => (timedOutPhase === null ? null : new Error(WAIT_TIMEOUT_MESSAGES[timedOutPhase])),
[timedOutPhase]
)
// Combine connection, parse, and timeout errors
const error = connectionError || parseError || timeoutError
return {
data,
resultMeta,
isConnected,
error,
isCancelled,
app,
openLink,
capture,
containerDimensions,
refreshContainerDimensions,
}
}