Installing the MCP Analytics SDK

Requirements

• Node.js 20.20+ or 22.22+ (TypeScript/JavaScript), Python 3.10+ – see Python below – or Ruby 3.0+ – see Ruby below (experimental and unsupported)
• An MCP server built on either TypeScript SDK major – @modelcontextprotocol/sdk (v1) or @modelcontextprotocol/{core,server,client} (v2) – either official Python MCP SDK major (mcp>=1.26,<3), or the official Ruby MCP SDK (mcp gem >= 1.4, experimental and unsupported). jlowin's standalone fastmcp package is also supported. See MCP SDK v2. (Running a custom dispatcher with no server object to wrap? See Custom servers.)
• A PostHog project token (phc_…)

AI wizard

The wizard installs the package, adds your posthog-node client, and configures instrument(). It also supports LLM coding agents, such as Cursor and Bolt:

For manual installation, follow the steps below.

Install

npm install @posthog/mcp posthog-node
# or pnpm add @posthog/mcp posthog-node
# or yarn add @posthog/mcp posthog-node

Pass your posthog-node client to instrument() as the required second argument. This follows the @posthog/ai pattern. You manage the client lifecycle. Call posthog.shutdown() or posthog.flush() to send queued events.

Wrap your server

Call instrument(server, posthog, options?) once per server. The posthog client is required. The options argument is optional. The function returns an analytics handle for custom events. A second call on the same server logs a warning and returns early.

Both SDKs capture intent, models, and exceptions and enable conversation IDs by default. Missing-capability reporting and agent feedback are opt-in.

Low-level Server

If you registered your tools against the raw protocol Server from @modelcontextprotocol/sdk/server/index.js:

import { Server } from "@modelcontextprotocol/sdk/server/index.js"
import { PostHog } from "posthog-node"
import { instrument } from "@posthog/mcp"

const server = new Server({ name: "my-mcp-server", version: "1.0.0" })

const posthog = new PostHog(process.env.POSTHOG_PROJECT_TOKEN, {
  host: "https://us.i.posthog.com", // or https://eu.i.posthog.com
})

// register your tools as usual...

const analytics = instrument(server, posthog)

High-level McpServer

Pass the typed McpServer wrapper directly to instrument(). The SDK unwraps it and adds a proxy to _registeredTools. This proxy also instruments tools that you register later:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
import { PostHog } from "posthog-node"
import { instrument } from "@posthog/mcp"

const server = new McpServer({ name: "my-mcp-server", version: "1.0.0" })

const posthog = new PostHog(process.env.POSTHOG_PROJECT_TOKEN, {
  host: "https://us.i.posthog.com",
})

const analytics = instrument(server, posthog)

server.tool("search_events", { /* ... */ }, async (args) => {
  // your handler runs untouched
})

import { McpServer } from "@modelcontextprotocol/server"
import { PostHog } from "posthog-node"
import { instrument } from "@posthog/mcp"

const server = new McpServer({ name: "my-mcp-server", version: "1.0.0" })

const posthog = new PostHog(process.env.POSTHOG_PROJECT_TOKEN, {
  host: "https://us.i.posthog.com",
})

const analytics = instrument(server, posthog)

server.registerTool("search_events", { /* ... */ }, async (args) => {
  // your handler runs untouched
})

Options, callbacks, and events work the same on both majors. See MCP SDK v2 for the differences.

Next.js / Vercel (mcp-handler)

mcp-handler provides a standard McpServer in its setup callback. Call instrument() in that callback, before or after you register tools:

import { createMcpHandler } from "mcp-handler"
import { PostHog, instrument } from "@posthog/mcp"

// Create the client once at module scope (not per request).
const posthog = new PostHog(process.env.POSTHOG_PROJECT_TOKEN, {
  host: "https://us.i.posthog.com", // or https://eu.i.posthog.com
})

const handler = createMcpHandler(
  (server) => {
    instrument(server, posthog)
    server.registerTool("roll_dice", { /* ... */ }, async ({ sides }) => { /* ... */ })
  },
  {},
  { basePath: "/api" },
)

export { handler as GET, handler as POST }

Grouping a client's calls

On Vercel, mcp-handler creates a new server for each request and provides no Mcp-Session-Id header. Without another correlation signal, the SDK assigns a separate $session_id to each request.

Use identify to group calls by user. Return a distinctId from your authentication data, such as the OAuth subject. The SDK uses this value as distinct_id across requests. This requires no client changes:

instrument(server, posthog, {
  identify: (request, extra) => ({ distinctId: getUserId(extra) }),
})

enableConversationId is on by default. The SDK adds a conversation_id argument and returns a handle in eligible tool results. The tool schema asks the agent to reuse this handle. Correlation is best-effort because some clients ignore the handle or treat tool output as untrusted content.

If this behavior doesn't suit your client, set enableConversationId: false and use identify for user-level grouping.

Flushing

posthog-node batches events. A serverless function can freeze before the client sends them. Call await posthog.flush() at the end of each invocation. On supported platforms, ctx.waitUntil(posthog.flush()) keeps the runtime active until the flush completes.

NestJS (@rekog/mcp-nest)

@rekog/mcp-nest creates the server through McpModule.forRoot(...). You define tools with @Tool() decorators. Add instrumentMutator to the module's serverMutator hook:

import { Module } from "@nestjs/common"
import { McpModule } from "@rekog/mcp-nest"
import { PostHog, instrumentMutator } from "@posthog/mcp"

// Create the client once at module scope.
const posthog = new PostHog(process.env.POSTHOG_PROJECT_TOKEN, {
  host: "https://us.i.posthog.com", // or https://eu.i.posthog.com
})

@Module({
  imports: [
    McpModule.forRoot({
      name: "my-mcp-server",
      version: "1.0.0",
      serverMutator: instrumentMutator(posthog),
    }),
  ],
})
export class AppModule {}

instrumentMutator(posthog) calls instrument() and returns the server. It does not return the analytics handle. The SDK also captures tools that mcp-nest registers after the mutator runs.

instrumentMutator(posthog) uses the same defaults, including on fresh server instances. Conversation correlation requires the agent to echo the handle.

If you need the analytics handle for custom events, call instrument() directly inside the mutator and return the server yourself:

serverMutator: (server) => {
  const analytics = instrument(server, posthog)
  // ...use `analytics.capture(...)` elsewhere...
  return server
}

Stateless and multi-pod servers

A stateless server creates a new instance for each request, often on a different pod. Without correlation, each request gets its own $session_id. Client name and version arrive only at initialize, so later events lose these values.

The SDK requires no shared session store or sticky routing. At initialize, it creates a token that contains the session ID and client metadata. It sends this token in the Mcp-Session-Id response header. Clients resend the header on later requests, so any pod can read the same values. No client changes are required.

Streamable HTTP needs enableJsonResponse: true

The SDK can send its session token only in JSON mode. In SSE mode, StreamableHTTPServerTransport creates response headers before your initialize handler runs. The token is missing from the response. Without another correlation signal, the SDK assigns a session per request:

new StreamableHTTPServerTransport({
  sessionIdGenerator: undefined, // stateless
  enableJsonResponse: true,      // lets the SDK mint the session header
})

Use a fresh transport per request, which stateless mode requires anyway. With @rekog/mcp-nest, set the same option on the module: streamableHttp: { statelessMode: true, enableJsonResponse: true }.

If you must stream (SSE)

Set the header yourself at the HTTP layer with encodeSessionId, reading clientInfo off the initialize body. The SDK decodes it either way:

import { MCP_SESSION_HEADER, encodeSessionId, newSessionId } from "@posthog/mcp"

// after parsing the POST body, before flushing response headers:
if (body?.method === "initialize" && !req.headers[MCP_SESSION_HEADER]) {
  res.setHeader(
    MCP_SESSION_HEADER,
    encodeSessionId({
      sessionId: newSessionId(),
      clientName: body.params?.clientInfo?.name,
      clientVersion: body.params?.clientInfo?.version,
    })
  )
}

When you can't use a session token

Some frameworks create the transport without exposing enableJsonResponse. Some clients ignore the session header. Either case can produce a separate session per request.

Use identify to group calls by distinct_id without client cooperation. Conversation IDs group calls by conversation when the agent echoes the handle.

Python

The Python MCP Analytics SDK is part of posthog, like posthog.ai. Install the package:

pip install posthog

instrument() requires mcp or fastmcp at runtime. These are peer dependencies, not bundled packages. The SDK detects both official mcp majors (mcp>=1.26,<3) and supports jlowin's standalone fastmcp. Custom dispatchers that use PostHogMCP require only posthog.

instrument(server, posthog_client, options?) works with every common Python MCP server:

• FastMCP and the low-level Server from the official modelcontextprotocol/python-sdk (the mcp package, 1.x)
• MCPServer – FastMCP's new name on mcp 2.x – and the v2 low-level Server, see MCP SDK v2
• jlowin's standalone FastMCP 2.0 (the separate fastmcp package)
• PostHogMCP for custom dispatchers with no server object (see below)

from posthog import Posthog
from posthog.mcp import instrument
from mcp.server.fastmcp import FastMCP

posthog = Posthog(
    "phc_your_project_api_key",
    host="https://us.i.posthog.com",  # or https://eu.i.posthog.com
)
server = FastMCP("my-server")

# On MCP SDK 2.x, FastMCP was renamed — instrument() works the same:
# from mcp.server.mcpserver import MCPServer
# server = MCPServer("my-server")

# register your tools as usual...

analytics = instrument(server, posthog)

Options are passed as MCPAnalyticsOptions, the snake_case equivalent of the TypeScript options:

from posthog.mcp import instrument
from posthog.mcp.types import MCPAnalyticsOptions, UserIdentity

instrument(server, posthog, MCPAnalyticsOptions(
    report_missing=True,          # register the get_more_tools virtual tool
    identify=lambda request, extra: UserIdentity(distinct_id="user_123"),
))

MCPAnalyticsOptions fields (the TypeScript Configuration table below uses camelCase – these are the Python names):

Stateless and multi-pod servers

A stateless Python deployment has the same correlation problem. The SDK creates a session token in the Mcp-Session-Id header. Clients resend it on later requests. The ASGI layer supports JSON and SSE, so Python does not need enableJsonResponse.

On official mcp.server.fastmcp and jlowin's fastmcp 2.0, instrument() wraps the streamable_http_app() and sse_app() factories. These factories also serve run(). Set the server to stateless mode:

server = FastMCP("my-server", stateless_http=True)
instrument(server, posthog)
server.run(transport="streamable-http")  # or: app = server.streamable_http_app()

When you build the ASGI app yourself – a low-level Server, or a custom PostHogMCP dispatcher – add the middleware to that app once:

from posthog.mcp import PostHogMcpStatelessSessionMiddleware

app.add_middleware(PostHogMcpStatelessSessionMiddleware)

Flushing on exit

The posthog client batches events asynchronously. You manage its lifecycle. instrument() schedules captured events in the background.

At shutdown, call await analytics.flush() to wait for pending captures. Then call posthog.shutdown() to send queued events and stop the client. posthog.flush() sends queued events without stopping it. See the complete Python example:

analytics = instrument(server, posthog)
# ... serve ...
await analytics.flush()   # drain in-flight auto-capture events
posthog.shutdown()        # flush + stop the posthog client

Custom dispatchers (no server object to wrap)

For a custom dispatcher, use PostHogMCP, a posthog client subclass that does not require an MCP server object. Call its capture methods to create events. Use prepare_tool_list() and prepare_tool_call() for intent capture. It uses the same events, redaction, and truncation as instrument(). See the custom dispatcher example.

Ruby

A Ruby SDK ships inside the posthog-ruby gem, so there's nothing extra to install:

gem "posthog-ruby"

PostHog::MCP.instrument needs the official Ruby MCP SDK at runtime, but you already have it – you built your server with the mcp gem (>= 1.4) – so it's treated as a peer dependency rather than bundled. (PostHog::MCP::Client for custom dispatchers needs nothing beyond posthog-ruby.)

PostHog::MCP.instrument(server, client, **options) wraps an MCP::Server, whether you register tools as MCP::Tool classes or with define_tool, and works over the stdio and Streamable HTTP transports:

require "posthog/mcp"

posthog = PostHog::Client.new(
  api_key: "phc_your_project_api_key",
  host: "https://us.i.posthog.com" # or https://eu.i.posthog.com
)
server = MCP::Server.new(name: "my-server", version: "1.0.0", tools: [SearchEvents])

# register more tools, prompts, and resources as usual...

analytics = PostHog::MCP.instrument(server, posthog)

If your app already uses posthog-rails and calls PostHog.init, leave the client out and the SDK picks up PostHog.client for you:

PostHog::MCP.instrument(server)

Options are keyword arguments:

PostHog::MCP.instrument(
  server, posthog,
  context: true,                 # inject the `context` intent argument (default)
  report_missing: true,          # advertise the get_more_tools virtual tool
  enable_conversation_id: true,  # stitch calls across reconnects and pods
  identify: ->(request, extra) { { distinct_id: "user_123", properties: { plan: "pro" } } }
)

The injected arguments are stripped before your tool's call receives its keywords, so a tool declared as def self.call(query:, server_context:) keeps working. A tool that declares context in its own input_schema keeps it. A tool whose input_schema is composed (oneOf, allOf, anyOf) or a $ref gets no injected arguments.

Events are truncated to fit the 32 KB message limit of the posthog-ruby client, because the client drops larger messages when it sends a batch.

instrument returns an analytics handle for custom events: analytics.capture("feedback_submitted", { rating: 5 }). Call it from the tool body. On Ruby 3.2+ it also works from a thread or fiber that the tool starts. On Ruby 3.0 and 3.1 such an event gets its own $session_id on HTTP servers.

Prompt and resource traffic is captured too, as $mcp_prompt_get, $mcp_prompts_list, $mcp_resource_read, and $mcp_resources_list.

$lib on Ruby events

MCP events report $lib: "posthog-ruby-mcp" so you can tell them apart from the rest of your traffic. This is set per event: the client you pass in keeps its own $lib (posthog-ruby or posthog-rails) for everything else it sends, so instrumenting an MCP server inside a Rails app doesn't relabel the app's other events.

Stateless and multi-pod servers

A stateless server keeps nothing between requests, often on a different pod each time. Left alone, every request becomes its own $session_id, and the client name and version (only sent at initialize) go missing from every event after the handshake.

The SDK handles this with no session store and no sticky routing. When MCP::Server::Transports::StreamableHTTPTransport runs with stateless: true, the SDK mints the Mcp-Session-Id response header at initialize as a token carrying the session ID and client identity. Clients replay that header on every request, so any pod reads the same values back. Nothing changes on the client side, and there's nothing to configure.

When you build the Rack app yourself, add the middleware once:

use PostHog::MCP::RackMiddleware

It reads neither the request nor the response body: it publishes the request's headers to the instrumented server below it and carries back the token that server minted once the handshake succeeded. The decoded token is exposed to your app as env["posthog_mcp.session"]. (Dispatching MCP requests by hand, with no MCP::Server to wrap? Then you mint it yourself – see Custom servers.)

Stateful HTTP servers need nothing: the transport's own session ID is hashed deterministically, so a session survives restarts. Conversation IDs work too and need no middleware at all.

Flushing on exit

Captured events go straight into the posthog-ruby client's queue, so there's nothing to drain besides the client itself. Call posthog.flush or posthog.shutdown when your process stops:

at_exit { posthog.shutdown }

Logging on stdio servers

A stdio MCP server owns $stdout for the protocol. The integration's own messages go only to the logger: you pass (nowhere by default); the experimental notice and misconfiguration warnings go to stderr. Point the core SDK's logger away from stdout too:

PostHog::Logging.logger = Logger.new($stderr)

Dispatching MCP requests without an MCP::Server? See Custom servers.

Configuration

The posthog client is passed as the required second positional argument – not in this options object. instrument() accepts these options as an optional third argument:

Capture the calling model

Model capture is enabled by default in both SDKs. The SDK reads recognized client metadata first, then falls back to the agent's llm_model argument. Events include $mcp_llm_model and $mcp_llm_model_source ("client_metadata" or "self_reported").

The recognized metadata field is Codex's params._meta["x-codex-turn-metadata"].model. Other clients can provide the llm_model argument.

Use this unverified client input to compare tool quality, latency, and errors by model. Don't use it for billing or security decisions. Missing, blank, and unknown values are omitted. Reasoning effort isn't captured.

To disable model capture, conversation IDs, or both, set the corresponding options to false:

instrument(server, posthog, {
  captureModel: false,
  enableConversationId: false,
})

from posthog.mcp.types import MCPAnalyticsOptions

instrument(server, posthog, MCPAnalyticsOptions(
    capture_model=False,
    enable_conversation_id=False,
))

Graceful shutdown

The posthog-node client queues and batches events asynchronously. You manage its lifecycle. Call posthog.shutdown() from your SIGTERM or beforeExit handler to send queued events:

import { PostHog } from "posthog-node"
import { instrument } from "@posthog/mcp"

const posthog = new PostHog(process.env.POSTHOG_PROJECT_TOKEN)
instrument(server, posthog)

process.on("SIGTERM", async () => {
  await posthog.shutdown()
  process.exit(0)
})

Call posthog.flush() to send queued events without stopping the client.

In serverless or edge environments, flush at the end of each invocation because SIGTERM may not run. Use await posthog.flush(). On supported platforms, use ctx.waitUntil(posthog.flush()).

What happens after install

As soon as the wrapper is in place, instrumented MCP requests emit PostHog events:

• $mcp_tool_call per tool invocation
• $mcp_tools_list per tools/list response
• $mcp_initialize per 2025-11-25 client handshake
• $exception whenever a tool throws or returns isError: true

Both SDKs also capture resource discovery and reads. Resource bodies pass through unchanged and aren't captured. See the event reference for SDK coverage. Prompt requests don't emit automatic analytics yet.

On 2025-11-25, calls keep their MCP protocol session until the agent echoes a valid conversation handle. On 2026-07-28, there is no protocol session. Conversation IDs are enabled by default, but calls only stay correlated when the agent echoes the handle. See the event reference for the full catalog.