@digital-science-dsl/dimensions-analytics-mcp 1.0.3 → 1.1.0

package/dist/mcp/usage-tracking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-tracking.js","sourceRoot":"","sources":["../../src/mcp/usage-tracking.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,GAAG,MAAM,oBAAoB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAC3D,OAAO,EAEL,cAAc,EACd,kBAAkB,GACnB,MAAM,4BAA4B,CAAC;AAQpC;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAgC;IACnE,kBAAkB,CAAC;QACjB,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,UAAU,EAAE;QAC5C,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,SAAS;QACnC,OAAO,EAAE,GAAG,CAAC,OAAO;KACrB,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAAgB,EAChB,OAAoD;IAEpD,OAAO,KAAK,EAAE,IAAW,EAAE,EAAE,CAAC,cAAc,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;AAC9E,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAiB,EACjB,QAAgB,EAChB,MAA+B;AAC/B,sFAAsF;AACtF,OAA2B;IAE3B,MAAM,CAAC,YAAY,CACjB,QAAQ,EACR,MAAM,EACN,oBAAoB,CAAC,QAAQ,EAAE,OAAO,CAA6C,CACpF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CAAC,SAA6B;IAClE,IAAI,CAAC,SAAS;QAAE,OAAO,SAAS,CAAC;IACjC,MAAM,EAAE,GAAG,SAAS,CAAC,WAAW,EAAE,CAAC;IACnC,IAAI,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC3C,IAAI,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,gBAAgB,CAAC;IACnD,IAAI,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,oBAAoB,CAAC;QAAE,OAAO,QAAQ,CAAC;IAChF,IAAI,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC;QAAE,OAAO,UAAU,CAAC;IAC/C,IAAI,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,SAAS,CAAC;IAC7C,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digital-science-dsl/dimensions-analytics-mcp",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "Dimensions Analytics MCP server for Dimensions DSL querying",
   "type": "module",
   "main": "./dist/index.js",

package/src/client/deployment-config.ts

@@ -1,5 +1,8 @@
 /**
  * Deployment mode and hosted backend configuration from environment.
+ *
+ * Hosted usage tracking: MCP sends X-Dimensions-* headers on dsl-service requests
+ * (see usage-headers.ts). dsl-service derives channel/user fields server-side.
  * @module client/deployment-config
  */
 
@@ -51,42 +54,6 @@ export function hostedBootstrapUser(host: string): string {
   return `mcp@${host}`;
 }
 
-/**
- * MCP-prefixed user label for dsl usage logs (reversible plus-addressing).
- */
-export function mcpTrackingUser(dimensionsUser: string): string {
-  const at = dimensionsUser.indexOf("@");
-  if (at <= 0) return `mcp+${dimensionsUser}`;
-  return `mcp+${dimensionsUser.slice(0, at)}${dimensionsUser.slice(at)}`;
-}
-
-export interface HostedDslLoggingInfo {
-  user: string;
-  dimensions_user: string;
-  channel: "mcp";
-  mcp_user: string;
-  product_variant: string;
-  source: "dimensions-analytics-mcp-hosted";
-}
-
-/**
- * `additional_logging_info` for hosted dsl-service queries.
- * `X-DIMENSIONS-USER` stays the canonical Dimensions user; channel fields tag MCP traffic.
- */
-export function buildHostedDslLoggingInfo(
-  dimensionsUser: string,
-  variant: string,
-): HostedDslLoggingInfo {
-  return {
-    user: dimensionsUser,
-    dimensions_user: dimensionsUser,
-    channel: "mcp",
-    mcp_user: mcpTrackingUser(dimensionsUser),
-    product_variant: variant,
-    source: "dimensions-analytics-mcp-hosted",
-  };
-}
-
 /**
  * Loads deployment configuration from environment variables.
  * @throws {Error} When hosted mode is enabled but required vars are missing

package/src/client/http-client.ts

@@ -18,6 +18,9 @@ import {
   UnprocessableEntityError,
 } from "./errors.js";
 import type { RateLimiter } from "./rate-limiter.js";
+import { executeRequestWithRetry } from "./request-retry.js";
+import { getMcpUsageSession } from "./usage-context.js";
+import { buildMcpUsageHeaders, buildMcpUserAgent } from "./usage-headers.js";
 
 /**
  * Configuration options for the HTTP client.
@@ -145,10 +148,24 @@ export class HttpClient {
     dsl: string,
     options?: RequestOptions,
   ): Promise<DimensionsResponse> {
+    const sessionHeaders: Record<string, string> = {};
+    const usageHeaders = buildMcpUsageHeaders();
+    if (Object.keys(usageHeaders).length > 0) {
+      Object.assign(sessionHeaders, usageHeaders);
+      const session = getMcpUsageSession();
+      if (session) {
+        sessionHeaders["User-Agent"] = buildMcpUserAgent(session.version, session.client);
+      }
+    }
+
     return this.wrapFetch<DimensionsResponse>({
       url,
       method: "POST",
-      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        ...sessionHeaders,
+        ...options?.headers,
+      },
       body: dsl,
       timeoutMs: options?.timeout ?? this.timeout,
       signal: options?.signal,
@@ -301,41 +318,16 @@ export class HttpClient {
   }
 
   /**
-   * Determines if an error is retryable.
-   * @param error - Error to check
-   * @returns True if the error should be retried
-   */
-  private isRetryable(error: unknown): boolean {
-    // Retry rate limit errors
-    if (error instanceof RateLimitError) {
-      return true;
-    }
-
-    // Retry server errors (5xx)
-    if (error instanceof ServerError) {
-      return true;
-    }
-
-    // Retry network errors
-    if (error instanceof NetworkError) {
-      return true;
-    }
-
-    // Retry timeout errors
-    if (error instanceof TimeoutError) {
-      return true;
-    }
-
-    // Don't retry other errors (400, 401, 403, etc.)
-    return false;
-  }
-
-  /**
-   * Delays execution for the specified time.
-   * @param ms - Delay in milliseconds
+   * Executes a request with retry logic.
+   * @param requestFn - Function that executes the request
+   * @returns Response from successful request
    */
-  private delay(ms: number): Promise<void> {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+  private async executeWithRetry<T>(requestFn: () => Promise<T>): Promise<T> {
+    return executeRequestWithRetry(requestFn, {
+      maxRetries: this.maxRetries,
+      retryDelay: this.retryDelay,
+      rateLimiter: this.rateLimiter,
+    });
   }
 
   /**
@@ -394,64 +386,6 @@ export class HttpClient {
     });
   }
 
-  /**
-   * Calculates the delay before the next retry attempt.
-   * For rate-limit errors, uses the client rate limiter's slot timing.
-   * For other transient errors, uses exponential backoff with jitter.
-   * The result is capped at 60 seconds.
-   * @param error - The error that triggered the retry
-   * @param attempt - The current attempt number (0-based)
-   * @returns Delay in milliseconds
-   */
-  private calculateRetryDelay(error: unknown, attempt: number): number {
-    const MAX_DELAY = 60_000;
-
-    if (error instanceof RateLimitError) {
-      const delay =
-        error.clientRateLimit?.retryAfterMs ??
-        this.rateLimiter?.getRetryDelayMs() ??
-        2000 * 2 ** attempt;
-      return Math.min(delay, MAX_DELAY);
-    }
-
-    const backoff = this.retryDelay * 2 ** attempt * (0.5 + Math.random() * 0.5);
-    return Math.min(backoff, MAX_DELAY);
-  }
-
-  /**
-   * Executes a request with retry logic.
-   * Uses client-side throttling before each attempt and exponential backoff for transient errors.
-   * @param requestFn - Function that executes the request
-   * @returns Response from successful request
-   */
-  private async executeWithRetry<T>(requestFn: () => Promise<T>): Promise<T> {
-    let lastError: Error | null = null;
-
-    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
-      await this.rateLimiter?.waitIfNeeded();
-      try {
-        const result = await requestFn();
-        this.rateLimiter?.recordRequest();
-        return result;
-      } catch (error) {
-        lastError = error as Error;
-
-        if (!this.isRetryable(error)) {
-          throw error;
-        }
-
-        if (attempt >= this.maxRetries) {
-          throw error;
-        }
-
-        const retryDelay = this.calculateRetryDelay(error, attempt);
-        await this.delay(retryDelay);
-      }
-    }
-
-    throw lastError ?? new NetworkError("Unknown error occurred");
-  }
-
   /**
    * Sends a POST request with JSON body.
    * @param path - URL path (appended to baseUrl)

package/src/client/internal-dsl-client.ts

@@ -1,27 +1,39 @@
 /**
- * dsl-service adapter for hosted deployment (POST /query, JSON body).
+ * dsl-service adapter for hosted deployment (POST /query).
+ * Usage metadata is sent via X-Dimensions-* headers (see usage-headers.ts), not JSON body.
  * @module client/internal-dsl-client
  */
 
-import { buildHostedDslLoggingInfo, type InternalDslEnvConfig } from "./deployment-config.js";
+import type { InternalDslEnvConfig } from "./deployment-config.js";
 import {
   AuthenticationError,
   DimensionsError,
   NetworkError,
   QuerySyntaxError,
+  RateLimitError,
   ServerError,
   sanitizeErrorMessage,
   TimeoutError,
 } from "./errors.js";
+import type { RateLimiter } from "./rate-limiter.js";
+import { executeRequestWithRetry } from "./request-retry.js";
 import type { DslResponse, QueryExecutorOptions } from "./types.js";
+import { getMcpUsageSession } from "./usage-context.js";
+import { buildMcpUsageHeaders, buildMcpUserAgent } from "./usage-headers.js";
 
 export interface InternalDslClientOptions {
   readonly config: InternalDslEnvConfig;
   /** User email for X-DIMENSIONS-USER (required by dsl-service) */
   readonly userEmail: string;
-  /** Optional client IP to forward */
+  /**
+   * End-user IP forwarded as X-Forwarded-For for dsl-service per-IP throttling.
+   * Set from the inbound MCP HTTP request (see mcp/http-server.ts).
+   */
   readonly clientIp?: string;
   readonly timeout?: number;
+  readonly maxRetries?: number;
+  readonly retryDelay?: number;
+  readonly rateLimiter?: RateLimiter;
 }
 
 /**
@@ -32,29 +44,51 @@ export class InternalDslClient {
   private readonly userEmail: string;
   private readonly clientIp?: string;
   private readonly timeout: number;
+  private readonly maxRetries: number;
+  private readonly retryDelay: number;
+  private readonly rateLimiter?: RateLimiter;
 
   constructor(options: InternalDslClientOptions) {
     this.config = options.config;
     this.userEmail = options.userEmail;
     this.clientIp = options.clientIp;
     this.timeout = options.timeout ?? 30_000;
+    this.maxRetries = options.maxRetries ?? 3;
+    this.retryDelay = options.retryDelay ?? 1000;
+    this.rateLimiter = options.rateLimiter;
   }
 
   /**
    * Runs a DSL query through dsl-service POST /query.
    */
   async query(dsl: string, options?: QueryExecutorOptions): Promise<DslResponse> {
+    return executeRequestWithRetry(() => this.executeQuery(dsl, options), {
+      maxRetries: this.maxRetries,
+      retryDelay: this.retryDelay,
+      rateLimiter: this.rateLimiter,
+    });
+  }
+
+  private async executeQuery(dsl: string, options?: QueryExecutorOptions): Promise<DslResponse> {
     const url = `${this.config.serviceUrl.replace(/\/$/, "")}/query`;
     const controller = new AbortController();
     const timeoutMs = options?.timeout ?? this.timeout;
     const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
 
+    const session = getMcpUsageSession();
+    const usageHeaders = buildMcpUsageHeaders();
+
     const headers: Record<string, string> = {
       "Content-Type": "application/json",
       "X-DIMENSIONS-USER": this.userEmail,
       Authorization: `Basic ${Buffer.from(`${this.config.username}:${this.config.password}`).toString("base64")}`,
+      ...usageHeaders,
     };
 
+    if (session) {
+      headers["User-Agent"] = buildMcpUserAgent(session.version, session.client);
+    }
+
     if (this.clientIp) {
       headers["X-Forwarded-For"] = this.clientIp;
     }
@@ -64,7 +98,6 @@ export class InternalDslClient {
       dsl_schema: this.config.dslSchema,
       host: this.config.host,
       variant: this.config.variant,
-      additional_logging_info: buildHostedDslLoggingInfo(this.userEmail, this.config.variant),
     };
 
     try {
@@ -114,6 +147,17 @@ export class InternalDslClient {
         return new AuthenticationError(message);
       case 400:
         return new QuerySyntaxError(message);
+      case 429: {
+        const retryAfterMs = this.rateLimiter?.getRetryDelayMs() ?? 2000;
+        return new RateLimitError(
+          "Rate limit exceeded — wait before retrying",
+          Math.ceil(retryAfterMs / 1000),
+          {
+            remaining: this.rateLimiter?.getRemainingRequests() ?? 0,
+            retryAfterMs,
+          },
+        );
+      }
       default:
         if (response.status >= 500) {
           return new ServerError(message, response.status);

package/src/client/request-retry.ts

@@ -0,0 +1,115 @@
+/**
+ * Shared retry logic for Dimensions HTTP clients (public API and dsl-service).
+ * @module client/request-retry
+ */
+
+import { NetworkError, RateLimitError, ServerError, TimeoutError } from "./errors.js";
+import type { RateLimiter } from "./rate-limiter.js";
+
+export interface RequestRetryOptions {
+  readonly maxRetries: number;
+  readonly retryDelay: number;
+  readonly rateLimiter?: RateLimiter;
+}
+
+type DelayFn = (ms: number) => Promise<void>;
+
+let delayFn: DelayFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Delays before the next retry attempt. Exported for unit tests.
+ */
+export async function requestRetryDelay(ms: number): Promise<void> {
+  return delayFn(ms);
+}
+
+/**
+ * Overrides retry delay behaviour in unit tests.
+ * @internal
+ */
+export function setRequestRetryDelayFn(fn: DelayFn): void {
+  delayFn = fn;
+}
+
+/**
+ * Restores default retry delay behaviour after tests.
+ * @internal
+ */
+export function resetRequestRetryDelayFn(): void {
+  delayFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Returns true when a failed request should be retried.
+ */
+export function isRetryableRequestError(error: unknown): boolean {
+  if (error instanceof RateLimitError) {
+    return true;
+  }
+  if (error instanceof ServerError) {
+    return true;
+  }
+  if (error instanceof NetworkError) {
+    return true;
+  }
+  if (error instanceof TimeoutError) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Calculates delay before the next retry (rate-limit aware, exponential backoff with jitter).
+ */
+export function calculateRequestRetryDelay(
+  error: unknown,
+  attempt: number,
+  options: Pick<RequestRetryOptions, "retryDelay" | "rateLimiter">,
+): number {
+  const MAX_DELAY = 60_000;
+
+  if (error instanceof RateLimitError) {
+    const delay =
+      error.clientRateLimit?.retryAfterMs ??
+      options.rateLimiter?.getRetryDelayMs() ??
+      2000 * 2 ** attempt;
+    return Math.min(delay, MAX_DELAY);
+  }
+
+  const backoff = options.retryDelay * 2 ** attempt * (0.5 + Math.random() * 0.5);
+  return Math.min(backoff, MAX_DELAY);
+}
+
+/**
+ * Executes a request with client-side throttling and retries for transient failures.
+ */
+export async function executeRequestWithRetry<T>(
+  requestFn: () => Promise<T>,
+  options: RequestRetryOptions,
+): Promise<T> {
+  let lastError: Error | null = null;
+
+  for (let attempt = 0; attempt <= options.maxRetries; attempt++) {
+    await options.rateLimiter?.waitIfNeeded();
+    try {
+      const result = await requestFn();
+      options.rateLimiter?.recordRequest();
+      return result;
+    } catch (error) {
+      lastError = error as Error;
+
+      if (!isRetryableRequestError(error)) {
+        throw error;
+      }
+
+      if (attempt >= options.maxRetries) {
+        throw error;
+      }
+
+      const retryDelay = calculateRequestRetryDelay(error, attempt, options);
+      await requestRetryDelay(retryDelay);
+    }
+  }
+
+  throw lastError ?? new NetworkError("Unknown error occurred");
+}

package/src/client/usage-context.ts

@@ -0,0 +1,53 @@
+/**
+ * Async-local MCP usage context for dsl-service request headers.
+ * @module client/usage-context
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export type McpDeploymentMode = "hosted" | "local";
+
+export interface McpUsageSession {
+  readonly sessionId: string;
+  readonly deployment: McpDeploymentMode;
+  readonly client: string;
+  readonly version: string;
+}
+
+export interface McpUsageCall {
+  readonly tool: string;
+}
+
+const sessionStorage = new AsyncLocalStorage<McpUsageSession>();
+const callStorage = new AsyncLocalStorage<McpUsageCall>();
+
+let activeSession: McpUsageSession | undefined;
+
+/**
+ * Installs session-level MCP usage metadata for the lifetime of a server instance.
+ */
+export function setMcpUsageSession(session: McpUsageSession): void {
+  activeSession = session;
+}
+
+export function getMcpUsageSession(): McpUsageSession | undefined {
+  return sessionStorage.getStore() ?? activeSession;
+}
+
+/**
+ * Runs a function with session-level usage context (nested over the active session).
+ */
+export function runWithMcpUsageSession<T>(session: McpUsageSession, fn: () => T): T {
+  return sessionStorage.run(session, fn);
+}
+
+/**
+ * Runs an MCP tool handler with per-call usage context (tool name).
+ */
+export function runWithMcpTool<T>(tool: string, fn: () => T): T {
+  return callStorage.run({ tool }, fn);
+}
+
+export function getActiveMcpTool(): string | undefined {
+  return callStorage.getStore()?.tool;
+}

package/src/client/usage-headers.ts

@@ -0,0 +1,45 @@
+/**
+ * X-Dimensions-* usage tracking headers for dsl-service.
+ * @module client/usage-headers
+ */
+
+import { getActiveMcpTool, getMcpUsageSession } from "./usage-context.js";
+
+export const USAGE_HEADER_CHANNEL = "X-Dimensions-Channel";
+export const USAGE_HEADER_MCP_TOOL = "X-Dimensions-MCP-Tool";
+export const USAGE_HEADER_MCP_SESSION_ID = "X-Dimensions-MCP-Session-Id";
+export const USAGE_HEADER_MCP_CLIENT = "X-Dimensions-MCP-Client";
+export const USAGE_HEADER_MCP_VERSION = "X-Dimensions-MCP-Version";
+export const USAGE_HEADER_MCP_DEPLOYMENT = "X-Dimensions-MCP-Deployment";
+
+/**
+ * Builds usage tracking headers from the active MCP session and tool context.
+ */
+export function buildMcpUsageHeaders(): Record<string, string> {
+  const session = getMcpUsageSession();
+  if (!session) {
+    return {};
+  }
+
+  const headers: Record<string, string> = {
+    [USAGE_HEADER_CHANNEL]: "mcp",
+    [USAGE_HEADER_MCP_SESSION_ID]: session.sessionId,
+    [USAGE_HEADER_MCP_CLIENT]: session.client,
+    [USAGE_HEADER_MCP_VERSION]: session.version,
+    [USAGE_HEADER_MCP_DEPLOYMENT]: session.deployment,
+  };
+
+  const tool = getActiveMcpTool();
+  if (tool) {
+    headers[USAGE_HEADER_MCP_TOOL] = tool;
+  }
+
+  return headers;
+}
+
+/**
+ * User-Agent string identifying the MCP server and client app.
+ */
+export function buildMcpUserAgent(version: string, client: string): string {
+  return `dimensions-analytics-mcp/${version} (${client})`;
+}

package/src/dsl/client.ts

@@ -98,15 +98,18 @@ export class DimensionsClient {
 
     if (this.config.backend === "internal") {
       const internal = this.config.internal!;
+      this.rateLimiter = new RateLimiter({
+        maxRequests: 1000,
+        windowMs: 60_000,
+      });
       this.internalClient = new InternalDslClient({
         config: internal.service,
         userEmail: internal.userEmail,
         clientIp: internal.clientIp,
         timeout: this.config.timeout,
-      });
-      this.rateLimiter = new RateLimiter({
-        maxRequests: 1000,
-        windowMs: 60_000,
+        maxRetries: this.config.maxRetries,
+        retryDelay: this.config.retryDelay,
+        rateLimiter: this.rateLimiter,
       });
       return;
     }

package/src/dsl/schema/structured-entities.ts

@@ -13,6 +13,10 @@ export const STRUCTURED_ENTITY_TYPES = [
   "datasets",
   "policy_documents",
   "organizations",
+  "reports",
+  "source_titles",
+  "funder_groups",
+  "research_org_groups",
 ] as const;
 
 /** A source with a structured search tool. */

package/src/dsl/types/vocabulary.ts

@@ -18,7 +18,11 @@ export type EntityType =
   | "clinical_trials"
   | "datasets"
   | "policy_documents"
-  | "organizations";
+  | "organizations"
+  | "reports"
+  | "source_titles"
+  | "funder_groups"
+  | "research_org_groups";
 
 /** Search indexes for `search <source> in <index> for "..."` clauses. */
 export type SearchIndex =
@@ -34,7 +38,8 @@ export type SearchIndex =
   | "acknowledgements"
   | "raw_affiliations"
   | "assignees"
-  | "title_abstract_claims";
+  | "title_abstract_claims"
+  | "name";
 
 /** Sort direction for order-by clauses. */
 export type SortOrder = "asc" | "desc";
@@ -62,6 +67,10 @@ export const VALID_ENTITIES: readonly EntityType[] = [
   "datasets",
   "policy_documents",
   "organizations",
+  "reports",
+  "source_titles",
+  "funder_groups",
+  "research_org_groups",
 ] as const;
 
 /** Valid search indexes for runtime validation. */
@@ -79,4 +88,5 @@ export const VALID_INDEXES: readonly SearchIndex[] = [
   "raw_affiliations",
   "assignees",
   "title_abstract_claims",
+  "name",
 ] as const;

package/src/mcp/examples/dsl-examples.ts

@@ -39,6 +39,18 @@ export const DSL_EXAMPLES_BY_ENTITY: Record<string, readonly string[]> = {
     'search organizations for "Stanford" return organizations limit 10',
     'search organizations where country = "United States" return organizations limit 10',
   ],
+  reports: [
+    'search reports for "climate change" return reports[basics] limit 10',
+    "search reports where year >= 2020 return reports[id+title+year] limit 20",
+  ],
+  source_titles: [
+    'search source_titles for "Nature" return source_titles[basics] limit 10',
+    'search source_titles where type = "journal" return source_titles[id+title+issn+sjr] limit 20',
+  ],
+  funder_groups: ['search funder_groups for "NIH" return funder_groups[basics] limit 10'],
+  research_org_groups: [
+    'search research_org_groups for "Ivy League" return research_org_groups[basics] limit 10',
+  ],
 };
 
 /** General DSL patterns (describe, functions, pagination). */

package/src/mcp/http-server.ts

@@ -3,6 +3,7 @@
  * @module mcp/http-server
  */
 
+import { randomUUID } from "node:crypto";
 import type { IncomingMessage, Server } from "node:http";
 import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
@@ -11,6 +12,7 @@ import type { HostedEnvConfig } from "../client/deployment-config.js";
 import { AuthenticationError } from "../client/errors.js";
 import { parseBearerToken, resolveUserFromApiKey } from "../client/resolve-api-key-user.js";
 import { createMcpServerAsync, warmHostedSchemaCache } from "./server.js";
+import { mcpClientFromUserAgent } from "./usage-tracking.js";
 
 export interface HostedHttpServerOptions {
   readonly hosted: HostedEnvConfig;
@@ -57,11 +59,18 @@ export function startHostedHttpServer(options: HostedHttpServerOptions): HostedH
         clientIp,
       });
 
+      const mcpSessionId = randomUUID();
+      const mcpClient = mcpClientFromUserAgent(
+        typeof req.headers["user-agent"] === "string" ? req.headers["user-agent"] : undefined,
+      );
+
       const { server } = await createMcpServerAsync({
         deploymentMode: "hosted",
         hosted: options.hosted,
         userEmail,
         clientIp,
+        mcpSessionId,
+        mcpClient,
       });
 
       const transport = new StreamableHTTPServerTransport({