Ruby MCP Analytics installation

PostHog::MCP ships inside the posthog-ruby gem. It instruments an MCP::Server from the official Ruby MCP SDK (mcp gem >= 1.4), whether you register tools as MCP::Tool classes or with define_tool. It works over stdio and Streamable HTTP, and serves both the 2025-11-25 and 2026-07-28 protocol revisions.

You need Ruby 3.0+ and a PostHog project token. Dispatching MCP requests without an MCP::Server? See Custom dispatchers.

Log to stderr on stdio servers

A stdio MCP server uses $stdout for the protocol. The SDK's own messages go only to the logger: you pass. The experimental notice and configuration warnings go to stderr. Point the core SDK's logger away from stdout too:

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

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, and events after initialize lose the client name and version.

When MCP::Server::Transports::StreamableHTTPTransport runs with stateless: true, the SDK puts a token in the Mcp-Session-Id response header at initialize. The token carries the session ID and client metadata. Clients send it back, so any pod reads the same values. There's nothing to configure.

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

use PostHog::MCP::RackMiddleware

The middleware reads no request or response body. The decoded token is available to your app as env["posthog_mcp.session"].

Stateful HTTP servers need nothing. The SDK hashes the transport's session ID, so a session survives restarts. On 2026-07-28 requests, the SDK never sends Mcp-Session-Id, so use conversation IDs or identify to group calls there.

Configuration

Pass options as keyword arguments:

PostHog::MCP.instrument(
  server, posthog,
  report_missing: true,
  identify: ->(request, extra) { { distinct_id: "user_123", properties: { plan: "pro" } } }
)

Callbacks receive extra["headers"], a Hash with lowercase keys on HTTP transports and an empty Hash on stdio:

identify = lambda do |_request, extra|
  resolve_user(extra["headers"]["authorization"])
end

The SDK removes the arguments it adds before your tool's call runs, so 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 uses oneOf, allOf, anyOf, or $ref gets no added arguments.

Events are truncated to the 32 KB message limit of posthog-ruby, because the client drops larger messages. MCP events report $lib: "posthog-ruby-mcp". The client you pass in keeps its own $lib for everything else it sends.

Custom dispatchers

Use this only when your app handles the MCP protocol itself: a Rack or Rails endpoint that parses the JSON-RPC body and routes tools/list and tools/call by hand, without an MCP::Server.

PostHog::MCP::Client is a PostHog::Client subclass. Create it once, and use it for everything else too. It needs nothing beyond posthog-ruby:

require "posthog/mcp"

posthog = PostHog::MCP::Client.new(
  api_key: ENV.fetch("POSTHOG_PROJECT_TOKEN"),
  host: "https://us.i.posthog.com"
)

It also takes missing_capability_tool_name:, mcp_exception_autocapture:, and capture_model:. This path doesn't add conversation IDs.

1. Prepare the tool list

When you answer tools/list, pass your tool descriptors through prepare_tool_list. It returns new Hashes and leaves yours unchanged:

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

It adds a required context argument and an optional llm_model argument to every tool. With report_missing: true, it also adds the get_more_tools tool. Pass context: false or capture_model: false to skip an argument.

2. Prepare each tool call

Before the tool runs, pass its name, the raw arguments, and its own inputSchema through prepare_tool_call. The result has args without the added arguments, intent and intent_source, llm_model and llm_model_source, and is_missing_capability:

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
end

With input_schema:, a context or llm_model field that your tool declares stays in args. Without it, the SDK always removes both names.

3. Capture the call

After the tool runs, call capture_tool_call. On a failure, pass error: with the exception or a message. The SDK sets $mcp_error_type and $mcp_error_message, and emits $exception:

started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
begin
  result = run_tool(name, prepared.args)
rescue StandardError => e
  posthog.capture_tool_call(
    name,
    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,
  llm_model: prepared.llm_model,
  llm_model_source: prepared.llm_model_source,
  parameters: prepared.args,
  response: result,
  duration_ms: (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000,
  distinct_id: user_id
)

4. Attribute the caller

Every capture method takes the same keywords. Pass them on every call:

For session_id:, add use PostHog::MCP::RackMiddleware. When you accept an initialize, call the 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"]
)

The middleware sends the token in the Mcp-Session-Id header. On later requests, pass session_id: env["posthog_mcp.session"]&.session_id. The hook is nil when the client already sent a token back, and returns nil for a 2026-07-28 client. If you issue your own session header instead, pass PostHog::MCP.derive_session_id_from_mcp_session(your_id), so one connection always maps to one $session_id.

5. Flush

Call posthog.flush at the end of a short-lived request handler, or posthog.shutdown when the process stops.