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

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.