Repository navigation
feat(mcp): group sessions by ChatGPT, Codex and VS Code conversation ids - #1193
lucasheriques wants to merge 11 commits into
Conversation
Read ChatGPT's `_meta["openai/session"]` conversation id as a session source for calls with no conversation handle and no transport session, and stamp `$mcp_session_source` (conversation, transport, client_metadata, generated) on every event whose session the SDK resolves. Why: on per-request stateless servers with `enable_conversation_id=False` (common for ChatGPT/Claude directory submissions) every call got its own `$session_id` (PostHog/posthog#119784). ChatGPT already sends a per-conversation id, so grouping needs no schema or result change. Order is handle, transport (token or mcp id), client id, generated, so it only groups calls that fragment today. A call carrying it mints no handle and gets no prompt-back. Same rule in `PostHogMCP.prepare_tool_call` via `request_meta`, after an explicit `session_id`. Twin of posthog-js 3eb19d9 and ADR-0014; the derivation `ses_35e4cc45ea3e5e1282c3f091de632132` is a cross-SDK contract. Internals: `resolve_session_id_with_source` / `prepare_request` return a `ResolvedSession(session_id, source)`, which the record_* functions take, so the source reaches every event. `token`/`mcp` map to `transport` at the property boundary. `handshake_session_id` becomes `handshake_session`. A client-conversation session never stands in for an unobserved `initialize`, like a conversation one. Tested: `pytest posthog/test/mcp` -> 699 passed, 10 skipped on mcp 1.30.0 and 557 passed, 42 skipped on mcp 2.3.0 (incl. new parameterized test_client_conversation_session.py plus a v1 FastMCP and a v2 wire-level fresh-instance test); `ruff format --check`, `ruff check`, `mypy`, `make public_api_check` clean.
Pre-PR gate findings on the TypeScript twin (posthog-js 26d720abd), applied here: - tools/list, resources/list|read and initialize resolved sessions without the client conversation id, which the spec's session order covers for every event. Each call site now passes it (`params.meta` on request handlers, `_meta` of the initialize params through `handshake_session`). Still per-request, never written to shared state, and it still does not stand in for an unobserved initialize. - Custom events from `McpAnalytics.capture()` now carry `$mcp_session_source`, the instance's own source (`generated`, or `transport` for a token or mcp session id). - `prepare_tool_call(session_id="")` already treated an empty id as absent; a regression case now pins it. Tested: `pytest posthog/test/mcp` -> 714 passed, 11 skipped on mcp 1.30.0 and 570 passed, 45 skipped on mcp 2.3.0 (fastmcp uninstalled); new parameterized cases failed before the fix (12 on mcp 2.3.0); `ruff format --check`, `ruff check`, `mypy`, `make public_api_check` clean.
…ernal tools/list What - ToolCallLifecycle.prime_session now passes the request's client conversation to resolve_session_id, so a call carrying only openai/session returns at the client_metadata step before the memory branch. It no longer refreshes data.last_activity or rotates data.session_id, so ChatGPT calls cannot keep the instance's generated session alive past its inactivity window. - The v2 tools/list wrapper skips analytics when the SDK calls the handler itself. On the 2026-07-28 streamable-HTTP path, mcp 2.3.0 runs tools/list during every tools/call (Mcp-Param-* validation) on a server without get_tool_input_schema (the low-level Server; MCPServer provides it). That call has no _meta, resolved to a fresh generated session, and emitted a phantom $mcp_tools_list. It is detected by the shared HTTP request's required Mcp-Method header naming a different method than the handler's own. Why Pre-PR gate findings on the client-metadata session work; the spec limits events to requests the client sent. Tested - pytest posthog/test/mcp: mcp 1.30.0 716 passed, 11 skipped; mcp 2.3.0 576 passed, 45 skipped (fastmcp uninstalled) - ruff format --check, ruff check, mypy | mypy-baseline filter, make public_api_check: clean - New tests failed before the fixes (instance state moved; phantom event emitted). A real tools/list still emits on both MCPServer and low-level Server.
There was a problem hiding this comment.
PostHog Review · Standard · reviewed 208707d: 1 Must fix.
See this review and its findings in PostHog Review. Comment @posthog review --deep for a Deep review. A Deep review takes longer and looks deeper than a Standard review.
posthog-python Compliance ReportDate: 2026-11-16T22:51:05.440901+00:00 ✅ All Tests Passed!271/271 tests passed Capture_V1 Tests✅ 95/95 tests passed View Details
Capture_Ai Tests✅ 5/5 tests passed View Details
Feature_Flags Tests✅ 17/17 tests passed View Details
Feature_Flags_V4 Tests✅ 150/150 tests passed View Details
Feature_Flags_Local_Evaluation Tests✅ 4/4 tests passed View Details
|
SDK performance: posthog-python2 changes worth reviewing: 2 observed regressions. Flags require at least a 5% change in the median and all six pairs agreeing on direction. This is a noise filter, not proof of a performance change or a CI gate.
View all results
Values are medians of paired measurements. Not flagged does not mean unchanged. Unavailable means a measurement could not be provided, not zero. Estimated allocation measurements retain their instrumentation uncertainty. RSS measures the whole process, not just SDK allocations; observed peaks are sampled checkpoints. Paired ranges in the diagnostics describe variability, not confidence intervals. Each shard uses its own runner; compare Before PR against With PR within a row, not across shards. Compared 102 metric rows; 102 rows shown in all results. Omitted or shortened data remain in |
dustinbyrne
left a comment
There was a problem hiding this comment.
Reproduced a custom-event attribution regression: after a token-bearing request, a metadata-only caller’s in-tool capture can inherit the previous caller’s session and person. The same public-entry test passes on base and fails on this head.
The metadata policy also needs reconciliation with the current canonical MCP specification; the linked spec proposal remains open. Details and executed evidence are inline.
AI-assisted review.
…x, VS Code) Rework the openai/session change to the merged sdk-specs rules (PostHog/sdk-specs 2026-11-04-mcp-client-conversation-ids and -codex-vscode-conversation-ids), matching posthog-js#5577: - _client_conversation.CLIENT_CONVERSATION_ROWS mirrors the spec table: openai/session (1-128 printable ASCII, handle-free), Codex sessionId and VS Code vscode.conversationId (UUID, lowercased, non-nil, handle kept). - A key is read only from a request its row recognizes by User-Agent or client name (_meta clientInfo first, then the adapter's resolved name). - The client id is session source 1, ahead of the handle and transport, on tool calls only (tools/list, resources and initialize no longer read it). A handle echoed with it is stripped but ignored. - A handle-free client's client-facing listing has no conversation_id or _mcp_instructions, and it is minted no handle. The SDK's internal cache pass still injects, so validation stays client-agnostic. - Client- and handle-grouped calls count as connection activity, so a stdio session does not rotate early (gate finding from the JS port). - PostHogMCP: prepare_tool_list/prepare_tool_call take headers (+client_info), capture_tool_call takes request_meta. Tested: pytest posthog/test/mcp 743 passed on mcp 1.30.0, 601 passed on mcp 2.3.0; the new tests cover every spec scenario and vector, including real HTTP fleets over official, fastmcp and lowlevel servers. ruff, mypy (CI mode with baseline) and the public API snapshot pass.
PR overviewThe PR groups MCP sessions using ChatGPT, Codex, and VS Code conversation IDs and defers custom events while conversation handles are being created. One issue has been addressed, and one memory-exhaustion concern remains open. Calls that create conversation handles retain all custom events until the tool finishes, bypassing the client's bounded queue during that period. Bulk or streaming tools that capture events per client-supplied item can therefore cause unbounded SDK memory growth. Open issues (1)
Fixed/addressed: 1 · PR risk: 5/10 Reviews |
- Count a client-grouped call as connection activity only on a one-client connection (no HTTP request, no token, no transport id). On a shared stateless HTTP pod, ChatGPT calls kept the instance session alive and merged two unrelated clients into one $session_id. - PostHogMCP.prepare_tool_list for a handle-free client still records conversation_id ownership, so prepare_tool_call strips an echoed handle like the automatic path does. Tested: both regressions have tests that fail on 02a4815 and pass now; pytest posthog/test/mcp 745 passed on mcp 1.30.0 and 603 on mcp 2.3.0; ruff, mypy (CI mode) and the public API check pass.
There was a problem hiding this comment.
PostHog Review · Standard · reviewed 3cbcd29: 1 Must fix, 2 Should fix. This pull request is large, so the review ran in 4 parts with less depth than usual.
This is review round 3 on this pull request. When findings keep coming back in the same code, the approach is usually the problem. Before the next fix, check whether a different design would remove the whole class of findings.
dustinbyrne
left a comment
There was a problem hiding this comment.
The earlier recognition, bounds and precedence feedback is addressed. The custom-event attribution regression remains and now also reproduces when the second caller supplies its own token.
I also reproduced session/identity merging for handle-free HTTP calls without usable metadata, output-validation failures after mixed-client FastMCP listings, and schema-invalid results after mixed manual listings. The corresponding base controls pass; details are inline.
AI-assisted review.
Resolve conflicts with main's bounded intent scans, unknown-tool event and new_session_id: keep lists_conversation_id and the client-conversation imports, and thread the resolved session through record_unknown_tool so $mcp_unknown_tool carries $mcp_session_source like every other event. Code matches the merged spec plus sdk-specs#185. Tested: uv run pytest posthog/test/mcp (776 passed, 11 skipped); ruff format and check, mypy-baseline filter, public API check, import under -W error all clean. Full suite: 6326 passed, 12 failed outside posthog/mcp (langchain, metrics autocapture fork).
There was a problem hiding this comment.
PostHog Review · Standard · reviewed 08774e9: 1 Must fix. This pull request is large, so the review ran in 4 parts with less depth than usual.
This is review round 4 on this pull request. When findings keep coming back in the same code, the approach is usually the problem. Before the next fix, check whether a different design would remove the whole class of findings.
There was a problem hiding this comment.
Not approved — this change needs a human reviewer.
Re-adding the stamphog label gives the same result unless the changed files change.
Stamphog can't auto-review this pull request because two gates refused it. The deny-list gate flagged it for matching the auth and public_api categories, which fits the session and identity changes in posthog/mcp/session.py, posthog/mcp/_instrumentation.py and posthog/mcp/posthog_mcp.py, and the signature changes recorded in references/public_api_snapshot.txt. The tier gate classified it as T2-never because it is a cross-cutting feature spanning 22 files and 1508 lines. The size gate passed, so size is not the blocker.
Please ask a human reviewer to look at it. Splitting it, for example into the client-conversation parsing module, the session resolution changes, and the PostHogMCP API changes, may make that review easier, but the sensitive areas will still need a human.
- posthog[bot] reviewed the current head.
Gate mechanics and policy version
| Gate | Result | |
|---|---|---|
| prerequisites | ✓ | all clear |
| deny-list | ✗ | matches: auth, public_api |
| size | ✓ | 722L, 13F substantive, 1508L/22F incl. docs/generated/snapshots — within ceiling |
| tier | ✗ | classified as T2-never: T2-never (1508L, 22F, cross-cutting, feat) |
| stamphog 2.7.0 | .stamphog/policy.yml @ unknown · reviewed head 08774e9 |
dustinbyrne
left a comment
There was a problem hiding this comment.
Complete read-only follow-up against current base 133d7d12c3f15b04287b6d8389b0412fb7dfe6de.
The recognition table, validation, namespaced derivation and metadata precedence now match the canonical MCP contract, including automatic session-source reporting. All four required regressions from my prior review still reproduce against this updated base: custom capture inherits the previous caller's identity; missing/empty handle-free HTTP metadata merges sessions and person properties; mixed-client official FastMCP listings turn successful strict output into errors; and manual listing/preparation returns a schema-incompatible result.
I independently reproduced the existing MCP 2.x internal-list ownership report: base passes all four cases; head fails fresh raw HTTP/no-resolver with JSON-RPC -32603, while warm-listing and resolver controls pass. The adversarial pass also identified a tracked public-import removal; the old import/string-return smoke test passes on base and raises ImportError on head.
These are five P1 corrections plus one P2 compatibility correction, so I cannot recommend approval yet. Current CI is green (26 successes, one neutral), but it does not cover these sequences. The exact regressions pass on the current base and fail on this head. Full local suites also have nine identical standalone FastMCP dependency/import failures on both revisions; those are environmental, not additional PR regressions. No live PostHog delivery, provider integration, deployed profile mutation or UI verification was performed.
AI-assisted review.
…s consistent Address the 11-09 review of #1193, checked against sdk-specs main (openspec/specs/mcp-analytics/spec.md): - Priming no longer short-circuits on a client conversation id, so an in-tool McpAnalytics.capture() never reads the previous caller's session or identity. Over HTTP such a call, and a handle-free (ChatGPT) call without a usable id, primes a session reserved for that one request ("request" internally, "generated" on the wire). The metadata-derived id is never stored on shared state, and a one-client connection (stdio, SSE) keeps the process session. - Two handle-free HTTP calls without openai/session no longer share the process session and its cached person properties (spec rule 4). - A listing that declares no _mcp_instructions turns mirroring off, because mcp 1.x validates the next result against the latest listing. Ordinary list, ChatGPT list, ordinary call no longer fails an extra="forbid" result. - PostHogMCP records real ownership on a suppressed listing, so a later ordinary listing declares _mcp_instructions whenever its results carry it. - MCP 2.x internal tools/list dispatch still prepares schemas and caches ownership. It only skips the $mcp_tools_list event. - A finished call grouped by a client id refreshes stdio connection activity. Rotation happens on arrival only. Virtual tools now prime on arrival too. - Restore posthog.mcp.asgi.handshake_session_id as an async str wrapper. Tested, one red-first test per finding: - pytest posthog/test/mcp: mcp 1.30 791 passed / 11 skipped; mcp 2.3 + fastmcp 4.1.8 677 passed / 28 skipped; mcp 2.3 bare 626 passed / 60 skipped. - ruff format --check, ruff check, mypy | mypy-baseline filter, public API check, python -W error -c "import posthog": clean. Reviewer notes: rule 4 is applied only where a handle used to isolate the call. The stateless-route-without-middleware fallback for other clients is unchanged (test_a_route_without_the_middleware_keeps_the_fallback). Separately, an ordinary stdio call longer than 30 minutes is stamped with a rotated session at completion; that predates this PR and is left for its own fix.
There was a problem hiding this comment.
Not approved — this change needs a human reviewer.
Re-adding the stamphog label gives the same result unless the changed files change.
stamphog can't approve this pull request automatically. The deny-list gate refused it because it touches sensitive areas, matching both auth and public_api. This shows up in the session and identity changes under posthog/mcp/ and in the references/public_api_snapshot.txt update. The tier gate also classified it as T2-never: a cross-cutting feature spanning 1875 lines across 23 files, which is never eligible for automated approval.
Please ask a human reviewer to take this one. It would also help to split it up, for example the client-conversation recognition module, the PostHogMCP signature changes, and the $mcp_session_source event property as separate pull requests.
Gate mechanics and policy version
| Gate | Result | |
|---|---|---|
| prerequisites | ✓ | all clear |
| deny-list | ✗ | matches: auth, public_api |
| size | ✓ | 813L, 13F substantive, 1875L/23F incl. docs/generated/snapshots — within ceiling |
| tier | ✗ | classified as T2-never: T2-never (1875L, 23F, cross-cutting, feat) |
| stamphog 2.8.0 | .stamphog/policy.yml @ unknown · reviewed head 5417daa |
dustinbyrne
left a comment
There was a problem hiding this comment.
The six previously reported exact regressions now pass against the updated base. Recognition, derivation and precedence also match the canonical contract.
One overlapping-request isolation regression remains: if Bob finishes while Alice’s async tool is waiting, Alice’s custom capture can use Bob’s session, identity and person properties. The same test passes on base and fails only for overlap on head under both official MCP majors; awaited controls pass. Consider keeping fallback attribution request-local before approval.
Current CI is green but omits this overlap. Validation establishes emitted payloads, not live PostHog delivery or deployed profile changes.
AI-assisted review.
| data.session_id = request_session_id | ||
| data.session_source = "request" | ||
| return ResolvedSession(request_session_id, "request") |
There was a problem hiding this comment.
[P1] Keep custom capture's fallback isolated across overlapping HTTP calls
IMPORTANT · REQUIRED · Introduced/exposed by this PR relative to the merge base.
Location: posthog/mcp/session.py:203–205, RIGHT. Related: _instrumentation.py:782–790, __init__.py:164–174, _capture.py:31–32.
On a shared stateless HTTP server, Alice can emit a custom event as Bob when Bob finishes while Alice's async tool is awaiting work. The event contains Alice's payload, Bob's distinct_id, Bob's request $session_id, and Bob's cached $set. Expected: Alice's custom event must not adopt another caller's attribution; an isolated anonymous fallback is sufficient.
A supported public caller is enough:
@server.tool()
async def probe(marker: str) -> str:
if marker == "alice":
entered.set()
await resume.wait() # another HTTP request can complete during async work
await analytics.capture("inside_tool", {"marker": "alice"})
return markerTrigger: default-enabled conversation anchoring; ChatGPT-recognized User-Agent; no token/transport session; an application identify callback resolving the request user; Bob has no usable client conversation ID. Alice may have valid openai/session metadata or none. Alice starts, Bob completes, then Alice resumes. The test uses valid HTTP/MCP requests and no private-state mutation; asynchronous overlap is supported by both official HTTP adapters.
The new request fallback is written to server-wide data.session_id. Bob's automatic completion identifies that fallback. When Alice resumes, McpAnalytics.capture() reads Bob's shared value, and capture_event() looks up Bob's cached actor. Locking individual resolver updates does not protect the lifetime of an awaiting tool invocation.
For both tested official MCP versions, the overlapping head case emits:
{
"event": "inside_tool",
"distinct_id": "bob",
"properties": {
"marker": "alice",
"$session_id": "<same session as Bob's automatic event>",
"$set": {"owner": "bob"}
}
}Base/head causality: on base 7eabca81234311dfd86e516c4354c5322f73bfc5, Bob's automatic event identifies a minted-handle session and leaves the custom-event fallback anonymous. On head 5417daa9361862cdc1934abf7e14ffaed9ecc414, handle suppression replaces that path with an identified request fallback exposed through shared state. Existing token-backed races are not the evidence for this finding. This is a newly identified case against the merge base, not a claim that it first appeared in the latest fix commit.
The canonical Session identity requirement forbids grouping different clients, and Person identity uses the request's actor or its session. The priming contract in _instrumentation.py:408–419 explicitly protects in-tool capture from another caller's identity. The instance-source documentation does not justify attaching Alice's payload to Bob's identity.
Executed regression: Python 3.11.13, pytest 8.4.1, pytest-asyncio 1.0.0, httpx 0.28.1 and Pydantic 2.12.5; identical base/head inputs/dependencies within each lane.
| Official entry path | Base | Head |
|---|---|---|
| MCP 1.28.1 FastMCP, legacy stateless HTTP | 4 passed | 2 failed, 2 passed |
| MCP 2.3.0 MCPServer, modern stateless HTTP | 4 passed | 2 failed, 2 passed |
Only the two overlapping variants fail on head, at custom["distinct_id"] != "bob"; awaited controls pass. Printed payloads independently show the wrong session and person properties. The six previously reported exact regressions pass on this head and are not being reopened here.
Consider retaining custom-capture fallback attribution in request/task-local context, bound for the invocation and reset in finally, rather than reading whichever request last updated the server-wide value. Preserve outside-request behavior and the passing sequential/token controls; add this overlap coverage for both majors. No public capture argument, global metadata-derived ID, or serialization of unrelated requests is needed.
Impact limits: demonstrated wrong event/person association within the receiving project, not an authentication bypass, response leak, cross-project disclosure, wrong automatic-event attribution, or executed backend profile mutation. The test uses the real inbound adapters and event-shaping pipeline with a FakeClient sink; outbound PostHog HTTP delivery and live client metadata frequency were not verified.
Executed regression harness
Save as test_concurrent_custom_capture.py in the SDK test environment and run pytest -q -s --asyncio-mode=auto test_concurrent_custom_capture.py. Run each revision under the same MCP major/version. The header-based identity callback is a test fixture for an application's request-user resolver, not a credential.
"""Overlapping public HTTP calls must not attribute Alice's custom event to Bob."""
import asyncio
import json
import importlib.metadata
import httpx
import pytest
MCP_MAJOR = int(importlib.metadata.version('mcp').split('.')[0])
if MCP_MAJOR < 2:
from mcp.server.fastmcp import FastMCP
from mcp.server.transport_security import TransportSecuritySettings
else:
from mcp.server.mcpserver import MCPServer
from posthog.test.mcp._helpers_v2 import modern_headers, modern_meta
from posthog.mcp import instrument, MCPAnalyticsOptions, UserIdentity, get_request_headers
from posthog.test.mcp._helpers import FakeClient
HEADERS = {'content-type': 'application/json', 'accept': 'application/json, text/event-stream', 'mcp-protocol-version': '2025-06-18', 'user-agent': 'openai-mcp/1.0.0 (ChatGPT)'}
@pytest.mark.parametrize('overlap', [False, True], ids=['awaited-control', 'overlapping'])
@pytest.mark.parametrize('alice_meta', [{}, {'openai/session': 'alice-chat'}], ids=['both-missing-id', 'alice-valid-id'])
async def test_custom_event_does_not_inherit_another_inflight_call(alice_meta, overlap):
entered = asyncio.Event()
resume = asyncio.Event()
client = FakeClient()
server = (FastMCP('concurrent-review', stateless_http=True, json_response=True, transport_security=TransportSecuritySettings(enable_dns_rebinding_protection=False)) if MCP_MAJOR < 2 else MCPServer('concurrent-review'))
@server.tool()
async def probe(marker: str) -> str:
if marker == 'alice':
entered.set()
if overlap:
await resume.wait()
await analytics.capture('inside_tool', {'marker': 'alice'})
return marker
def identify(request, extra):
user = get_request_headers(extra['ctx']).get('x-review-user')
return UserIdentity(distinct_id=user, properties={'owner': user}) if user else None
analytics = instrument(server, client, MCPAnalyticsOptions(context=False, capture_model=False, send_initialize_event=False, identify=identify))
app = server.streamable_http_app() if MCP_MAJOR < 2 else server.streamable_http_app(json_response=True, stateless_http=True)
async with server.session_manager.run():
async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url='http://127.0.0.1:8000') as http:
async def call(who, meta, request_id):
protocol_headers = HEADERS if MCP_MAJOR < 2 else {**modern_headers('tools/call', 'probe'), 'user-agent': HEADERS['user-agent']}
request_meta = meta if MCP_MAJOR < 2 else {**modern_meta(), **meta}
response = await http.post('/mcp', headers={**protocol_headers, 'x-review-user': who}, json={'jsonrpc': '2.0', 'id': request_id, 'method': 'tools/call', 'params': {'name': 'probe', 'arguments': {'marker': who}, '_meta': request_meta}})
assert response.status_code == 200, response.text
body = response.json()
assert 'error' not in body and not body['result'].get('isError'), body
await analytics.flush()
return body
if overlap:
alice_task = asyncio.create_task(call('alice', alice_meta, 1))
await asyncio.wait_for(entered.wait(), 5)
try:
await call('bob', {}, 2)
finally:
resume.set()
await asyncio.wait_for(alice_task, 5)
else:
await call('alice', alice_meta, 1)
await call('bob', {}, 2)
custom = next(e for e in client.events if e['event'] == 'inside_tool')
bob = next(e for e in client.events if e['event'] == '$mcp_tool_call' and e['distinct_id'] == 'bob')
print(json.dumps({'mcp_version': importlib.metadata.version('mcp'), 'overlap': overlap, 'alice_meta': alice_meta, 'alice_custom': custom, 'bob_automatic': bob}, default=str))
assert custom['distinct_id'] != 'bob', 'Alice custom event uses Bob identity'
assert custom['properties'].get('$set', {}).get('owner') != 'bob', 'Alice payload updates Bob properties'
assert custom['properties']['$session_id'] != bob['properties']['$session_id'], 'Alice custom event uses Bob request session'There was a problem hiding this comment.
Fixed in 4b103b5. I followed your suggestion: the session is request-local, bound for the invocation and reset in finally.
- Binding. Each adapter (FastMCP, lowlevel, and both v2 paths) runs the tool body inside
lifecycle.in_tool(). It binds the call's session to aContextVarkeyed to the server's tracking data and resets it when the body returns.McpAnalytics.capture()reads it, and falls back todata.session_idoutside a tool body or on another server. - Which session. The call's client conversation id or handle if it has one (an echoed handle, or one minted for this call, as posthog-js does), otherwise its primed transport session.
on_feedback. The host handler runs bound to the$mcp_feedbacksession.- Merge. main is merged in (c8df7b0). The only conflict was
posthog_mcp.py, where the client-id logic moved into the new_prepare_conversationhelper.
Tests in test_client_conversation_session.py:
- Your overlap scenario (Alice primes, Bob completes, Alice captures), with no id, a client id, an echoed handle and a minted handle. Alice's event matches her own
$mcp_tool_callsession. - An
on_feedbackoverlap. - Captures outside a tool: on the same server after a call, and on another server inside one.
Each row fails when the matching part of the binding is removed. posthog/test/mcp: 884 pass. Not run here: the 2.x adapters (only mcp 1.x is installed locally). CI covers both majors.
…-session # Conflicts: # posthog/mcp/posthog_mcp.py
A custom event captured inside a tool read the server-wide data.session_id. On a shared stateless HTTP server, another request finishing while the tool awaited moved that slot, so the event took the other caller's session and identity (Dustin's P1 on this PR). Each adapter now runs the tool body inside lifecycle.in_tool(), which binds the call's session to a ContextVar keyed to its server and resets it when the body returns. The session is the call's client conversation id or handle (echoed, or minted for this call, as posthog-js does) when it has one, else its primed transport session. The host's on_feedback handler runs bound to the $mcp_feedback session. Rules 1 and 2 move into resolve_anchored_session so the resolver and the binding share them. Tested: overlap rows (no id, client id, echoed and minted handle), an on_feedback overlap, and outside-a-tool rows (same server after a call, another server inside one) fail before and pass after; dropping each part of the binding turns its rows red. pytest posthog/test/mcp: 884 passed. ruff, public API snapshot clean; mypy unchanged (5 errors in untouched files).
There was a problem hiding this comment.
PostHog Review · Standard · reviewed 4b103b5: 1 Should fix. This pull request is large, so the review ran in 4 parts with less depth than usual.
This is review round 5 on this pull request. When findings keep coming back in the same code, the approach is usually the problem. Before the next fix, check whether a different design would remove the whole class of findings.
…ll's outcome A handle minted for a call groups it only once its result delivers it. The in-tool binding put custom events on that handle's session right away, but a call that raised, or whose result could not carry the handle, records its $mcp_tool_call under the fallback session. The two then split (reviewhog's P2 on this PR). While a call runs on a handle minted for it, in_tool buffers its custom events. When the call records its outcome (result, error, unknown tool), they are sent with that event's session, without the call waiting on them or failing because of them. Each adapter settles whatever is left in a finally with the primed session, so a cancelled call, or one that records nothing, loses none. They keep the duration they had when captured. Work the tool started that captures later goes straight to the settled session. Echoed handles and client conversation ids are unchanged. Tested: a parameterized test crosses the outcome (delivered, undelivered, raised) with when the event is captured (in the tool, after the call settles); 5 of 6 rows fail before. test_minted_handle_custom_events.py runs cancellation (in the tool, and while the call records), an empty tool name, an unbuildable event and the duration through the real mcp 1.x adapters; all fail without the fix. pytest posthog/test/mcp: 895 passed. ruff, public API snapshot clean; mypy unchanged. The mcp 2.x adapter gets the same finally; CI runs it.
There was a problem hiding this comment.
PostHog Review · Standard · reviewed be1d543: 2 Should fix. This pull request is large, so the review ran in 4 parts with less depth than usual.
This is review round 6 on this pull request. When findings keep coming back in the same code, the approach is usually the problem. Before the next fix, check whether a different design would remove the whole class of findings.
| pending = unsettled_custom_events(data) | ||
| if pending is not None: | ||
| # Sent once the call settles; its duration is still the moment it was captured. | ||
| pending.events.append({**event_input, "duration": 0}) |
There was a problem hiding this comment.
P2 · Snapshot custom properties before queuing events
When a tool reuses a properties dictionary across awaited capture() calls, this shallow copy queues the same dictionary for every event. Updating or clearing it before the tool finishes rewrites or erases previously captured values: two progress events both lose their steps after properties.clear(). Snapshot the properties when queuing each event.
| pending = unsettled_custom_events(data) | ||
| if pending is not None: | ||
| # Sent once the call settles; its duration is still the moment it was captured. | ||
| pending.events.append({**event_input, "duration": 0}) |
There was a problem hiding this comment.
P2 · Bound the deferred custom-event buffer
During a long-running tool call that mints a handle, each awaited capture() retains the full properties object in pending.events until completion. This bypasses the client's bounded queue and payload truncation, so repeated progress events grow memory without limit; settlement then creates one task per event. Bound the buffer by count and bytes with explicit overflow handling.
| pending = unsettled_custom_events(data) | ||
| if pending is not None: | ||
| # Sent once the call settles; its duration is still the moment it was captured. | ||
| pending.events.append({**event_input, "duration": 0}) |
There was a problem hiding this comment.
Medium: Unbounded deferred-event buffer
Calls that mint a conversation handle now accumulate every full custom event until the tool finishes, before the sink or the client's bounded queue can drop anything. For bulk or streaming tools that capture per client-supplied item, this allows unbounded SDK memory growth despite max_queue_size; cap the deferred event count and retained bytes, dropping excess events before appending.
Problem
Servers that need tool schemas and results left unchanged turn conversation IDs off. On a stateless server that builds a fresh instance per request, every tool call then gets its own
$session_id(PostHog/posthog#119784).Some clients already name the conversation in each tool call's
_meta. sdk-specs main defines which keys the SDKs read, from which clients, and in what order: "Session identity", from PostHog/sdk-specs#175 and #176. This PR implements those rules exactly. It is the twin of PostHog/posthog-js#5577.Changes
_client_conversation.CLIENT_CONVERSATION_ROWSmirrors the spec table:openai/session: 1 to 128 printable ASCII characters. Handle-free.sessionId: a UUID. Keeps the handle as a fallback.vscode.conversationId: a UUID. Keeps the handle as a fallback.UUIDs are lowercased and the nil UUID is rejected.
Recognition. A key is read only from a request whose
User-Agentor client name matches its row. The client name comes from the request's_metaclientInfofirst, then the name the adapter resolved.The client's id is session source 1 on tool calls, ahead of the handle and the transport.
tools/list, resource requests, andinitializeno longer read it. A handle echoed alongside it is stripped but ignored.Handle-free (ChatGPT). Its client-facing
tools/listhas noconversation_idor_mcp_instructions, and it is minted no handle. The SDK's internal tool-cache pass still injects, so validation stays the same for every client.Connection activity. On a one-client connection (stdio), a client-grouped call counts as activity, so the session doesn't rotate early.
$mcp_session_sourceon everyinstrument()event. The spec addition for it is docs(mcp-analytics): record which source grouped each session as $mcp_session_source sdk-specs#185.PostHogMCP.prepare_tool_listandprepare_tool_calltakeheaders, andprepare_tool_callalso takesclient_info.capture_tool_calltakesrequest_meta. A ChatGPTprepare_tool_liststill recordsconversation_idownership.On mcp 2.x low-level servers, the SDK's internal
tools/listdispatch (Mcp-Param header validation) emits no event. That part is unchanged from the earlier version of this PR.Not verified against real clients
openai/sessionstay the same for a whole ChatGPT conversation? Not verified. I have no ChatGPT connector session to log from. One way to confirm is to log_metaacross a multi-turn chat.sessionId? Partly verified, from source only. Codex adds it to tool-call_metastarting atrust-v0.156.0(2026-09-22). Older installs fall back to the handle.How I tested
pytest posthog/test/mcp: 745 passed on mcp 1.30.0 and 603 passed on mcp 2.3.0.test_client_conversation_session.pycovers every spec scenario and vector, and recognition examples.ruff,mypy(CI mode with baseline), and the public API snapshot pass.prepare_tool_listskipped recording ownership, soprepare_tool_callpassed an echoed handle to the handler.>. It predates this PR and matches posthog-js, so it's a follow-up.structuredContent. Mirroring is a MAY and the handle is still delivered.$mcp_session_sourceonly for a recognized client id (spec MAY, follow-up).🤖 Agent context
Autonomy: Human-driven (agent-assisted)
Built with Claude Code (pstack poteto-mode) at Lucas's direction. An earlier version ranked
openai/sessionbelow the transport session, with no recognition rules. Lucas decided the merged sdk-specs rules win, so this version implements them as written.