fix(mcp): deliver the conversation handle via structuredContent too

Manual testing against Claude Code found the conversation feature inert for
any tool that declares an output schema: clients that read structuredContent
never render the content blocks, so the [SERVER]: Reuse conversation_id text
block was invisible and the agent had nothing to echo back. Every call minted
a fresh handle, and each landed in its own session.

Ports the second delivery channel from @posthog/mcp (ADR-0004, posthog-js
 #4430/#4431), which measured the same 0% echo rate before fixing it:

- declare an optional `_mcp_instructions` key on the tool's advertised
  outputSchema at tools/list (never `required`)
- mirror {conversation_id} into the result's structuredContent on *every*
  response, not just the minting one, so an agent that dropped the handle
  can read it back

The declaration is what makes the write safe — clients validate
structuredContent against the advertised schema, so an undeclared key fails
the customer's whole tool result under additionalProperties: false. Only
tools we declared on are ever written to, and an instance that never served
a tools/list fails closed. Composed schemas (oneOf/allOf/anyOf/$ref) and
tools owning the key are skipped; the text block still carries them.

Wired into all four adapters (v1 FastMCP, v1 low-level, jlowin fastmcp, v2)
with shape-tolerant reads: the (content, structured) tuple from FastMCP 1.x's
convert_result path, CallToolResult models (structuredContent on 1.x,
structured_content on 2.x), and plain dicts.

Verified on the live playground server: outputSchema declares the key and
structuredContent carries the handle alongside the tool's own payload.

Generated-By: PostHog Code
Task-Id: ebafcb71-b03b-443d-b40c-d527ed4a04f4

Author: gesh

.sampo/changesets/mcp-sdk-v2-support.md

@@ -2,4 +2,4 @@
 posthog: minor
 ---
 
-feat(mcp): support the MCP Python SDK 2.x and the 2026-07-28 spec revision. `instrument()` now wraps `mcp.server.mcpserver.MCPServer` (the renamed FastMCP) and the v2 low-level `Server` (constructor-injected handlers, string-keyed registry, late `add_request_handler` registrations included), capturing tool calls, tools/list, errors, intent, client identity, and `$mcp_protocol_version` on both protocol eras — SDK 1.x paths are unchanged. Conversation-anchored sessions land as the cross-pod correlation for the stateless era (parity with `@posthog/mcp`): with `enable_conversation_id`, `$session_id` is derived deterministically from the agent-echoed `conversation_id` (new export `derive_session_id_from_conversation`), only handles the SDK could have minted (uuidv7) anchor, and the prompt-back now rides errored results too so a first-call failure keeps the conversation together. `instrument()` also no longer crashes on an unsupported or unrecognized MCP SDK — it degrades to a logged no-op.
+feat(mcp): support the MCP Python SDK 2.x and the 2026-07-28 spec revision. `instrument()` now wraps `mcp.server.mcpserver.MCPServer` (the renamed FastMCP) and the v2 low-level `Server` (constructor-injected handlers, string-keyed registry, late `add_request_handler` registrations included), capturing tool calls, tools/list, errors, intent, client identity, and `$mcp_protocol_version` on both protocol eras — SDK 1.x paths are unchanged. Conversation-anchored sessions land as the cross-pod correlation for the stateless era (parity with `@posthog/mcp`): with `enable_conversation_id`, `$session_id` is derived deterministically from the agent-echoed `conversation_id` (new export `derive_session_id_from_conversation`), only handles the SDK could have minted (uuidv7) anchor, and the prompt-back now rides errored results too so a first-call failure keeps the conversation together. The handle is delivered over both channels a tool result has — a `content` text block on the minting response, and an `_mcp_instructions` key declared on the tool's `outputSchema` and mirrored into `structuredContent` on every response. The second channel is what makes the feature work for tools with structured output at all: clients that read `structuredContent` never render `content`, so the agent had no handle to echo (0% echo rate measured against Claude Code before the mirror). `instrument()` also no longer crashes on an unsupported or unrecognized MCP SDK — it degrades to a logged no-op.

posthog/mcp/_instrument_fastmcp.py

@@ -50,6 +50,10 @@
     resolve_session_and_client,
 )
 from ._internal import MCPAnalyticsData
+from ._output_instructions import (
+    add_instructions_to_output_schema,
+    mirror_instructions_into_structured_content,
+)
 from .logger import log
 from .tools import (
     GET_MORE_TOOLS_NAME as _GET_MORE_TOOLS_NAME,
@@ -178,16 +182,26 @@ async def wrapped(
             )
             raise
 
-        # Inject the prompt-back first, then capture the delivered result. Only stamp
-        # a minted conversation_id when it was actually appended to what the agent got.
+        # Deliver the handle first, then capture the result the agent actually got.
+        # Two channels: mirrored into structuredContent on every response (for
+        # tools whose output schema we declared the key on — clients that read
+        # structuredContent never see the text block), and the prompt-back text
+        # block on the minting response only.
         delivered_conversation_id = conversation_id
-        if minted and conversation_id:
-            injected = _inject_prompt_back(result, conversation_id)
-            if injected is result:
-                delivered_conversation_id = (
-                    None  # not injectable (e.g. tuple/scalar result)
+        if conversation_id:
+            delivered = False
+            if data.tool_output_instructions.get(name):
+                result, delivered = mirror_instructions_into_structured_content(
+                    result, conversation_id
                 )
-            result = injected
+            if minted:
+                injected = _inject_prompt_back(result, conversation_id)
+                if injected is not result:
+                    delivered = True
+                result = injected
+                # Only a minted handle can be lost — one the agent supplied, it has.
+                if not delivered:
+                    delivered_conversation_id = None
 
         await record_tool_call(
             data,
@@ -298,6 +312,13 @@ async def list_handler(req: Any) -> Any:
                     tool.inputSchema = schema
                 except Exception:  # noqa: BLE001 - some schema attrs may be read-only
                     log(f"WARN: could not set inputSchema on tool {tool.name}")
+            # Declare the structuredContent channel and remember the answer:
+            # clients that read structuredContent never see the content text
+            # block, and only a declared key may be written back on a call.
+            if data.options.enable_conversation_id:
+                data.tool_output_instructions[tool.name] = (
+                    add_instructions_to_output_schema(tool)
+                )
 
         if data.options.report_missing:
             missing_name = resolve_missing_capability_tool_name(data.options)

posthog/mcp/_instrument_lowlevel.py

@@ -44,6 +44,10 @@
     resolve_session_and_client,
 )
 from ._internal import MCPAnalyticsData
+from ._output_instructions import (
+    add_instructions_to_output_schema,
+    mirror_instructions_into_structured_content,
+)
 from .logger import log
 from .tools import (
     GET_MORE_TOOLS_NAME as _GET_MORE_TOOLS_NAME,
@@ -188,22 +192,33 @@ async def handler(req: Any) -> Any:
         # CallToolResult(isError=True); record_tool_call detects that from the result.
         call_result = getattr(result, "root", result)
 
-        # Inject the prompt-back before capture; only stamp a minted conversation_id
-        # when it was actually delivered (non-list results can't carry it), so we
-        # don't record an orphan id the agent never received. Errored results carry
-        # it on purpose: a first-call failure is exactly when the agent needs the
-        # handle, or the retry starts a fresh conversation.
+        # Deliver the handle before capture, over both channels a result has:
+        # mirrored into structuredContent on every response (for tools whose
+        # output schema we declared the key on — clients that read
+        # structuredContent never see the text block), and the prompt-back text
+        # block on the minting response only. Only stamp a minted conversation_id
+        # when it actually reached the agent, so we don't record an orphan id.
+        # Errored results carry it on purpose: a first-call failure is exactly
+        # when the agent needs the handle, or the retry starts a fresh conversation.
         delivered_conversation_id = conversation_id
-        if minted and conversation_id:
-            content = getattr(call_result, "content", None)
-            if isinstance(content, list):
-                content.append(
-                    mcp_types.TextContent(
-                        type="text", text=build_prompt_back(conversation_id)["text"]
-                    )
+        if conversation_id:
+            delivered = False
+            if data.tool_output_instructions.get(name):
+                _, delivered = mirror_instructions_into_structured_content(
+                    call_result, conversation_id
                 )
-            else:
-                delivered_conversation_id = None
+            if minted:
+                content = getattr(call_result, "content", None)
+                if isinstance(content, list):
+                    content.append(
+                        mcp_types.TextContent(
+                            type="text", text=build_prompt_back(conversation_id)["text"]
+                        )
+                    )
+                    delivered = True
+                # Only a minted handle can be lost — one the agent supplied, it has.
+                if not delivered:
+                    delivered_conversation_id = None
 
         await record_tool_call(
             data,
@@ -316,6 +331,13 @@ async def handler(req: Any) -> Any:
                     tool.inputSchema = schema
                 except Exception:  # noqa: BLE001
                     log(f"WARN: could not set inputSchema on tool {tool.name}")
+            # Declare the structuredContent channel and remember the answer:
+            # clients that read structuredContent never see the content text
+            # block, and only a declared key may be written back on a call.
+            if data.options.enable_conversation_id:
+                data.tool_output_instructions[tool.name] = (
+                    add_instructions_to_output_schema(tool)
+                )
 
         if data.options.report_missing:
             missing_name = resolve_missing_capability_tool_name(data.options)

posthog/mcp/_instrument_v2.py

@@ -56,6 +56,10 @@
     resolve_session_and_client,
 )
 from ._internal import MCPAnalyticsData
+from ._output_instructions import (
+    add_instructions_to_output_schema,
+    mirror_instructions_into_structured_content,
+)
 from .logger import log
 from .tools import (
     GET_MORE_TOOLS_NAME as _GET_MORE_TOOLS_NAME,
@@ -323,8 +327,12 @@ async def wrapped(
         duration_ms = (time.monotonic() - start) * 1000
 
         delivered_conversation_id = conversation_id
-        if minted and conversation_id:
-            if not _append_prompt_back(result, conversation_id):
+        if conversation_id:
+            result, delivered = _deliver_conversation_id(
+                data, result, name, conversation_id, minted
+            )
+            # Only a minted handle can be lost this way — one the agent supplied, it has.
+            if minted and not delivered:
                 delivered_conversation_id = None
 
         await record_tool_call(
@@ -365,6 +373,24 @@ def _append_prompt_back(result: Any, conversation_id: str) -> bool:
     return False
 
 
+def _deliver_conversation_id(
+    data: MCPAnalyticsData, result: Any, name: str, conversation_id: str, minted: bool
+) -> Tuple[Any, bool]:
+    """Hand the conversation handle back over both channels a result has:
+    mirrored into ``structuredContent`` on every response (for tools whose
+    output schema we declared the key on), and as a ``content`` text block on
+    the minting response only. Returns ``(result, delivered)`` — a minted handle
+    the agent never received must not be stamped on the event."""
+    delivered = False
+    if data.tool_output_instructions.get(name):
+        result, delivered = mirror_instructions_into_structured_content(
+            result, conversation_id
+        )
+    if minted and _append_prompt_back(result, conversation_id):
+        delivered = True
+    return result, delivered
+
+
 # --- low-level: tools/call ------------------------------------------------------
 
 
@@ -444,8 +470,12 @@ async def handler(ctx: Any, params: Any) -> Any:
         duration_ms = (time.monotonic() - start) * 1000
 
         delivered_conversation_id = conversation_id
-        if minted and conversation_id:
-            if not _append_prompt_back(result, conversation_id):
+        if conversation_id:
+            result, delivered = _deliver_conversation_id(
+                data, result, name, conversation_id, minted
+            )
+            # Only a minted handle can be lost this way — one the agent supplied, it has.
+            if minted and not delivered:
                 delivered_conversation_id = None
 
         await record_tool_call(
@@ -562,6 +592,13 @@ async def handler(ctx: Any, params: Any) -> Any:
                     tool.input_schema = schema
                 except Exception:  # noqa: BLE001 - some schema attrs may be read-only
                     log(f"WARN: could not set input_schema on tool {tool.name}")
+            # Declare the structuredContent channel and remember the answer:
+            # clients that read structuredContent never see the content text
+            # block, and only a declared key may be written back on a call.
+            if data.options.enable_conversation_id:
+                data.tool_output_instructions[tool.name] = (
+                    add_instructions_to_output_schema(tool)
+                )
 
         if data.options.report_missing:
             missing_name = resolve_missing_capability_tool_name(data.options)

posthog/mcp/_internal.py

@@ -66,6 +66,12 @@ class MCPAnalyticsData:
     identified_sessions: IdentityCache = field(default_factory=IdentityCache)
     tool_categories: Dict[str, str] = field(default_factory=dict)
     tool_descriptions: Dict[str, str] = field(default_factory=dict)
+    # Which tools got `_mcp_instructions` declared on their advertised output
+    # schema at tools/list. Only those may be mirrored into on a call — writing
+    # an undeclared key fails the customer's whole result under
+    # `additionalProperties: false`. Absent means "never served a listing for
+    # this tool", which fails closed.
+    tool_output_instructions: Dict[str, bool] = field(default_factory=dict)
     # Bounded FIFO of sessions we've emitted $mcp_initialize for, so a long-lived
     # server can't accumulate one entry per session forever.
     initialized_sessions: "OrderedDict[str, None]" = field(default_factory=OrderedDict)