Skip to content

feat(mcp): add event_options to MCP capture calls and instrument - #1206

Merged
eli-r-ph merged 3 commits into
eli/v1-sdk-lib-per-eventfrom
eli/v1-mcp-event-options
Nov 9, 2026
Merged

eli-r-ph merged 3 commits into
eli/v1-sdk-lib-per-eventfrom
eli/v1-mcp-event-options

Conversation

@eli-r-ph

@eli-r-ph eli-r-ph commented Nov 8, 2026

Copy link
Copy Markdown
Contributor

💡 Motivation and Context

MCP events had no way to carry capture options: the MCP capture methods took no options, and instrument() had no hook for them. This adds event_options, named so it does not clash with the existing instrument(..., options=MCPAnalyticsOptions).

Stacked on #1202.

  • PostHogMCP.capture_tool_call, capture_initialize, capture_tools_list, capture_missing_capability, capture_feedback and McpAnalytics.capture take a keyword-only event_options dict.
  • MCPAnalyticsOptions.event_options (added last, so positional construction still works) is a (request, extra) callback, sync or async, called for the same auto-captured events as event_properties, including the $exception sibling.
  • Per-call options win over the callback's key by key. An event without an identity still always sends process_person_profile: False.
  • A non-dict value, from a call or the callback, is logged and ignored. The event is still sent.
  • PostHogMCP.capture() keeps the core client's options=. The docstrings, migration guide and MCP README say which takes which.
  • Docs: the migration guide gets an MCP analytics section (per-call and callback options, why context options set inside a tool handler miss $mcp_tool_call, copying options in MCP before_send), and the MCP README gets an Event options section.
  • Public API snapshot and a minor changeset.

💚 How did you test it?

New parameterized tests cover per-call options on every capture method, the callback on every auto-capture call site (sync and async, identified and anonymous), the precedence rules, non-dict and raising callbacks, before_send seeing the merged options, and the v1 wire payload. They fail without the source change and pass with it. The MCP suite and test_client.py pass on mcp 1.30 and mcp 2.3. ruff, mypy and the public API check pass. The full suite has three fork tests that also fail on macOS without this change.

📝 Checklist

  • All commits are signed (see Commit signing)
  • I reviewed the submitted code.
  • I added tests to verify the changes.
  • I updated the docs if needed.
  • No breaking change or entry added to the changelog.

If releasing new changes

  • Ran sampo add to generate a changeset file (minor changeset written by hand)

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Claude Code, Claude Opus 5.5. The API name and precedence were set by the maintainer. Through the public API, per-call options and the callback never apply to the same event today: the callback runs only for auto-captured events, and per-call options exist only on the capture methods. The builder still merges them in the agreed order, and a pipeline test covers it.

🤖 Generated with Claude Code

eli-r-ph and others added 2 commits November 7, 2026 17:39
The PostHogMCP capture_* methods and McpAnalytics.capture take a
keyword-only event_options argument, and MCPAnalyticsOptions gains an
event_options callback, called for the same events as event_properties.
Per-call options win over the callback's key by key, and an event
without an identity still always sends process_person_profile: False.
A non-dict value is logged and ignored.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Covers the per-call argument and the callback, why context options set
inside a tool handler miss $mcp_tool_call, copying options in MCP
before_send, and the options vs event_options split on PostHogMCP.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@eli-r-ph eli-r-ph self-assigned this Nov 8, 2026
@eli-r-ph
eli-r-ph marked this pull request as ready for review November 8, 2026 03:20
@eli-r-ph
eli-r-ph requested a review from a team as a code owner November 8, 2026 03:20

@marandaneto marandaneto left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The code looks good; no qualifying findings. Verdict: correct.

* feat(celery): propagate context options to workers

Publish context options in an X-POSTHOG-CONTEXT-OPTIONS task header,
next to the tags header, and set them as context options on the worker
before the task started event. propagate_context=False sends none.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(celery): point eager tasks to explicit PostHog headers

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(ai): take capture options in the AI integrations (#1208)

* feat(ai): take capture options in the AI integrations

Every AI wrapper method that takes posthog_properties also takes
posthog_options, and the Gemini clients take it as a per-client
default. LangChain's CallbackHandler and PostHogMiddleware, and the
OpenAI Agents and Claude Agent SDK instrument() and processors, take
options=. LangChain also reads posthog_options from run metadata.

The wrappers never pass posthog_options to the provider. The options
are sent as the event's own options, below the personless
process_person_profile: False. A value that is not a dict is logged
and ignored, and no options argument is passed when none are set.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(ai): send LangChain exception events with the run's options

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(migration): simplify the 8.0 checklist and MCP hook note

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(ai): pass exception options as a typed keyword

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
@eli-r-ph
eli-r-ph merged commit 81e92e8 into eli/v1-sdk-lib-per-event Nov 9, 2026
@eli-r-ph
eli-r-ph deleted the eli/v1-mcp-event-options branch November 9, 2026 23:40
eli-r-ph added a commit that referenced this pull request Nov 9, 2026
…y context options, AI options (#1202, #1206, #1207, #1208)

Squash of the per-event $lib stack: #1202 (per-event $lib/$lib_version), #1206 (MCP event_options), #1207 (Celery context options to workers) and #1208 (capture options in the AI integrations).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants