Identify client interface in session metadata (#5223)

Right now, we don't have a good way to identify which sessions were
created via Portal, the SDK, Claude Code or Claude.ai. This adds extra
info to the session metadata in the DB to help us identify the user's
surface.

The engine API changes are backwards compatible, so existing SDK users
aren't forced to upgrade.

Sourced from commit 57221d3bb0fb3a42b7b11b16cc137795ea2413d5

Author: rgambee

futuresearch-mcp/src/futuresearch_mcp/app.py

@@ -2,6 +2,7 @@
 
 import logging
 from contextlib import asynccontextmanager
+from importlib.metadata import version
 
 from futuresearch.api_utils import create_client as _create_sdk_client
 from futuresearch.generated.api.billing.get_billing_balance_billing_get import (
@@ -41,13 +42,16 @@ async def http_lifespan(_server: FastMCP):
     redis_client = get_redis_client()
     await redis_client.ping()  # pyright: ignore[reportGeneralTypeIssues]
 
+    sdk_version = version("futuresearch")
+
     def _http_client_factory() -> AuthenticatedClient:
         access_token = get_access_token()
         if access_token is None:
             raise RuntimeError("Not authenticated")
         return AuthenticatedClient(
             base_url=settings.futuresearch_api_url,
             token=access_token.token,
+            headers={"X-SDK-Version": f"futuresearch-python/{sdk_version}"},
             raise_on_unexpected_status=True,
             follow_redirects=True,
         )

futuresearch-mcp/src/futuresearch_mcp/http_config.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import contextvars
 import logging
 import os
 import time as _time
@@ -28,35 +27,13 @@
     SecurityHeadersMiddleware,
 )
 from futuresearch_mcp.redis_store import get_redis_client
+from futuresearch_mcp.request_context import request_context
 from futuresearch_mcp.routes import api_download, api_progress
 from futuresearch_mcp.templates import UNIFIED_HTML
 from futuresearch_mcp.uploads import proxy_upload
 
 logger = logging.getLogger(__name__)
 
-# ── User-Agent propagation ────────────────────────────────────────────
-# In stateless HTTP mode there is no MCP initialize handshake, so
-# ctx.session.client_params is always None.  We propagate the HTTP
-# User-Agent header via a ContextVar so tool functions can still
-# distinguish clients (e.g. Claude Code vs Claude.ai).
-_user_agent_var: contextvars.ContextVar[str] = contextvars.ContextVar(
-    "user_agent", default=""
-)
-
-_conversation_id_var: contextvars.ContextVar[str] = contextvars.ContextVar(
-    "conversation_id", default=""
-)
-
-
-def get_user_agent() -> str:
-    """Return the User-Agent of the current HTTP request (empty in stdio mode)."""
-    return _user_agent_var.get()
-
-
-def get_conversation_id() -> str:
-    """Return the X-Conversation-Id of the current HTTP request (empty if absent)."""
-    return _conversation_id_var.get()
-
 
 def configure_http_mode(
     *,
@@ -216,13 +193,10 @@ async def dispatch(self, request, call_next):
         if request.url.path == "/health":
             return await call_next(request)
 
-        # Propagate User-Agent so downstream tool code can detect the client
-        # even in stateless HTTP mode (no MCP initialize → no client_params).
-        ua_token = _user_agent_var.set(request.headers.get("user-agent", ""))
-        cc_token = _conversation_id_var.set(
-            request.headers.get("x-conversation-id", "")
-        )
-        try:
+        with request_context(
+            user_agent=request.headers.get("user-agent", ""),
+            conversation_id=request.headers.get("x-conversation-id", ""),
+        ):
             start = _time.monotonic()
             response = await call_next(request)
             elapsed_ms = (_time.monotonic() - start) * 1000
@@ -246,9 +220,6 @@ async def dispatch(self, request, call_next):
                 request.headers.get("user-agent", "-"),
             )
             return response
-        finally:
-            _user_agent_var.reset(ua_token)
-            _conversation_id_var.reset(cc_token)
 
 
 def _add_middleware(

futuresearch-mcp/src/futuresearch_mcp/request_context.py

@@ -0,0 +1,44 @@
+"""Per-request context propagation via contextvars.
+
+In stateless HTTP mode there is no MCP initialize handshake, so
+ctx.session.client_params is always None. The HTTP middleware propagates
+the User-Agent and X-Conversation-Id headers via context vars so that
+tool functions can still distinguish clients.
+"""
+
+import contextvars
+from collections.abc import Generator
+from contextlib import contextmanager
+
+_user_agent_var: contextvars.ContextVar[str] = contextvars.ContextVar(
+    "user_agent", default=""
+)
+
+_conversation_id_var: contextvars.ContextVar[str] = contextvars.ContextVar(
+    "conversation_id", default=""
+)
+
+
+def get_user_agent() -> str:
+    """Return the User-Agent of the current HTTP request (empty in stdio mode)."""
+    return _user_agent_var.get()
+
+
+def get_conversation_id() -> str:
+    """Return the X-Conversation-Id of the current HTTP request (empty if absent)."""
+    return _conversation_id_var.get()
+
+
+@contextmanager
+def request_context(
+    user_agent: str,
+    conversation_id: str,
+) -> Generator[None]:
+    """Set per-request context vars for the duration of the block."""
+    ua_token = _user_agent_var.set(user_agent)
+    cc_token = _conversation_id_var.set(conversation_id)
+    try:
+        yield
+    finally:
+        _user_agent_var.reset(ua_token)
+        _conversation_id_var.reset(cc_token)

futuresearch-mcp/src/futuresearch_mcp/tool_helpers.py

@@ -28,6 +28,7 @@
 
 from futuresearch_mcp import redis_store
 from futuresearch_mcp.config import settings
+from futuresearch_mcp.request_context import get_conversation_id, get_user_agent
 
 logger = logging.getLogger(__name__)
 
@@ -57,19 +58,33 @@ class SessionContext:
 
 
 def _get_client(ctx: FuturesearchContext) -> AuthenticatedClient:
-    """Get an FutureSearch API client from the FastMCP lifespan context."""
-    return ctx.request_context.lifespan_context.client_factory()
+    """Get a FutureSearch API client with MCP client identity headers."""
+    client = ctx.request_context.lifespan_context.client_factory()
+    extra_headers = _extract_client_headers(ctx)
+    logger.debug(f"Setting extra headers to {extra_headers}")
+    if extra_headers:
+        client = client.with_headers(extra_headers)
+    return client
+
+
+def _extract_client_headers(ctx: FuturesearchContext) -> dict[str, str]:
+    """Build X-MCP-Client-* headers from MCP client params or User-Agent."""
+    headers: dict[str, str] = {}
+    cp = ctx.session.client_params
+    if cp and cp.clientInfo:
+        if cp.clientInfo.name:
+            headers["X-MCP-Client-Name"] = cp.clientInfo.name
+        if cp.clientInfo.version:
+            headers["X-MCP-Client-Version"] = cp.clientInfo.version
+    elif user_agent := get_user_agent():
+        headers["X-MCP-Client-Name"] = user_agent
+    return headers
 
 
 def _get_conversation_id() -> str | None:
     """Get the conversation ID from the current HTTP request context, if any."""
-    try:
-        from futuresearch_mcp.http_config import get_conversation_id  # noqa: PLC0415
-
-        val = get_conversation_id()
-        return val if val else None
-    except Exception:
-        return None
+    val = get_conversation_id()
+    return val if val else None
 
 
 def create_linked_session(
@@ -88,8 +103,6 @@ def log_client_info(ctx: FuturesearchContext, tool_name: str) -> None:
         if not cp:
             # Stateless HTTP mode — no MCP initialize handshake.
             # Fall back to User-Agent from the HTTP request.
-            from futuresearch_mcp.http_config import get_user_agent  # noqa: PLC0415
-
             ua = get_user_agent()
             logger.info(
                 "[%s] client_params=None (stateless) ua=%s",
@@ -180,8 +193,6 @@ def _widgets_from_user_agent() -> bool:
     Only clients we have confirmed can render widgets get them; unknown UAs
     default to text-only to avoid wasting context tokens on unsupported UIs.
     """
-    from futuresearch_mcp.http_config import get_user_agent  # noqa: PLC0415
-
     ua = get_user_agent().lower()
 
     # Whitelist of UA substrings for clients that support widgets.
@@ -203,8 +214,6 @@ def _widgets_from_user_agent() -> bool:
 
 def is_internal_client() -> bool:
     """Return True if the request comes from FutureSearch's own app."""
-    from futuresearch_mcp.http_config import get_user_agent  # noqa: PLC0415
-
     return "futuresearch" in get_user_agent().lower()
 
 

futuresearch-mcp/tests/test_server.py

@@ -169,6 +169,7 @@ def _make_mock_client():
     client.__aenter__ = AsyncMock(return_value=client)
     client.__aexit__ = AsyncMock(return_value=None)
     client.token = "fake-token"
+    client.with_headers = MagicMock(return_value=client)
     return client
 
 

futuresearch-mcp/tests/test_stdio_content.py

@@ -146,6 +146,7 @@ def _make_mock_client():
     client.token = "fake-token"
     client.__aenter__ = AsyncMock(return_value=client)
     client.__aexit__ = AsyncMock(return_value=None)
+    client.with_headers = MagicMock(return_value=client)
     return client
 
 

futuresearch-mcp/tests/test_ua_detection.py

@@ -6,7 +6,7 @@
 
 from futuresearch_mcp.tool_helpers import _widgets_from_user_agent, is_internal_client
 
-_UA_PATCH = "futuresearch_mcp.http_config.get_user_agent"
+_UA_PATCH = "futuresearch_mcp.tool_helpers.get_user_agent"
 
 
 class TestWidgetsFromUserAgent:

src/futuresearch/api_utils.py

@@ -1,4 +1,5 @@
 import os
+from importlib.metadata import version
 from typing import TypeVar
 
 from futuresearch.constants import DEFAULT_FUTURESEARCH_API_URL, FuturesearchError
@@ -35,9 +36,11 @@ def create_client() -> AuthenticatedClient:
         or os.environ.get("EVERYROW_API_URL")
         or DEFAULT_FUTURESEARCH_API_URL
     )
+    sdk_version = version("futuresearch")
     return AuthenticatedClient(
         base_url=api_url,
         token=api_key,
+        headers={"X-SDK-Version": f"futuresearch-python/{sdk_version}"},
         raise_on_unexpected_status=True,
         follow_redirects=True,
     )