Instrumenting a custom server

instrument() works by wrapping a @modelcontextprotocol/sdk Server or McpServer — it patches that object's request handlers. But not every MCP server is built that way. If you run a custom dispatcher — a Hono or Express HTTP handler, a Cloudflare Worker / Vercel edge function, or anything that speaks the MCP protocol without the SDK's server abstraction — there's no object for instrument() to wrap.

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 $exception fan-out.

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
})

Because it is a PostHog client, every option and method you already know is available — including beforeSend (which runs on the MCP events too) and enableExceptionAutocapture (set it to false to stop errored tool calls from fanning out a $exception). The wrapping-path hooks (identify, context, intentFallback, eventProperties) don't apply here: there's no wrapped server to run them against, so you pass identity and properties on each call instead.

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 and enableExceptionAutocapture isn't false, the error you pass becomes the $exception sibling event (if you don't pass one, a generic exception is synthesized 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 — captureModel and the injected llm_model argument are currently available only through instrument() on a supported TypeScript server wrapper (and, experimentally, capture_model: on Ruby). Don't add $mcp_llm_model manually.

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

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, **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,
            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,
        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 and the SDK reads $mcp_error_message and $mcp_error_type off the exception, so the failures view shows why a call failed instead of an empty row. The message is sanitized and capped at 2048 characters. Add error_type="timeout" (or any low-cardinality label) to override the thrown class name with your own category. Requires posthog>=7.41; upgrade to 7.45.3 or later, which also unwraps the generic ToolError that mcp>=2.1 raises in place of your exception.

Attributing the caller

clientInfo.name reports claude-code from the CLI, the Agent SDK, the VS Code extension and the desktop app alike, so on its own it collapses every surface into one bucket and the harness breakdown reads mostly "Other". The distinguishing detail is in the raw transport headers, which a custom dispatcher has to pass itself (instrument() reads them off the request for you):

• 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 the products, not surfaces within one: claude.ai web, desktop, and mobile connectors all arrive through Anthropic's server-side fetcher with the same header value, so they share the single "Claude.ai" label.

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

Stateless / multi-pod dispatchers

On a stateless deployment (a fresh server per request, often across pods) there's no connection to carry a session, so $session_id fragments and the client name/version — sent only at initialize — go missing from later requests. Add the mint middleware to your ASGI app once. It mints a self-encoded token onto the Mcp-Session-Id response header at initialize and decodes the client's replay on every later request, so every pod recovers the same values with no shared store:

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 carries only what the client volunteered at initialize — treat $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.

Step 2: Prepare each tool call

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

• args: the arguments without the injected context, so your tool never sees it
• intent and intent_source: the agent's stated reason, ready to capture
• is_missing_capability: true when the agent called the get_more_tools virtual tool

prepared = posthog.prepare_tool_call(name, arguments)

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

result = run_tool(name, prepared.args)

Step 3: Capture what happened

After the tool runs, call capture_tool_call. Pass the prepared intent, 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. At initialize it mints an Mcp-Session-Id token, clients replay it on every request, and the decoded token is available as env["posthog_mcp.session"], so session_id: env["posthog_mcp.session"]&.session_id. If you already issue your own session header, 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.