Instrumenting a custom server

instrument() wraps the request handlers of a @modelcontextprotocol/sdk Server or McpServer. A custom dispatcher has no server object to wrap. Examples include Hono, Express, Cloudflare Workers, and Vercel edge functions that implement the MCP protocol directly.

For those servers, use PostHogMCP instead. It's a subclass of the posthog-node client, so it's a drop-in replacement for your existing PostHog client. It adds preparation helpers for tool schemas and calls, plus capture methods for tool calls, tool listings, initialization, and missing capabilities. You resolve request metadata and call the matching methods yourself. They build the same canonical $mcp_* events as instrument() and use the same sanitization, truncation, and additional $exception events.

When to use which

The examples below are TypeScript. Python has the same helper with the same methods in snake_case – skip to Python.

Set up

PostHogMCP takes the exact same constructor arguments as posthog-node's PostHog, so swap the class and you keep one client for your whole app:

import { PostHogMCP } from "@posthog/mcp"

const posthog = new PostHogMCP(process.env.POSTHOG_PROJECT_TOKEN, {
  host: "https://us.i.posthog.com", // or https://eu.i.posthog.com
  // standard posthog-node options apply, e.g. beforeSend, enableExceptionAutocapture
})

PostHogMCP provides the standard PostHog client options and methods. Its beforeSend hook also applies to MCP events. Set enableExceptionAutocapture: false to stop additional $exception events for failed calls.

The instrument() hooks (identify, context, intentFallback, eventProperties) do not run on this path. Pass identity and properties on each capture call.

Capture events

Call the matching method from inside your dispatcher, after you've resolved who the user is and run the tool. The methods are fire-and-forget, just like posthog.capture():

// On a tools/call, after the tool runs:
posthog.captureToolCall({
  toolName: "search_events",
  parameters: request.params.arguments,
  response: result,
  durationMs: Date.now() - start,
  isError: false,
  distinctId: user.id,                       // → distinct_id (enables person processing)
  sessionId: mcpSessionId,                    // → $session_id (omitted if you don't pass one)
  protocolVersion: requestProtocolVersion,    // → $mcp_protocol_version
  groups: { organization: user.orgId },       // → $groups
  properties: { $mcp_client_name: "claude-code" }, // any extra props, spread verbatim
})

// Only on a 2025-11-25 initialize handshake:
posthog.captureInitialize({
  clientName: "claude-code",
  clientVersion: "1.2.3",
  protocolVersion: "2025-11-25",
  distinctId: user.id,
})

// Custom events use the inherited posthog-node capture():
posthog.capture({
  distinctId: user.id,
  event: "feedback_submitted",
  properties: { rating: 5 },
})

Fields shared by every method

Tool-call specific fields

toolName -> $mcp_tool_name, toolDescription -> $mcp_tool_description, parameters -> $mcp_parameters, response -> $mcp_response, durationMs -> $mcp_duration_ms, isError -> $mcp_is_error. When isError is true, the SDK emits an additional $exception unless enableExceptionAutocapture is false. It uses the error you supply. If no error is available, it creates a generic exception from the tool name.

What you don't get compared with instrument()

Because there's no wrapped server, PostHogMCP does not manage these for you – you pass the equivalent data per call:

• Sessions – no MCP-session-derived $session_id or inactivity rollover. Pass your own sessionId.
• Identity caching / $identify dedupe – pass distinctId (and optional setProperties) on each call.
• Automatic intent and missing-capability handling – use prepareToolList() and prepareToolCall(), then pass their output to the matching capture method.
• Conversation IDs – pass your own stable sessionId. The custom dispatcher helpers don't inject or echo conversation_id.
• Model capture – enabled by default in both SDKs' preparation helpers. Use prepareToolList() to advertise the argument, then prepareToolCall() to extract it. Pass its llmModel and llmModelSource to captureToolCall(). The experimental Ruby client is opt-in: pass capture_model: true to prepare_tool_list.

For model capture on a fresh dispatcher, pass the application's original tool as originalTool in the preparation options. Pass requestMeta there to capture recognized client metadata. Python uses the equivalent snake_case fields and keyword arguments.

The 2026-07-28 revision has no initialize handshake or protocol session. Don't fabricate $mcp_initialize. Capture each request's protocolVersion. For correlation across requests, pass an authenticated user ID or your own stable session ID.

Everything from the event reference onward – event names, property shapes, sanitization, error tracking – is identical.

Graceful shutdown

PostHogMCP is a posthog-node client, so flush it yourself. In serverless or edge environments, flush at the end of each invocation rather than relying on SIGTERM:

// at the end of the request/invocation
await posthog.flush()
// or keep the runtime alive until the flush completes
ctx.waitUntil(posthog.flush())

Python

The Python SDK ships the same custom-dispatcher path as PostHogMCP, a subclass of the posthog client. Method names are snake_case and arguments are keyword args rather than an options object:

import time
from posthog.mcp import PostHogMCP, get_more_tools_result

posthog = PostHogMCP("phc_your_project_api_key", host="https://us.i.posthog.com")

# Advertise your tools with the injected `context` intent argument (and, optionally,
# the get_more_tools virtual tool):
tools = posthog.prepare_tool_list(my_tools, report_missing=True)

def handle_tools_call(request, name, arguments):
    # Pull the agent's intent off the call and strip the injected `context`:
    prepared = posthog.prepare_tool_call(name, arguments)

    # Pass these on every capture — see "Attributing the caller" below:
    common = dict(
        distinct_id=user_id,
        session_id=mcp_session_id,
        client_user_agent=request.headers.get("user-agent"),
        vendor_client=request.headers.get("x-anthropic-client"),
        groups={"organization": org_id},
    )

    if prepared.is_missing_capability:
        posthog.capture_missing_capability(
            context=prepared.intent,
            llm_model=prepared.llm_model,
            llm_model_source=prepared.llm_model_source,
            **common,
        )
        return get_more_tools_result()

    start = time.monotonic()
    try:
        result = run_tool(name, prepared.args)
    except Exception as exc:
        posthog.capture_tool_call(
            name,
            llm_model=prepared.llm_model,
            llm_model_source=prepared.llm_model_source,
            parameters=prepared.args,
            duration_ms=(time.monotonic() - start) * 1000,
            is_error=True,
            error=exc,  # → $mcp_error_message, $mcp_error_type, and the $exception sibling
            **common,
        )
        raise

    posthog.capture_tool_call(
        name,
        llm_model=prepared.llm_model,
        llm_model_source=prepared.llm_model_source,
        intent=prepared.intent,
        intent_source=prepared.intent_source,
        parameters=prepared.args,
        response=result,
        duration_ms=(time.monotonic() - start) * 1000,
        **common,
    )
    return result

Capture the handshake and the tool listing the same way:

posthog.capture_initialize(client_name="claude-code", client_version="1.2.3", **common)
posthog.capture_tools_list(tool_names=[t["name"] for t in tools], **common)

posthog.flush()  # PostHogMCP is a posthog client — flush/shutdown it yourself

PostHogMCP(api_key, missing_capability_tool_name="get_more_tools", mcp_exception_autocapture=True, **posthog_kwargs) accepts the standard posthog client kwargs – host, and before_send if you need to drop or rewrite payloads. Set mcp_exception_autocapture=False to stop a failed tool call from emitting a $exception sibling. As in TypeScript, the wrapping-path hooks (identify, context, intent_fallback, event_properties) don't apply here – pass identity and properties on each capture_* call.

Failed calls

Pass error=exc with is_error=True to capture $mcp_error_message and $mcp_error_type from the exception. The SDK sanitizes the message and limits it to 2048 characters. Set error_type="timeout", or another category, to replace the exception class name. The SDK also unwraps the generic ToolError from MCP SDK 2.x.

Attributing the caller

clientInfo.name reports claude-code for the CLI, Agent SDK, VS Code extension, and desktop app. That name alone cannot distinguish these clients, so the harness breakdown can show mostly "Other". Custom dispatchers must pass the transport headers below. instrument() reads them automatically:

• client_user_agent -> $mcp_client_user_agent – the parenthetical carries the build (claude-code/2.1.0 (cli) vs (sdk-ts)).
• vendor_client -> $mcp_vendor_client – from vendor headers like x-anthropic-client, the only thing that separates Anthropic's pooled surfaces (Claude.ai, Cowork, Claude Design) from each other. It separates products but cannot distinguish clients within one product. Claude.ai web, desktop, and mobile connectors use the same fetcher and header value. They all receive the "Claude.ai" label.

Both are captured raw and classified at query time, so labels improve without an SDK release. stdio and in-memory transports carry no headers, so leave them unset there.

Stateless / multi-pod dispatchers

A stateless deployment creates a new server per request, often across pods. Without correlation, $session_id differs between requests. Client name and version arrive only at initialize, so later requests lose these values.

Add the session middleware to your ASGI app once. At initialize, it puts a token in the Mcp-Session-Id response header. It decodes the token when clients resend it. Each pod recovers the same values without shared storage:

from posthog.mcp import PostHogMcpStatelessSessionMiddleware, get_mcp_session

app.add_middleware(PostHogMcpStatelessSessionMiddleware)

# ...then in your request handler, feed the recovered session into each capture.
# The token carries the client identity too — pass it as $mcp_client_* properties
# (capture_tool_call takes session_id directly, client name/version via properties):
sess = get_mcp_session(request)  # None until the client replays the token
posthog.capture_tool_call(
    name,
    session_id=sess.session_id if sess else None,
    intent=prepared.intent,
    properties={
        "$mcp_client_name": sess.client_name if sess else None,
        "$mcp_client_version": sess.client_version if sess else None,
    },
)

The token is unsigned and contains only client-provided values from initialize. Use $session_id and $mcp_client_* as analytics labels, not authentication.

Ruby

Do you need this?

If your Ruby server is an MCP::Server from the official mcp gem, you don't: add PostHog::MCP.instrument(server, posthog) and every request is captured. See Ruby.

You need this section only when your app speaks the MCP protocol itself: a Rack or Rails endpoint that parses the JSON-RPC body, routes tools/list and tools/call by hand, and never builds an MCP::Server. There's no object to wrap, so you tell PostHog what happened.

Set up

PostHog::MCP::Client is a PostHog::Client subclass. Create it once, where you create your PostHog client today, and use it for everything else too (capture, feature flags, flush). It needs nothing beyond posthog-ruby, no mcp gem.

require "posthog/mcp"

posthog = PostHog::MCP::Client.new(
  api_key: "phc_your_project_api_key",
  host: "https://us.i.posthog.com" # or https://eu.i.posthog.com
)

Two constructor options are specific to MCP: missing_capability_tool_name: renames the get_more_tools virtual tool, and mcp_exception_autocapture: false turns off the $exception sibling event for failed calls.

Step 1: Prepare the tool list

When you answer tools/list, pass your tool descriptors (the Hashes you return on the wire, with name and inputSchema) through prepare_tool_list. It returns new Hashes; your originals are not changed.

def handle_tools_list
  posthog.prepare_tool_list(MY_TOOLS, report_missing: true)
end

This does two things:

• It adds a required context string argument to every tool. The agent fills it with why it is calling the tool, and you capture that as $mcp_intent in step 2. See Capturing agent intent. Pass context: false to skip it, or context: { description: "..." } to change the prompt.
• With report_missing: true, it appends the get_more_tools virtual tool, so agents can tell you which capability they were missing. See Missing capabilities.

Pass capture_model: true to also add an optional llm_model argument, where the agent reports its model. A tool whose inputSchema is composed (oneOf, allOf, anyOf) or a $ref is returned unchanged.

Step 2: Prepare each tool call

When you answer tools/call, pass the tool name, the raw arguments, and the tool's own inputSchema through prepare_tool_call before you run the tool. It returns a PreparedToolCall with:

• args: the arguments without the injected context and llm_model, so your tool never sees them
• intent and intent_source: the agent's stated reason, ready to capture
• llm_model and llm_model_source: the agent's self-reported model, when you set capture_model: true
• is_missing_capability: true when the agent called the get_more_tools virtual tool

Pass the same inputSchema Hash you gave to prepare_tool_list. If the tool declares its own context or llm_model field, that field then stays in args and is not read as analytics. Without input_schema:, both names are always removed.

prepared = posthog.prepare_tool_call(name, arguments, input_schema: tool[:inputSchema])

if prepared.is_missing_capability
  posthog.capture_missing_capability(context: prepared.intent, distinct_id: user_id)
  return PostHog::MCP.get_more_tools_result # the canned reply the agent expects
end

# Run the tool with prepared.args (see step 3)

Step 3: Capture what happened

After the tool runs, call capture_tool_call. Pass the prepared intent (and llm_model: and llm_model_source:, if you capture the model), the arguments and result, the duration, and whether it failed. On a failure pass error: (the exception, or a message); PostHog fills $mcp_error_type, $mcp_error_message, and emits the $exception sibling.

started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
begin
  result = run_tool(name, prepared.args)
rescue StandardError => e
  posthog.capture_tool_call(
    name,
    intent: prepared.intent,
    intent_source: prepared.intent_source,
    parameters: prepared.args,
    duration_ms: (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000,
    is_error: true,
    error: e,
    distinct_id: user_id
  )
  raise
end

posthog.capture_tool_call(
  name,
  intent: prepared.intent,
  intent_source: prepared.intent_source,
  parameters: prepared.args,
  response: result,
  duration_ms: (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000,
  distinct_id: user_id
)

The other capture methods follow the same shape and map to the events in the event reference:

Step 4: Attribute the caller

Every capture method accepts the same attribution keywords. Pass them on every call so the events for one client group together:

For session_id:, the simplest option is use PostHog::MCP::RackMiddleware in your Rack stack. The middleware reads no request or response body – you already parse the JSON-RPC body yourself – so when you answer an accepted initialize, call the mint hook it leaves in env["posthog_mcp.mint"]:

session = env["posthog_mcp.mint"]&.call(
  client_name: params["clientInfo"]["name"],
  client_version: params["clientInfo"]["version"],
  protocol_version: params["protocolVersion"]
)

posthog.capture_initialize(
  client_name: params["clientInfo"]["name"],
  client_version: params["clientInfo"]["version"],
  protocol_version: params["protocolVersion"],
  session_id: session&.session_id,
  distinct_id: user_id
)

The middleware attaches the minted token to the Mcp-Session-Id response header, clients replay it on every request, and on those requests the decoded token is waiting in env["posthog_mcp.session"] – so everywhere else you just pass session_id: env["posthog_mcp.session"]&.session_id. The hook is absent (nil) when the client already replayed a token, and returns nil for a 2026-07-28 client, which must not be answered with an Mcp-Session-Id. If you issue your own session header instead, pass PostHog::MCP.derive_session_id_from_mcp_session(your_id) so the same connection always maps to the same $session_id.

Step 5: Flush

PostHog::MCP::Client batches events in the background like any posthog-ruby client. Call posthog.flush at the end of a short-lived request handler, or posthog.shutdown when the process stops.