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.

19.9 KB
Raw Blame
/**
 * MCP client profiling and capability detection.
 *
 * `clientInfo.name` is what a client self-reports during the `initialize`
 * handshake. We use substring matching (with separators stripped and case
 * normalized) so variants like "claude-code", "Claude Code", "claude-code-cli",
 * and "claude-code/1.2.3" all resolve to the same form.
 *
 * The `MCPClientProfile` class owns all per-client behavior decisions:
 *
 * - `isToolsModeClient()` matches the clients that keep the full per-tool
 *   roster ("tools" mode) instead of the single-exec CLI default. This is the
 *   only way a client lands in tools mode without an explicit `?mode=` /
 *   `x-posthog-mcp-mode` override — see `resolveMode`.
 *
 * - `isCliModeEnabled()` matches clients that should drop `structuredContent`
 *   when a `formatted_results` override is set. Every known Anthropic client
 *   qualifies — matched against the `x-anthropic-client` (`vendorClient`)
 *   header, since Anthropic pools MCP transports across all its products and
 *   reports the live one there. Other coding agents are matched by
 *   self-reported client name. Cursor is deliberately excluded from the name
 *   match — it reads text for the model and renders `structuredContent` in UI,
 *   so it does not need the formatted-results workaround.
 *
 * - `isPostHogCodeConsumer()` matches the `x-posthog-mcp-consumer` header
 *   sent by the PostHog Desktop Tasks wrapper.
 *
 * - `isRenderUiHost()` uses declared MCP Apps support when the client sends it.
 *   Otherwise it matches Claude web/desktop, Cowork, and the exact `openai-mcp`
 *   client name.
 *
 * - `isClaudeChatHost()` matches Claude web/desktop only — the chat surfaces that
 *   report `supportsInstructions` but never surface the `instructions` payload to
 *   the model. Used to keep the env-context on the exec command description for
 *   them. Cowork surfaces instructions normally, so it is deliberately excluded.
 *
 * - `capabilities` is a feature-flag-style object describing protocol
 *   features the client actually implements (e.g. `supportsInstructions` —
 *   Codex ignores the `instructions` field returned from `initialize`).
 */

function normalizeClientName(s: string): string {
    return s.toLowerCase().replace(/[-_\s]+/g, '')
}

function matchesAnyFragment(clientName: string | undefined, fragments: readonly string[]): boolean {
    if (!clientName) {
        return false
    }
    const normalized = normalizeClientName(clientName)
    if (!normalized) {
        return false
    }
    return fragments.some((fragment) => normalized.includes(normalizeClientName(fragment)))
}

function matchesProductName(value: string | undefined, names: readonly string[]): boolean {
    const product = value?.trim().split(/[\s/]/, 1)[0]?.toLowerCase()
    return !!product && names.includes(product)
}

// Coding agents and LLM-driven clients that render text rather than MCP Apps UI.
// Matched by `isCliModeEnabled()`, which gates dropping `structuredContent` when a
// `formatted_results` override is set. Mode selection does NOT read this list — CLI
// (single-exec) is the default for every client; `TOOLS_MODE_CLIENT_NAME_FRAGMENTS`
// is the tools-mode allow-list.
export const CODING_AGENT_CLIENT_NAME_FRAGMENTS = [
    'claude-code',
    'cline',
    'roo-code',
    'roo-cline',
    'continue',
    'codex',
    'windsurf',
    'zed',
    'aider',
    'copilot',
    'gemini-cli',
    // Devin self-reports `clientInfo.name` as `Devin`; it's a coding agent and
    // benefits from the same single-exec mode.
    'devin',
    // LibreChat is a general MCP client, but benefits from the same CLI-shaped
    // single-exec mode as coding agents.
    'librechat',
    // Notion AI ships its own `notion-mcp-client` (not a coding agent per se,
    // but an LLM-driven consumer that benefits from the same single-exec mode
    // and formatted-text rendering as coding agents).
    'notion',
    // OpenCode is a terminal coding agent (and the engine behind clients like
    // OpenWork). It connects through OpenCode's MCP client, which self-reports
    // `clientInfo.name` as `opencode`. It renders text, not MCP Apps UI, so it
    // wants single-exec mode like the other coding agents.
    'opencode',
    // Amp is Sourcegraph's coding agent; its MCP client self-reports
    // `clientInfo.name` as `amp-mcp-client` and benefits from single-exec mode.
    'amp-mcp-client',
    // Poke is an LLM-driven assistant that renders text, not MCP Apps UI, so it
    // wants the same single-exec mode as the coding agents.
    'poke',
    // Grok (xAI) — both Grok Build (the terminal coding agent) and the grok.com
    // assistant connect custom MCP servers and render text rather than MCP Apps
    // UI, so they benefit from the same single-exec mode and formatted-text
    // rendering as the other coding agents.
    'grok',
    // Ando is an LLM-driven assistant (Slack, chat, calls) whose MCP client
    // self-reports `clientInfo.name` as `ando-mcp-gateway`; it renders text and
    // benefits from the same single-exec mode as the coding agents.
    'ando-mcp-gateway',
] as const

// Clients that wedge after a stateless `server/discover` but complete the legacy
// handshake, so discover answers method-not-found to push them back to `initialize`.
// Remove an entry once the client completes the stateless dialect.
export const LEGACY_DIALECT_ONLY_CLIENT_NAME_FRAGMENTS = ['antigravity'] as const

// Clients that keep the full per-tool roster ("tools" mode) instead of the
// single-exec CLI default.
// - Cursor self-reports `clientInfo.name` (`cursor-vscode`, `Cursor`); it sends
//   `content[].text` to the model and renders `structuredContent` in its UI, so
//   the full roster serves it better than the exec wrapper. Some older Cursor
//   builds omit `clientInfo.name` and are only identifiable by their
//   `Cursor/x.y.z (...)` User-Agent, hence the UA fragment too.
// - Every OpenAI surface (ChatGPT, Codex, Agent Builder, Responses API) stays
//   on the CLI default. OpenAI's shared `openai-mcp` client caches the roster it
//   captures for a published plugin and serves that snapshot to every user, so
//   the plugin listing pins its mode explicitly with `?mode=` instead of relying
//   on a User-Agent label that only some of its requests carry.
export const TOOLS_MODE_CLIENT_NAME_FRAGMENTS = ['cursor'] as const
export const TOOLS_MODE_USER_AGENT_FRAGMENTS = ['cursor'] as const

// Known `x-anthropic-client` (`vendorClient`) header values. Anthropic pools
// MCP transports across all its products and reports the live one in this
// header, so it's the reliable identifier for an Anthropic client (the
// `initialize` body's `clientName` is the pool owner, e.g. `Anthropic/ClaudeAI`).
// Every Anthropic product runs in CLI (single-exec) mode. Matched as normalized
// substrings, so vendor-prefixed shapes like `Anthropic/ClaudeAI` resolve to
// `claudeai`.
export const ANTHROPIC_CLIENT_NAME_FRAGMENTS = ['claudecode', 'claudeai', 'cowork', 'claudedesign'] as const

// Anthropic clients connect through a pooled MCP transport and usually omit the
// `initialize` body's `clientInfo.name`, reporting their live product only in the
// `x-anthropic-client` (`vendorClient`) header. Map that vendor value to the
// canonical client-name token the MCP analytics dashboard buckets on, so these
// sessions are attributed to a real client instead of falling into "Other".
// Mirrors the vendor→name mapping in the dashboard (harnessRegistry.ts and
// models-mcp.md) — keep the three in sync.
const VENDOR_CLIENT_TO_CLIENT_NAME: Readonly<Record<string, string>> = {
    claudecode: 'claude-code',
    claudeai: 'claude-ai',
    cowork: 'cowork',
    claudedesign: 'claude-design',
}

/**
 * Resolve the client name used for analytics (`$mcp_client_name`) and the API
 * client header. Prefers the self-reported `clientInfo.name`; when that's absent
 * — as it is for Anthropic clients on the pooled transport — it falls back to a
 * canonical name derived from the `x-anthropic-client` vendor header, keeping the
 * raw vendor value for any unrecognized Anthropic product. Returns undefined when
 * neither is available.
 */
export function resolveEffectiveClientName(
    clientName: string | undefined,
    vendorClient: string | undefined
): string | undefined {
    if (clientName) {
        return clientName
    }
    if (!vendorClient) {
        return undefined
    }
    return VENDOR_CLIENT_TO_CLIENT_NAME[normalizeClientName(vendorClient)] ?? vendorClient
}

// Value sent in `x-posthog-mcp-consumer` by PostHog Desktop (the Tasks sandbox
// wrapper around the Claude Agent SDK) when the task was launched from the
// PostHog Desktop UI. Slack-launched runs send `"slack"` and posthog_ai (Max) runs
// send `"posthog_ai"`; only PostHog Desktop renders MCP UI apps, so this is the
// sole consumer that gates UI-apps payload emission in single-exec mode.
export const POSTHOG_CODE_CONSUMER = 'posthog-code'

// Claude web/desktop and Cowork are MCP Apps hosts that render interactive UI
// (iframes), so the `render-ui` tool is meaningful for them. They send
// `x-anthropic-client: ClaudeAI` / `Cowork` (vs `ClaudeCode` for Claude Code) and
// `User-Agent: Claude-User`. The vendor client is authoritative when present:
// Claude Code is excluded even though it may share the `Claude-User` user-agent.
// The user-agent is a fallback solely for requests that omit the vendor header.
// We deliberately do NOT match `clientName` here — Anthropic pools transports, so
// Claude Code's `clientInfo.name` is also `Anthropic/ClaudeAI`, and matching it
// would misclassify Claude Code as a UI host.
export const ANTHROPIC_UI_HOST_VENDOR_FRAGMENTS = ['claudeai', 'cowork'] as const

// Claude web/desktop never show `instructions` to the model. Cowork does, so it
// is not a chat host even though it is a UI host.
export const ANTHROPIC_CHAT_HOST_VENDOR_FRAGMENTS = ['claudeai'] as const

// Anthropic surfaces that render MCP UI apps on the `exec` response itself, so they
// get the same treatment as the PostHog Desktop consumer. `Cowork` is not one: Claude
// desktop chat reports `Cowork` and mounts an iframe only for a tool that declares
// `_meta.ui.resourceUri` on `tools/list`, which `exec` does not. It renders through
// `render-ui`, like `ClaudeAI`.
export const INLINE_EXEC_UI_APP_VENDOR_FRAGMENTS = ['claudecode'] as const

// User-Agent Anthropic clients send when they connect without the
// `x-anthropic-client` header (Claude.ai web/desktop and internal Anthropic
// tooling). It's a generic Anthropic signal — Claude Code and Cowork can send it
// too — so it drives CLI-mode detection; the UI-host check reuses it as its own
// user-agent fallback.
export const ANTHROPIC_USER_AGENT_FRAGMENTS = ['claude-user'] as const
export const ANTHROPIC_UI_HOST_USER_AGENT_FRAGMENTS = ANTHROPIC_USER_AGENT_FRAGMENTS

// OpenAI clients send no vendor header, so the shared `openai-mcp` client is matched
// on `clientInfo.name` or the User-Agent product token. The match is exact because a
// substring match on `codex` also matches Codex CLI (`codex-mcp-client`), which cannot
// render UI.
export const OPENAI_RENDER_UI_CLIENT_NAMES = ['openai-mcp'] as const

export type ClientCapabilities = {
    // MCP `initialize` response includes an `instructions` field that most
    // clients inject into the model's system prompt. Codex discards it, so
    // we skip sending it (saving the payload cost) for those sessions.
    supportsInstructions: boolean
}

export const DEFAULT_CLIENT_CAPABILITIES: ClientCapabilities = {
    supportsInstructions: true,
}

type CapabilityOverride = {
    // Matched against the self-reported `clientInfo.name`.
    fragments: readonly string[]
    // Matched against the User-Agent, for surfaces that omit `clientInfo.name`
    // entirely — Codex through OpenAI's shared `openai-mcp` client identifies
    // only via `openai-mcp/x.y.z (Codex)`.
    userAgentFragments?: readonly string[]
    capabilities: Partial<ClientCapabilities>
}

const CLIENT_CAPABILITY_OVERRIDES: readonly CapabilityOverride[] = [
    {
        fragments: ['codex'],
        userAgentFragments: ['codex'],
        capabilities: { supportsInstructions: false },
    },
]

type MCPClientProfileInput = {
    clientName?: string | undefined
    clientVersion?: string | undefined
    consumer?: string | undefined
    oauthClientName?: string | undefined
    // Per-request `x-anthropic-client` value (e.g. `ClaudeCode`, `ClaudeAI`).
    // Anthropic pools MCP transports across products, so the live inner client
    // can disagree with the session-pinned `clientName` from `initialize`.
    vendorClient?: string | undefined
    // Per-request `User-Agent` (e.g. `Claude-User` for Claude web/desktop).
    userAgent?: string | undefined
    uiSupported?: boolean | undefined
}

export class MCPClientProfile {
    readonly clientName: string | undefined
    readonly clientVersion: string | undefined
    readonly consumer: string | undefined
    readonly oauthClientName: string | undefined
    readonly vendorClient: string | undefined
    readonly userAgent: string | undefined
    readonly uiSupported: boolean | undefined

    private _capabilities: ClientCapabilities | undefined

    constructor(input: MCPClientProfileInput) {
        this.clientName = input.clientName
        this.clientVersion = input.clientVersion
        this.consumer = input.consumer
        this.oauthClientName = input.oauthClientName
        this.vendorClient = input.vendorClient
        this.userAgent = input.userAgent
        this.uiSupported = input.uiSupported
    }

    isToolsModeClient(): boolean {
        // The only clients that auto-select the full per-tool roster; everyone
        // else defaults to CLI (single-exec) mode — see `resolveMode`. Matched on
        // the self-reported `clientInfo.name` and the User-Agent (older Cursor
        // builds identify only through the UA); never on the vendor header, so
        // Anthropic pooled transports can't land in tools mode.
        return (
            matchesAnyFragment(this.clientName, TOOLS_MODE_CLIENT_NAME_FRAGMENTS) ||
            matchesAnyFragment(this.userAgent, TOOLS_MODE_USER_AGENT_FRAGMENTS)
        )
    }

    isCliModeEnabled(): boolean {
        // Gates dropping `structuredContent` when a `formatted_results` override
        // is set — these clients read `content[].text`, so the structured copy
        // would only bloat the payload. Every Anthropic product qualifies.
        if (this.isAnthropicClient()) {
            return true
        }
        // Otherwise fall back to the self-reported client name for coding agents.
        return matchesAnyFragment(this.clientName, CODING_AGENT_CLIENT_NAME_FRAGMENTS)
    }

    isAnthropicClient(): boolean {
        // Anthropic pools MCP transports across all its products (Claude Code,
        // Claude.ai, Cowork, Claude Design, …), so the `x-anthropic-client` header
        // is the reliable signal of the live product when present. Some surfaces
        // (Claude.ai web/desktop, internal tools) connect without that header, so
        // also accept the `Claude-User` user-agent and the pooled `Anthropic/…`
        // `clientInfo.name`. Unlike `isRenderUiHost`, matching the pooled name here
        // is safe and intended: every Anthropic product belongs in CLI mode, so
        // there is nothing to misclassify.
        return matchesAnyFragment(this.vendorClient, ANTHROPIC_CLIENT_NAME_FRAGMENTS) || this.isAnthropicConnector()
    }

    isAnthropicConnector(): boolean {
        // The connector omits `x-anthropic-client` on `tools/list` and sends it on the call, so this must not read it.
        return (
            matchesAnyFragment(this.userAgent, ANTHROPIC_USER_AGENT_FRAGMENTS) ||
            normalizeClientName(this.clientName ?? '').startsWith('anthropic')
        )
    }

    isLegacyDialectOnly(): boolean {
        return matchesAnyFragment(this.clientName, LEGACY_DIALECT_ONLY_CLIENT_NAME_FRAGMENTS)
    }

    isPostHogCodeConsumer(): boolean {
        return this.consumer === POSTHOG_CODE_CONSUMER
    }

    isRenderUiHost(): boolean {
        // A client that declares the MCP Apps extension states its own support, so the
        // declaration wins over name detection in both directions. Clients that omit the
        // extension fall back to the hosts known to render `render-ui`.
        if (this.uiSupported !== undefined) {
            return this.uiSupported
        }
        // The per-request vendor client (`x-anthropic-client`) is authoritative: it
        // distinguishes the Claude surfaces that pool the same MCP transport —
        // `ClaudeAI` (web/desktop) and `Cowork`, both `render-ui` hosts, from
        // `ClaudeCode`, which only renders UI apps inline on the `exec` response
        // (see `isInlineExecUiHost`). When it's present, trust it exclusively; only
        // fall back to the user-agent and client name when the vendor header is
        // absent. Otherwise a non-render-ui surface like Claude Code — which can
        // share the `Claude-User` user-agent with web/desktop — would be
        // misclassified as a UI host.
        if (this.vendorClient) {
            return matchesAnyFragment(this.vendorClient, ANTHROPIC_UI_HOST_VENDOR_FRAGMENTS)
        }
        return (
            matchesAnyFragment(this.userAgent, ANTHROPIC_UI_HOST_USER_AGENT_FRAGMENTS) ||
            matchesProductName(this.userAgent, OPENAI_RENDER_UI_CLIENT_NAMES) ||
            matchesProductName(this.clientName, OPENAI_RENDER_UI_CLIENT_NAMES)
        )
    }

    isInlineExecUiHost(): boolean {
        // Claude Code renders MCP UI apps inline on the single-exec `exec` tool, while
        // Claude.ai and Cowork render through the separate `render-ui` tool.
        // Like PostHog Desktop, Claude Code surfaces `structuredContent` to the model, so
        // the exec UI-app branch suppresses it and re-homes the app data onto `_meta`.
        // The per-request vendor header (`ClaudeCode`) is the reliable signal.
        return matchesAnyFragment(this.vendorClient, INLINE_EXEC_UI_APP_VENDOR_FRAGMENTS)
    }

    isClaudeChatHost(): boolean {
        // Same vendor-authoritative shape as `isRenderUiHost`, narrowed to the chat
        // surfaces (Claude web/desktop) that ignore the `instructions` payload. The
        // `Claude-User` user-agent fallback is kept for requests without the vendor
        // header — those are predominantly chat sessions, and keeping env-context
        // for a misattributed surface only costs payload size, not correctness.
        if (this.vendorClient) {
            return matchesAnyFragment(this.vendorClient, ANTHROPIC_CHAT_HOST_VENDOR_FRAGMENTS)
        }
        return matchesAnyFragment(this.userAgent, ANTHROPIC_UI_HOST_USER_AGENT_FRAGMENTS)
    }

    get capabilities(): ClientCapabilities {
        if (!this._capabilities) {
            this._capabilities = this._resolveCapabilities()
        }
        return this._capabilities
    }

    private _resolveCapabilities(): ClientCapabilities {
        const resolved: ClientCapabilities = { ...DEFAULT_CLIENT_CAPABILITIES }
        for (const override of CLIENT_CAPABILITY_OVERRIDES) {
            if (
                matchesAnyFragment(this.clientName, override.fragments) ||
                matchesAnyFragment(this.userAgent, override.userAgentFragments ?? [])
            ) {
                Object.assign(resolved, override.capabilities)
            }
        }
        return resolved
    }
}

export function isCliModeEnabledClient(clientName: string | undefined): boolean {
    return new MCPClientProfile({ clientName }).isCliModeEnabled()
}

export function isLegacyDialectOnlyClient(clientName: string | undefined): boolean {
    return new MCPClientProfile({ clientName }).isLegacyDialectOnly()
}

export function isPostHogCodeConsumer(mcpConsumer: string | undefined): boolean {
    return new MCPClientProfile({ consumer: mcpConsumer }).isPostHogCodeConsumer()
}

export function isToolsModeClient(clientName: string | undefined, userAgent?: string | undefined): boolean {
    return new MCPClientProfile({ clientName, userAgent }).isToolsModeClient()
}