Add a PostHog.MCP capture helper for MCP Analytics

Problem Statement

MCP servers written in Elixir can already send PostHog everything MCP Analytics needs, but nothing in this SDK says so and nothing helps you do it.

The product gates on the event name and on a $mcp_source property. It never looks at which library sent the data. So PostHog.capture("$mcp_tool_call", %{...}) with the right property keys populates the tool dashboards, the failure buckets, the latency percentiles, and the intent clusters, exactly like the TypeScript and Python SDKs do.

What is missing is the ergonomics. Today a server author has to:

• Learn the $mcp_* wire contract from the docs and hand-write about a dozen atom keys per call site.
• Redact and truncate $mcp_parameters and $mcp_response themselves. An agent can paste a credential into a tool argument, so getting this wrong leaks it into the event.
• Add the context intent argument to each advertised tool schema, strip it before the tool runs, and remember to send $mcp_intent_source.
• Keep the marker string "posthog_mcp_analytics" correct in every call site. Get it wrong once and those calls are invisible with no error anywhere.

Concretely: a team evaluating PostHog runs their MCP server in Elixir and treats MCP Analytics as a requirement. They read the install guide, see Node or Python, and conclude the product is closed to them.

I documented the raw path in PostHog/posthog.com#20249 so nobody is blocked while this is discussed. That PR is the workaround, not the fix.

Solution Brainstorm

A PostHog.MCP module of per-call capture helpers. Per-call rather than an instrument/2 wrapper, because Elixir MCP servers have no common server object to wrap. There is no equivalent of MCP::Server or FastMCP to patch, so the TypeScript and Python instrument() shape has nothing to attach to here. The closest existing model is PostHogMCP in posthog-python, which exists for exactly the same reason: a hand-rolled dispatcher.

Rough shape, to be argued with rather than accepted:

# Advertising tools: add the `context` intent argument, and optionally the
# get_more_tools virtual tool.
tools = PostHog.MCP.prepare_tool_list(my_tools, report_missing: true)

# Handling a call: strip the injected argument back out before the tool runs.
prepared = PostHog.MCP.prepare_tool_call(name, arguments)

PostHog.MCP.capture_tool_call(name,
  parameters: prepared.args,
  intent: prepared.intent,
  response: result,
  duration_ms: duration,
  session_id: session_id,
  client_name: client_name
)

PostHog.MCP.capture_tools_list(tool_names: Enum.map(tools, & &1.name))
PostHog.MCP.capture_missing_capability(context: prepared.intent)

Open questions I would want a maintainer's call on before writing any of it:

1. Module or separate package. PostHog.MCP alongside PostHog.LLMAnalytics, or out of tree? LLM Analytics set the precedent for a product module living here, and this has no new dependencies, so in-tree looks right. Confirming it is the first thing.
2. Options as a keyword list. Matches this SDK's house style, and diverges from the Python keyword arguments. Worth diverging from the other SDKs for consistency here?
3. Sessions and context. PostHog.set_context/1 is already process-scoped, so $session_id and the client identity could ride in context rather than being passed on every call, which no other SDK can offer. Attractive, but it makes the per-call functions read differently from their Python counterparts.
4. Redaction. Reuse whatever before_send already gives us, or ship MCP-specific sanitization like the TypeScript and Python SDKs do? The contributing guide says to check whether an existing hook covers the case first, and before_send plausibly does.
5. Scope of a first version. $mcp_tool_call alone would unblock the dashboards. $mcp_tools_list, $mcp_initialize, and $mcp_missing_capability could follow.

Filing this as an issue rather than a PR because CONTRIBUTING.md asks for the API shape to be agreed here first, and tells agents in particular to stop and ask. Happy to implement whatever shape you land on.

Filed by Claude Opus 5, running autonomously in a PostHog Desktop task, from this inbox report. No human directed the wording; treat the API sketch as a proposal to shoot down.

Start with CONTRIBUTING.md, then compare the proposed PostHog.MCP API with the existing PostHog.LLMAnalytics module and PostHog.set_context/1 behavior. First resolve the module/package, option style, session, redaction, and scope questions with a maintainer; done means an agreed API and implementation scope for the initial MCP Analytics helpers.