Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .sampo/changesets/mcp-client-conversation-session.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
pypi/posthog: minor
---

MCP analytics now groups tool calls into sessions by the client's own conversation id in `_meta`: ChatGPT's `openai/session`, Codex's `sessionId`, and VS Code's `vscode.conversationId`, each read only from the client its `User-Agent` or client name identifies. The client's id wins over a conversation handle and a transport session. ChatGPT gets no `conversation_id` argument and no handle, so its tool schemas and results stay unchanged. Events from `instrument()` now carry `$mcp_session_source` (`client_metadata`, `conversation`, `transport` or `generated`), so session fragmentation can be measured. `PostHogMCP.prepare_tool_list` and `prepare_tool_call` take the request's `headers` (and `client_info`), and `capture_tool_call` takes `request_meta`.
22 changes: 19 additions & 3 deletions posthog/mcp/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,16 @@ Use a client dedicated to MCP analytics if the application also captures unrelat

A valid echoed conversation handle takes precedence over transport sessions. A request that already carries a transport session or a PostHog session token does not mint a new handle or append a prompt-back block. Requests carrying neither use the conversation fallback.

Some MCP clients name the conversation in each tool call's `params._meta`: ChatGPT's
`openai/session`, Codex's `sessionId`, and VS Code's `vscode.conversationId`. The SDK reads each key
only from a request whose `User-Agent` or client name identifies that client, and derives
`$session_id` from it ahead of any conversation handle or transport session. ChatGPT sends its id on
every call, so its `tools/list` has no `conversation_id` argument and its results get no handle, even
with `enable_conversation_id` on. Each event records which source grouped it in
`$mcp_session_source`: `client_metadata`, `conversation`, `transport`, or `generated`. Custom events
from `McpAnalytics.capture()` carry the instance's own source. The rules are the sdk-specs "Session
identity" requirement, and posthog-js `docs/adr/0014` records the reasoning.


Intent, model capture, conversation correlation, MCP exception capture, and `$mcp_initialize`
are on by default. Missing-capability reporting and feedback collection remain off.
Expand Down Expand Up @@ -237,9 +247,12 @@ Model and conversation injection copy tool objects instead of changing their ori
Always advertise the returned list and pass the original application tool to
`prepare_tool_call()`. Repeatedly preparing the original list preserves ownership.

Pass an existing transport or request session as `session_id`. A valid echoed
`conversation_id` takes precedence. Otherwise the existing session stays, and no new handle is
minted. `prepare_tool_result()` appends a new handle to the result's `content` and mirrors it
Pass `request_meta` whenever the request supplies `_meta`, and `headers` (plus `client_info` from a
handshake bound to the request, if you hold one) so the SDK can recognize the client; this enables
recognized client metadata and client conversation ids without changing the arguments sent to the
tool. Pass the same `headers` to `prepare_tool_list()`. Pass an existing transport or request
session as `session_id`. A client conversation id or a valid echoed `conversation_id` takes
precedence. Otherwise the existing session stays, and no new handle is minted. `prepare_tool_result()` appends a new handle to the result's `content` and mirrors it
into `structuredContent` when the tool declares an output schema. If the result has no channel
that can carry a new handle, `conversation_id` is `None` and the derived `session_id` is kept.
Set `enable_conversation_id=False` on `PostHogMCP` to keep the previous custom-dispatcher
Expand Down Expand Up @@ -468,6 +481,9 @@ Prefer it if you're on a recent client.
The `get_more_tools` and `send_feedback` virtual tools also use the conversation
handle when this option is enabled.

A recognized client's own conversation id in `params._meta` (such as ChatGPT's `openai/session`)
also groups calls on per-request servers, with or without this option, and wins over the handle.

### How the SDK tells you it's misconfigured

The failure used to be silent. It now surfaces two ways:
Expand Down
27 changes: 17 additions & 10 deletions posthog/mcp/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,8 @@
from .session import (
derive_session_id_from_conversation,
derive_session_id_from_mcp_session,
current_session,
unsettled_custom_events,
new_session_id,
)
from .session_token import (
Expand Down Expand Up @@ -161,16 +163,21 @@ async def capture(self, event: str, properties: Optional[dict] = None) -> None:
data = get_server_tracking_data(self._key)
if data is None:
return
coro = capture_event(
data,
{
"session_id": data.session_id,
"event_type": MCPAnalyticsEventType.CUSTOM,
"event_name": event,
"timestamp": datetime.now(timezone.utc),
"properties": properties,
},
)
session_id, session_source = current_session(data)
event_input = {
"session_id": session_id,
"session_source": session_source,
"event_type": MCPAnalyticsEventType.CUSTOM,
"event_name": event,
"timestamp": datetime.now(timezone.utc),
"properties": properties,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

[P1] Snapshot scalar properties before returning from deferred capture

Compared base f22511891225fb15a4e6a0f889e723e9b5d0ebe4 with head be1d543c1909f6b9d21e1aa449258cbc60dc8af1.

IMPORTANT · REQUIRED · Introduced by deferred capture.
Related: posthog/mcp/__init__.py:175–179.

Reusing a dictionary after awaited capture now changes the contents of earlier events:

properties = {"step": 0}
await analytics.capture("progress", properties)
properties["step"] = 1
await analytics.capture("progress", properties)
properties.clear()

Expected: the events retain step=0 and step=1. Actual: both are emitted without step.

The shallow event-input copy retains the caller-owned properties mapping until settlement. Base awaited materialization, which copied its top-level entries into the outgoing mapping before returning.

Executed public HTTP/ASGI comparison, both official majors:

Case Base Head
Minted-handle call [0, 1] Both scalar properties absent
Anchoring-disabled control [0, 1] [0, 1]

No concurrency, malformed input or private-state mutation is required. This regresses established observable capture behavior; the timestamp represents capture time while its payload instead reflects later application state.

Consider snapshotting the top-level mapping when accepting the deferred event, preserving fail-closed handling and final session selection.

Scope: This establishes top-level scalar preservation only. Nested mutation fails on base too; no deep-copy contract is inferred. Automatic events and identities are not shown to be lost.

Each major’s scalar cases produce base 2 passed, head 1 failed / 1 passed. The complete shared harness below produces base 4 passed, head 2 failed / 2 passed, including the separate optional allocation measurement.

Executed shared scalar/retention harness

Run with the same selected MCP version—1.28.1 or 2.3.0—on both revisions:

pytest -q -s --asyncio-mode=auto test_deferred_capture_standalone.py

Use -k snapshots for the scalar cases and -k large_progress for retention.

import importlib.metadata
import json
import tracemalloc
import httpx
import pytest
from posthog.mcp import instrument, MCPAnalyticsOptions
from posthog.test.mcp._helpers import FakeClient

MAJOR = int(importlib.metadata.version("mcp").split(".")[0])
if 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

async def call_tool(body, client, anchored):
    server = (
        FastMCP(
            "deferred-controls", stateless_http=True, json_response=True,
            transport_security=TransportSecuritySettings(
                enable_dns_rebinding_protection=False
            ),
        )
        if MAJOR < 2 else MCPServer("deferred-controls")
    )

    @server.tool()
    async def probe() -> str:
        await body(analytics)
        return "ok"

    analytics = instrument(
        server, client,
        MCPAnalyticsOptions(
            enable_conversation_id=anchored,
            context=False, capture_model=False,
            send_initialize_event=False,
        ),
    )
    app = (
        server.streamable_http_app() if 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:
            headers = (
                {
                    "content-type": "application/json",
                    "accept": "application/json, text/event-stream",
                    "mcp-protocol-version": "2025-06-18",
                }
                if MAJOR < 2 else modern_headers("tools/call", "probe")
            )
            response = await http.post(
                "/mcp",
                headers={**headers, "user-agent": "example-client/1.0"},
                json={
                    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
                    "params": {
                        "name": "probe", "arguments": {},
                        "_meta": {} if MAJOR < 2 else modern_meta(),
                    },
                },
            )
            assert response.status_code == 200, response.text
            result = response.json()
            assert "error" not in result
            assert not result["result"].get("isError"), result
            if anchored:
                assert "conversation_id" in json.dumps(result)
            await analytics.flush()

@pytest.mark.parametrize("anchored", [False, True])
async def test_capture_snapshots_properties_before_returning(anchored):
    client = FakeClient()

    async def body(analytics):
        props = {"step": 0}
        await analytics.capture("progress", props)
        props["step"] = 1
        await analytics.capture("progress", props)
        props.clear()

    await call_tool(body, client, anchored)
    events = [e for e in client.events if e["event"] == "progress"]
    assert len(events) == 2
    actual = [e["properties"].get("step") for e in events]
    print(json.dumps({"anchored": anchored, "steps": actual}))
    assert actual == [0, 1]

class CountingClient:
    """Never retains event payloads itself."""
    def __init__(self):
        self.count = 0
        self.largest_blob = 0

    def capture(self, event, **kwargs):
        if event == "progress":
            self.count += 1
            self.largest_blob = max(
                self.largest_blob,
                len(kwargs["properties"].get("blob", "")),
            )

@pytest.mark.parametrize("anchored", [False, True])
async def test_large_progress_events_do_not_accumulate_before_sink_limits(
    anchored,
):
    client = CountingClient()
    observed = {}

    async def body(analytics):
        tracemalloc.start()
        before = tracemalloc.get_traced_memory()[0]
        try:
            for index in range(64):
                await analytics.capture(
                    "progress",
                    {"blob": str(index) + ":" + "x" * (256 * 1024)},
                )
            current, peak = tracemalloc.get_traced_memory()
            observed.update(
                retained_bytes=current-before,
                peak_bytes=peak-before,
                captures_before_tool_returns=client.count,
            )
        finally:
            tracemalloc.stop()

    await call_tool(body, client, anchored)
    print(json.dumps({
        "anchored": anchored, **observed,
        "total_captures": client.count,
        "largest_sink_blob": client.largest_blob,
    }))
    assert client.count == 64
    assert observed["retained_bytes"] < 2 * 1024 * 1024

The harness is formatting-equivalent to the executed source. The memory threshold detects the change, not an agreed future cap/drop contract.

}
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})

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

[P2] Bound deferred payloads before downstream queue limits

Compared base f22511891225fb15a4e6a0f889e723e9b5d0ebe4 with head be1d543c1909f6b9d21e1aa449258cbc60dc8af1.

MINOR · OPTIONAL · Introduced by deferred capture.
Related: session.py:38–45, _instrumentation.py:653–674.

A call minting a handle retains every full custom payload until completion:

for index in range(64):
    await analytics.capture(
        "progress", {"blob": str(index) + ":" + "x" * (256 * 1024)}
    )

pending.events has no count or retained-byte bound. Inputs have not reached truncation, before_send or the host queue. Settlement creates one task per retained event.

The executed harness below uses a counting/discarding client that retains no payloads:

Minted-handle case Base retained allocation Head retained allocation
MCP 1.28.1 26,934 bytes 16,807,366 bytes
MCP 2.3.0 21,610 bytes 16,806,302 bytes

Anchoring-off controls remain approximately 24–29 KB on head. Head forwards zero captures before the tool returns and all 64 afterwards. Downstream blobs are approximately 101 KB, while the list retains their original 256 KiB inputs.

Consider an internal count-and-size budget with explicit overflow handling and bounded settlement work, preserving outcome-dependent attribution.

Why optional: The mechanism is confirmed, but this deliberately large fixture does not establish typical residency or likely exhaustion. It measures wrapper-stage Python allocations, not a real host queue’s total memory, RSS, OOM or production harm. All 64 events eventually reach the sink.

The observer-only requirement bounds per-session state/pending tasks, but does not specify an exact per-invocation raw-byte budget. Downstream limits cannot constrain this new list; their existing implementation is not alleged to be broken.

Executed measurement: Run the complete harness below with -k large_progress. Each major yields base 2 passed, head 1 failed / 1 passed. The 2 MiB detector and current delivery-count assertion are not a proposed post-fix cap/drop contract; that policy needs corresponding assertions.

Executed shared scalar/retention harness

Run with the same selected MCP version—1.28.1 or 2.3.0—on both revisions:

pytest -q -s --asyncio-mode=auto test_deferred_capture_standalone.py

Use -k snapshots for the scalar cases and -k large_progress for retention.

import importlib.metadata
import json
import tracemalloc
import httpx
import pytest
from posthog.mcp import instrument, MCPAnalyticsOptions
from posthog.test.mcp._helpers import FakeClient

MAJOR = int(importlib.metadata.version("mcp").split(".")[0])
if 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

async def call_tool(body, client, anchored):
    server = (
        FastMCP(
            "deferred-controls", stateless_http=True, json_response=True,
            transport_security=TransportSecuritySettings(
                enable_dns_rebinding_protection=False
            ),
        )
        if MAJOR < 2 else MCPServer("deferred-controls")
    )

    @server.tool()
    async def probe() -> str:
        await body(analytics)
        return "ok"

    analytics = instrument(
        server, client,
        MCPAnalyticsOptions(
            enable_conversation_id=anchored,
            context=False, capture_model=False,
            send_initialize_event=False,
        ),
    )
    app = (
        server.streamable_http_app() if 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:
            headers = (
                {
                    "content-type": "application/json",
                    "accept": "application/json, text/event-stream",
                    "mcp-protocol-version": "2025-06-18",
                }
                if MAJOR < 2 else modern_headers("tools/call", "probe")
            )
            response = await http.post(
                "/mcp",
                headers={**headers, "user-agent": "example-client/1.0"},
                json={
                    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
                    "params": {
                        "name": "probe", "arguments": {},
                        "_meta": {} if MAJOR < 2 else modern_meta(),
                    },
                },
            )
            assert response.status_code == 200, response.text
            result = response.json()
            assert "error" not in result
            assert not result["result"].get("isError"), result
            if anchored:
                assert "conversation_id" in json.dumps(result)
            await analytics.flush()

@pytest.mark.parametrize("anchored", [False, True])
async def test_capture_snapshots_properties_before_returning(anchored):
    client = FakeClient()

    async def body(analytics):
        props = {"step": 0}
        await analytics.capture("progress", props)
        props["step"] = 1
        await analytics.capture("progress", props)
        props.clear()

    await call_tool(body, client, anchored)
    events = [e for e in client.events if e["event"] == "progress"]
    assert len(events) == 2
    actual = [e["properties"].get("step") for e in events]
    print(json.dumps({"anchored": anchored, "steps": actual}))
    assert actual == [0, 1]

class CountingClient:
    """Never retains event payloads itself."""
    def __init__(self):
        self.count = 0
        self.largest_blob = 0

    def capture(self, event, **kwargs):
        if event == "progress":
            self.count += 1
            self.largest_blob = max(
                self.largest_blob,
                len(kwargs["properties"].get("blob", "")),
            )

@pytest.mark.parametrize("anchored", [False, True])
async def test_large_progress_events_do_not_accumulate_before_sink_limits(
    anchored,
):
    client = CountingClient()
    observed = {}

    async def body(analytics):
        tracemalloc.start()
        before = tracemalloc.get_traced_memory()[0]
        try:
            for index in range(64):
                await analytics.capture(
                    "progress",
                    {"blob": str(index) + ":" + "x" * (256 * 1024)},
                )
            current, peak = tracemalloc.get_traced_memory()
            observed.update(
                retained_bytes=current-before,
                peak_bytes=peak-before,
                captures_before_tool_returns=client.count,
            )
        finally:
            tracemalloc.stop()

    await call_tool(body, client, anchored)
    print(json.dumps({
        "anchored": anchored, **observed,
        "total_captures": client.count,
        "largest_sink_blob": client.largest_blob,
    }))
    assert client.count == 64
    assert observed["retained_bytes"] < 2 * 1024 * 1024

The harness is formatting-equivalent to the executed source. The memory threshold detects the change, not an agreed future cap/drop contract.

return
coro = capture_event(data, event_input)
if coro is not None:
await coro

Expand Down
1 change: 1 addition & 0 deletions posthog/mcp/_capture.py
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ def capture_event(
full_event: Dict[str, Any] = {
"id": event_input.get("id") or "",
"session_id": session_id,
"session_source": event_input.get("session_source"),
"event_type": event_input.get("event_type") or MCPAnalyticsEventType.CUSTOM,
"event_name": event_input.get("event_name"),
"timestamp": timestamp,
Expand Down
173 changes: 173 additions & 0 deletions posthog/mcp/_client_conversation.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,173 @@
"""Client conversation ids: a value an MCP client puts in a ``tools/call``
request's ``_meta`` to name the conversation the call belongs to.

``CLIENT_CONVERSATION_ROWS`` is the table of the spec's "Session identity"
requirement, row for row. A row's key is read only from a request its recognition
rule matches, so a generic key such as Codex's ``sessionId`` is never read from a
client that means something else by it. posthog-js keeps the same table.
"""

from __future__ import annotations

import re
from typing import Any, Callable, NamedTuple, Optional, Sequence

from ._transport_identity import CLIENT_USER_AGENT_HEADER
from .request_headers import _to_header_bag, get_request_headers
from .session_token import decode_session_id, read_mcp_session_header

__all__ = [
"CLIENT_CONVERSATION_ROWS",
"ClientConversation",
"ClientConversationRow",
"meta_client_name",
"read_client_conversation",
"recognize_client",
"recognize_manual_client",
"request_user_agent",
]


class ClientConversation(NamedTuple):
"""A recognized client's conversation id, and the ``_meta`` key it came from."""

key: str
id: str


class ClientConversationRow(NamedTuple):
key: str
read_value: Callable[[Any], Optional[str]]
recognizes: Callable[[Optional[str], Optional[str]], bool]
# The client sends its id on every call, so the SDK advertises no
# ``conversation_id`` to it and mints it no handle. Rows whose clients have
# versions or kinds of conversation that send no id keep the handle.
handle_free: bool


_PRINTABLE_ASCII_UP_TO_128 = re.compile(r"[\x20-\x7e]{1,128}")
_UUID = re.compile(r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}")
_NIL_UUID = "00000000-0000-0000-0000-000000000000"
_CHATGPT_USER_AGENT = re.compile(r"openai-mcp/[^\s(]*\s*\(\s*chatgpt\s*[;,)]", re.I)
_VSCODE_PRODUCT_NAMES = ("Visual Studio Code", "Visual Studio Code - Insiders")


def _read_printable_ascii(value: Any) -> Optional[str]:
if isinstance(value, str) and _PRINTABLE_ASCII_UP_TO_128.fullmatch(value):
return value
return None


def _read_uuid(value: Any) -> Optional[str]:
if not isinstance(value, str):
return None
lowered = value.lower()
return lowered if _UUID.fullmatch(lowered) and lowered != _NIL_UUID else None


def _user_agent_starts_with(user_agent: Optional[str], prefixes: Sequence[str]) -> bool:
lowered = (user_agent or "").lower()
return bool(lowered) and any(lowered.startswith(p.lower()) for p in prefixes)


def _client_name_is(client_name: Optional[str], names: Sequence[str]) -> bool:
lowered = (client_name or "").lower()
return bool(lowered) and any(lowered == name.lower() for name in names)


# Checked in this order; the first row that recognizes a request is its client's row.
CLIENT_CONVERSATION_ROWS = (
ClientConversationRow(
key="openai/session",
read_value=_read_printable_ascii,
recognizes=lambda user_agent, _: bool(
user_agent and _CHATGPT_USER_AGENT.match(user_agent)
),
handle_free=True,
),
ClientConversationRow(
key="sessionId",
read_value=_read_uuid,
recognizes=lambda user_agent, client_name: (
_user_agent_starts_with(user_agent, ["codex-mcp-client/"])
or _client_name_is(client_name, ["codex-mcp-client"])
),
handle_free=False,
),
ClientConversationRow(
key="vscode.conversationId",
read_value=_read_uuid,
recognizes=lambda user_agent, client_name: (
_user_agent_starts_with(
user_agent, [f"{name}/" for name in _VSCODE_PRODUCT_NAMES]
)
or _client_name_is(client_name, _VSCODE_PRODUCT_NAMES)
),
handle_free=False,
),
)


def recognize_client(
user_agent: Optional[str], client_name: Optional[str]
) -> Optional[ClientConversationRow]:
"""The row of the client a request's ``User-Agent`` or client name identifies.

The client name is ``$mcp_client_name`` as the adapters resolve it for the
request: its own ``_meta``, then a replayed session token, then a handshake."""
user_agent = user_agent if isinstance(user_agent, str) else None
client_name = client_name if isinstance(client_name, str) else None
for row in CLIENT_CONVERSATION_ROWS:
if row.recognizes(user_agent, client_name):
return row
return None


def read_client_conversation(
row: Optional[ClientConversationRow], meta: Any
) -> Optional[ClientConversation]:
"""The recognized client's conversation id in ``meta``, or ``None`` when there
is none or it is not the row's shape."""
if row is None or not isinstance(meta, dict):
return None
value = row.read_value(meta.get(row.key))
return ClientConversation(row.key, value) if value is not None else None


def request_user_agent(extra: Any) -> Optional[str]:
"""The request's ``User-Agent``, or ``None`` off HTTP. Never raises."""
try:
headers = get_request_headers(extra)
except Exception: # noqa: BLE001 - a header read must not break a request
return None
value = (headers or {}).get(CLIENT_USER_AGENT_HEADER)
return value if isinstance(value, str) else None


def recognize_manual_client(
headers: Any, request_meta: Any, handshake_client_name: Optional[str]
) -> Optional[ClientConversationRow]:
""":func:`recognize_client` for a custom dispatcher, from what it passes in:
the request's headers, its ``_meta``, and a handshake ``clientInfo`` name
bound to the request's transport session. The client name follows the
request's ``_meta``, then a replayed session token, then the handshake."""
bag = _to_header_bag(headers) if headers is not None else None
user_agent = (bag or {}).get(CLIENT_USER_AGENT_HEADER)
token = decode_session_id(read_mcp_session_header(bag)) if bag else None
return recognize_client(
user_agent if isinstance(user_agent, str) else None,
meta_client_name(request_meta)
or (token.client_name if token is not None else None)
or handshake_client_name,
)


def meta_client_name(meta: Any) -> Optional[str]:
"""The client name a 2026-07-28 request carries in its own ``_meta``."""
info = (
meta.get("io.modelcontextprotocol/clientInfo")
if isinstance(meta, dict)
else None
)
name = info.get("name") if isinstance(info, dict) else None
return name if isinstance(name, str) and name else None
Loading
Loading