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

package/src/mcp/middleware/field-aliases.ts

@@ -103,6 +103,10 @@ export const ENTITY_ALIASES: Readonly<Record<EntityType, Readonly<Record<string,
   policy_documents: { ...POLICY_DOCUMENT_ALIASES },
   researchers: { ...RESEARCHER_ALIASES },
   organizations: { ...ORGANIZATION_ALIASES },
+  reports: {},
+  source_titles: {},
+  funder_groups: {},
+  research_org_groups: {},
 };
 
 // ---------------------------------------------------------------------------

package/src/mcp/server.ts

@@ -27,6 +27,7 @@ import { registerLookupTools } from "./tools/lookup.js";
 import { registerQueryTools } from "./tools/query.js";
 import { registerSchemaTools, validateFieldAliases } from "./tools/schema.js";
 import { registerSearchTools } from "./tools/search.js";
+import { initMcpUsageTracking } from "./usage-tracking.js";
 
 /**
  * Configuration options for the MCP server.
@@ -46,6 +47,10 @@ export interface McpServerConfig {
   userEmail?: string;
   /** Client IP to forward to dsl-service and auth.json */
   clientIp?: string;
+  /** MCP session id for usage tracking */
+  mcpSessionId?: string;
+  /** Coarse MCP client label (cursor, vscode, etc.) */
+  mcpClient?: string;
 }
 
 /**
@@ -98,6 +103,8 @@ export function buildServerInstructions(schemaStore: SchemaStore): string {
       "search_researchers matches names only — topic→researcher uses facet_query (entityType publications, facetField researchers);",
       "search_grants funderOrgName needs exact Dimensions names (NCI/NSF acronyms resolve; discover funders via facet_query/aggregate_query on facetField funder_orgs);",
       "search_organizations for institution lookup — prefer GRID id in filters when the name is ambiguous;",
+      "search_source_titles for journals / ISSN lookup (not articles); search_reports for technical reports;",
+      "search_funder_groups / search_research_org_groups for curated group name → member GRID ids;",
       "facet_query supports yearFrom/yearTo for year-scoped facets.",
     ].join(" "),
     [
@@ -153,6 +160,7 @@ async function loadSchemaForServer(
  * Warms the shared schema cache for hosted deployment (call once at process startup).
  */
 export async function warmHostedSchemaCache(hosted: HostedEnvConfig): Promise<SchemaStore> {
+  initMcpUsageTracking({ deployment: "hosted", client: "bootstrap" });
   const client = createBootstrapDimensionsClient(hosted);
   return getSharedSchemaStore(client);
 }
@@ -168,6 +176,12 @@ export async function createMcpServerAsync(config: McpServerConfig = {}): Promis
 }> {
   const { mode, hosted } = resolveDeployment(config);
 
+  initMcpUsageTracking({
+    deployment: mode,
+    client: config.mcpClient ?? (mode === "local" ? "stdio" : "unknown"),
+    sessionId: config.mcpSessionId,
+  });
+
   const client = createDimensionsClient({
     mode,
     hosted: hosted ?? config.hosted,

package/src/mcp/tools/analytics-filters.ts

@@ -14,6 +14,8 @@ const ENTITY_YEAR_FIELD: Partial<Record<EntityType, string>> = {
   clinical_trials: "year",
   datasets: "year",
   policy_documents: "year",
+  reports: "year",
+  source_titles: "start_year",
 };
 
 /**

package/src/mcp/tools/analytics.ts

@@ -16,6 +16,7 @@ import {
 } from "../../dsl/index.js";
 import { resolveFacetFieldName, withFieldAliases } from "../middleware/field-aliases.js";
 import type { SchemaStore } from "../schema/index.js";
+import { registerTrackedTool } from "../usage-tracking.js";
 import { formatErrorResult, formatToolResult, READ_ONLY_API_ANNOTATIONS } from "../utils.js";
 import { applyAnalyticsFilters } from "./analytics-filters.js";
 
@@ -123,7 +124,8 @@ export function registerAnalyticsTools(
   const entityTypeSchema = entityTypeEnum(schemaStore);
 
   // Facet Query
-  server.registerTool(
+  registerTrackedTool(
+    server,
     "facet_query",
     {
       description:
@@ -212,7 +214,8 @@ export function registerAnalyticsTools(
   );
 
   // Aggregate Query
-  server.registerTool(
+  registerTrackedTool(
+    server,
     "aggregate_query",
     {
       description:
@@ -320,7 +323,8 @@ export function registerAnalyticsTools(
   );
 
   // Citation Trend
-  server.registerTool(
+  registerTrackedTool(
+    server,
     "citation_trend",
     {
       description:
@@ -382,7 +386,8 @@ export function registerAnalyticsTools(
   );
 
   // Funding Trend
-  server.registerTool(
+  registerTrackedTool(
+    server,
     "funding_trend",
     {
       description:

package/src/mcp/tools/fetch-search-pages.ts

@@ -24,6 +24,7 @@ import {
 import { queryHashFromDsl, runAggregateFetch, runFileFetch } from "../batch-fetch.js";
 import { resolveExportFormat } from "../export-format.js";
 import { withFieldAliases } from "../middleware/field-aliases.js";
+import { registerTrackedTool } from "../usage-tracking.js";
 import {
   formatErrorResult,
   formatToolResult,
@@ -84,7 +85,8 @@ export function registerFetchSearchPagesTools(
 ): void {
   const entityList = schemaStore.structuredEntityTypes().join(", ");
 
-  server.registerTool(
+  registerTrackedTool(
+    server,
     "fetch_search_pages",
     {
       description:

package/src/mcp/tools/functions.ts

@@ -7,6 +7,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import type { DimensionsClient } from "../../dsl/index.js";
+import { registerTrackedTool } from "../usage-tracking.js";
 import { formatErrorResult, formatToolResult, READ_ONLY_API_ANNOTATIONS } from "../utils.js";
 
 /**
@@ -15,7 +16,8 @@ import { formatErrorResult, formatToolResult, READ_ONLY_API_ANNOTATIONS } from "
  * @param client - Dimensions client instance
  */
 export function registerFunctionTools(server: McpServer, client: DimensionsClient): void {
-  server.registerTool(
+  registerTrackedTool(
+    server,
     "extract_affiliations",
     {
       description:
@@ -61,7 +63,8 @@ export function registerFunctionTools(server: McpServer, client: DimensionsClien
     },
   );
 
-  server.registerTool(
+  registerTrackedTool(
+    server,
     "extract_grants",
     {
       description:

package/src/mcp/tools/lookup.ts

@@ -8,6 +8,7 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { type DimensionsClient, EntitySchema, type EntityType } from "../../dsl/index.js";
 import { withFieldAliases } from "../middleware/field-aliases.js";
+import { registerTrackedTool } from "../usage-tracking.js";
 import {
   asArray,
   formatErrorResult,
@@ -22,7 +23,8 @@ import {
  */
 export function registerLookupTools(server: McpServer, client: DimensionsClient): void {
   // Get publication by DOI
-  server.registerTool(
+  registerTrackedTool(
+    server,
     "get_by_doi",
     {
       description:
@@ -75,7 +77,8 @@ export function registerLookupTools(server: McpServer, client: DimensionsClient)
   );
 
   // Get publication by PubMed ID
-  server.registerTool(
+  registerTrackedTool(
+    server,
     "get_by_pmid",
     {
       description:
@@ -128,11 +131,12 @@ export function registerLookupTools(server: McpServer, client: DimensionsClient)
   );
 
   // Get entity by Dimensions ID
-  server.registerTool(
+  registerTrackedTool(
+    server,
     "get_by_id",
     {
       description:
-        "Retrieve any entity by its Dimensions ID. Supports publications, grants, patents, clinical trials, datasets, policy documents, researchers, and organizations.",
+        "Retrieve any entity by its Dimensions ID. Supports publications, grants, patents, clinical trials, datasets, policy documents, researchers, organizations, reports, source titles, funder groups, and research org groups.",
       inputSchema: {
         entityType: EntitySchema.describe("The type of entity to look up"),
         id: z.string().describe("The Dimensions ID to look up"),

package/src/mcp/tools/query.ts

@@ -12,6 +12,7 @@ import {
   validateExecuteDslPolicy,
 } from "../../dsl/index.js";
 import type { SchemaStore } from "../schema/index.js";
+import { registerTrackedTool } from "../usage-tracking.js";
 import { formatErrorResult, formatToolResult } from "../utils.js";
 
 /**
@@ -26,7 +27,8 @@ export function registerQueryTools(
   schemaStore: SchemaStore,
 ): void {
   const sources = schemaStore.structuredEntityTypes().join(", ");
-  server.registerTool(
+  registerTrackedTool(
+    server,
     "execute_dsl",
     {
       description: `Execute a raw Dimensions DSL query. Read dimensions://schema/policy and dimensions://examples first. Official docs: https://docs.dimensions.ai/dsl/

package/src/mcp/tools/schema.ts

@@ -9,6 +9,7 @@ import type { DimensionsClient } from "../../dsl/index.js";
 import { buildReverseAliasMap } from "../middleware/field-aliases.js";
 import type { SchemaContext } from "../schema/context.js";
 import { loadSchema, type SchemaStore } from "../schema/index.js";
+import { registerTrackedTool } from "../usage-tracking.js";
 import { formatErrorResult, formatToolResult, READ_ONLY_API_ANNOTATIONS } from "../utils.js";
 
 /**
@@ -22,7 +23,8 @@ export function registerSchemaTools(
   client: DimensionsClient,
   context: SchemaContext,
 ): void {
-  server.registerTool(
+  registerTrackedTool(
+    server,
     "describe_schema",
     {
       description:
@@ -98,7 +100,8 @@ export function registerSchemaTools(
     },
   );
 
-  server.registerTool(
+  registerTrackedTool(
+    server,
     "refresh_schema",
     {
       description:

package/src/mcp/tools/search-entity-metadata.ts

@@ -250,4 +250,54 @@ export const SEARCH_ENTITY_METADATA: readonly SearchEntityMetadata[] = [
       sortBy: z.enum(["name"]).optional().describe("Sort results by this field"),
     },
   },
+  {
+    source: "reports",
+    description:
+      "Search technical reports in the Dimensions database. Returns report titles, abstracts, responsible organizations, funders, and related metadata.",
+    applyConvenienceFilters: (builder, args) => {
+      yearRange("yearFrom", "yearTo", "year")(builder, args);
+    },
+    extraInputSchema: {
+      yearFrom: z.number().int().optional().describe("Filter reports from this year (inclusive)"),
+      yearTo: z.number().int().optional().describe("Filter reports up to this year (inclusive)"),
+      sortBy: z.enum(["year", "date"]).optional().describe("Sort results by this field"),
+    },
+  },
+  {
+    source: "source_titles",
+    description:
+      "Search publication source titles (journals, preprint platforms, book series, proceedings) in the Dimensions database. " +
+      "Use for journal / ISSN lookup — not for searching articles (use search_publications).",
+    applyConvenienceFilters: (builder, args) => {
+      if (typeof args.sourceTitleType === "string") {
+        builder.where("type", "=", args.sourceTitleType);
+      }
+    },
+    extraInputSchema: {
+      sourceTitleType: z
+        .enum(["journal", "book_series", "proceeding", "preprint_platform"])
+        .optional()
+        .describe("Filter by source title type"),
+      sortBy: z
+        .enum(["sjr", "snip", "start_year"])
+        .optional()
+        .describe("Sort results by this field"),
+    },
+  },
+  {
+    source: "funder_groups",
+    description:
+      "Search curated funder groups in the Dimensions database. Returns group name and member organization GRID IDs. " +
+      "Query matches group names (search index: name).",
+    applyConvenienceFilters: noop,
+    extraInputSchema: {},
+  },
+  {
+    source: "research_org_groups",
+    description:
+      "Search curated research organization groups in the Dimensions database. Returns group name and member organization GRID IDs. " +
+      "Query matches group names (search index: name).",
+    applyConvenienceFilters: noop,
+    extraInputSchema: {},
+  },
 ];

package/src/mcp/tools/search.ts

@@ -19,6 +19,7 @@ import {
   validateSearchPaginationPolicy,
 } from "../../dsl/index.js";
 import { withFieldAliases } from "../middleware/field-aliases.js";
+import { registerTrackedTool } from "../usage-tracking.js";
 import {
   formatErrorResult,
   formatToolResult,
@@ -99,7 +100,8 @@ export function registerSearchTools(
     const resultKey = searchResultKey(source);
     const toolName = searchToolName(source);
 
-    server.registerTool(
+    registerTrackedTool(
+      server,
       toolName,
       {
         description: meta.description,

package/src/mcp/usage-tracking.ts

@@ -0,0 +1,72 @@
+/**
+ * MCP tool usage tracking helpers.
+ * @module mcp/usage-tracking
+ */
+
+import { randomUUID } from "node:crypto";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import pkg from "../../package.json" with { type: "json" };
+import {
+  type McpDeploymentMode,
+  runWithMcpTool,
+  setMcpUsageSession,
+} from "../client/usage-context.js";
+
+export interface McpUsageTrackingOptions {
+  readonly deployment: McpDeploymentMode;
+  readonly client?: string;
+  readonly sessionId?: string;
+}
+
+/**
+ * Initializes session-level MCP usage metadata for a server instance.
+ */
+export function initMcpUsageTracking(options: McpUsageTrackingOptions): void {
+  setMcpUsageSession({
+    sessionId: options.sessionId ?? randomUUID(),
+    deployment: options.deployment,
+    client: options.client ?? "unknown",
+    version: pkg.version,
+  });
+}
+
+/**
+ * Wraps a tool handler so the active tool name is available for usage headers.
+ */
+export function withMcpUsageTracking<TArgs, TResult>(
+  toolName: string,
+  handler: (args: TArgs) => TResult | Promise<TResult>,
+): (args: TArgs) => Promise<TResult> {
+  return async (args: TArgs) => runWithMcpTool(toolName, () => handler(args));
+}
+
+/**
+ * Registers an MCP tool with usage tracking for dsl-service headers.
+ */
+export function registerTrackedTool(
+  server: McpServer,
+  toolName: string,
+  config: Record<string, unknown>,
+  // biome-ignore lint/suspicious/noExplicitAny: preserve MCP SDK tool handler inference
+  handler: (args: any) => any,
+): void {
+  server.registerTool(
+    toolName,
+    config,
+    withMcpUsageTracking(toolName, handler) as Parameters<McpServer["registerTool"]>[2],
+  );
+}
+
+/**
+ * Derives a coarse MCP client label from an HTTP User-Agent header.
+ */
+export function mcpClientFromUserAgent(userAgent: string | undefined): string {
+  if (!userAgent) return "unknown";
+  const ua = userAgent.toLowerCase();
+  if (ua.includes("cursor")) return "cursor";
+  if (ua.includes("claude")) return "claude-desktop";
+  if (ua.includes("vscode") || ua.includes("visual studio code")) return "vscode";
+  if (ua.includes("windsurf")) return "windsurf";
+  if (ua.includes("copilot")) return "copilot";
+  return "unknown";
+}

package/test/client/deployment-config.test.ts

@@ -4,12 +4,7 @@
  */
 
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import {
-  buildHostedDslLoggingInfo,
-  hostedBootstrapUser,
-  loadDeploymentConfig,
-  mcpTrackingUser,
-} from "../../src/client/deployment-config.js";
+import { hostedBootstrapUser, loadDeploymentConfig } from "../../src/client/deployment-config.js";
 
 const HOSTED_ENV = {
   DEPLOYMENT_MODE: "hosted",
@@ -72,22 +67,3 @@ describe("hostedBootstrapUser", () => {
     expect(hostedBootstrapUser("app.dimensions.ai")).toBe("mcp@app.dimensions.ai");
   });
 });
-
-describe("mcpTrackingUser", () => {
-  it("prefixes canonical email with mcp+", () => {
-    expect(mcpTrackingUser("alice@university.edu")).toBe("mcp+alice@university.edu");
-  });
-});
-
-describe("buildHostedDslLoggingInfo", () => {
-  it("includes channel metadata for dsl-service logs", () => {
-    expect(buildHostedDslLoggingInfo("alice@university.edu", "standard")).toEqual({
-      user: "alice@university.edu",
-      dimensions_user: "alice@university.edu",
-      channel: "mcp",
-      mcp_user: "mcp+alice@university.edu",
-      product_variant: "standard",
-      source: "dimensions-analytics-mcp-hosted",
-    });
-  });
-});

package/test/client/http-client.test.ts

@@ -10,6 +10,7 @@ import {
 } from "../../src/client/errors.js";
 import { HttpClient } from "../../src/client/http-client.js";
 import { RateLimiter } from "../../src/client/rate-limiter.js";
+import * as requestRetry from "../../src/client/request-retry.js";
 
 /**
  * Creates a mock auth provider for testing.
@@ -42,6 +43,7 @@ describe("HttpClient", () => {
 
   afterEach(() => {
     globalThis.fetch = originalFetch;
+    requestRetry.resetRequestRetryDelayFn();
     vi.restoreAllMocks();
   });
 
@@ -156,7 +158,7 @@ describe("HttpClient", () => {
 
   describe("retry behavior", () => {
     it("retries on 429 rate limit error", async () => {
-      vi.spyOn(client as never, "delay" as never).mockResolvedValue(undefined as never);
+      requestRetry.setRequestRetryDelayFn(async () => {});
 
       const mockFetch = vi
         .fn()
@@ -239,7 +241,7 @@ describe("HttpClient", () => {
     });
 
     it("exhausts retries and throws RateLimitError", async () => {
-      vi.spyOn(client as never, "delay" as never).mockResolvedValue(undefined as never);
+      requestRetry.setRequestRetryDelayFn(async () => {});
 
       const mockFetch = vi.fn().mockResolvedValue({
         ok: false,
@@ -279,9 +281,8 @@ describe("HttpClient", () => {
         rateLimiter,
       });
 
-      const delaySpy = vi
-        .spyOn(limitedClient as never, "delay" as never)
-        .mockResolvedValue(undefined as never);
+      const delaySpy = vi.fn(async () => {});
+      requestRetry.setRequestRetryDelayFn(delaySpy);
 
       const mockFetch = vi
         .fn()
@@ -304,9 +305,8 @@ describe("HttpClient", () => {
     });
 
     it("uses exponential backoff for 5xx errors", async () => {
-      const delaySpy = vi
-        .spyOn(client as never, "delay" as never)
-        .mockResolvedValue(undefined as never);
+      const delaySpy = vi.fn(async () => {});
+      requestRetry.setRequestRetryDelayFn(delaySpy);
 
       const mockFetch = vi
         .fn()
@@ -349,9 +349,8 @@ describe("HttpClient", () => {
         retryDelay: 100000, // Very large base delay
       });
 
-      const delaySpy = vi
-        .spyOn(largeDelayClient as never, "delay" as never)
-        .mockResolvedValue(undefined as never);
+      const delaySpy = vi.fn(async () => {});
+      requestRetry.setRequestRetryDelayFn(delaySpy);
 
       const mockFetch = vi
         .fn()
@@ -385,9 +384,10 @@ describe("HttpClient", () => {
         rateLimiter,
       });
 
-      const delaySpy = vi
-        .spyOn(limitedClient as never, "delay" as never)
-        .mockResolvedValue(undefined as never);
+      const delays: number[] = [];
+      requestRetry.setRequestRetryDelayFn(async (ms) => {
+        delays.push(ms);
+      });
 
       const mockFetch = vi
         .fn()
@@ -405,8 +405,8 @@ describe("HttpClient", () => {
 
       await limitedClient.query("search publications");
 
-      expect(delaySpy).toHaveBeenCalledTimes(1);
-      expect(delaySpy).toHaveBeenCalledWith(60_000);
+      expect(delays).toHaveLength(1);
+      expect(delays[0]).toBe(60_000);
     });
   });
 
@@ -865,7 +865,7 @@ describe("HttpClient", () => {
     });
 
     it("retries postJson on rate limit error", async () => {
-      vi.spyOn(client as never, "delay" as never).mockResolvedValue(undefined as never);
+      requestRetry.setRequestRetryDelayFn(async () => {});
 
       const mockFetch = vi
         .fn()

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

@@ -6,6 +6,16 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { QuerySyntaxError } from "../../src/client/errors.js";
 import { InternalDslClient } from "../../src/client/internal-dsl-client.js";
+import * as requestRetry from "../../src/client/request-retry.js";
+import { runWithMcpTool, setMcpUsageSession } from "../../src/client/usage-context.js";
+import {
+  USAGE_HEADER_CHANNEL,
+  USAGE_HEADER_MCP_CLIENT,
+  USAGE_HEADER_MCP_DEPLOYMENT,
+  USAGE_HEADER_MCP_SESSION_ID,
+  USAGE_HEADER_MCP_TOOL,
+  USAGE_HEADER_MCP_VERSION,
+} from "../../src/client/usage-headers.js";
 import { mockFetchJson } from "./helpers/mock-fetch.js";
 
 const CONFIG = {
@@ -22,10 +32,18 @@ describe("InternalDslClient", () => {
 
   afterEach(() => {
     globalThis.fetch = originalFetch;
+    requestRetry.resetRequestRetryDelayFn();
     vi.restoreAllMocks();
   });
 
-  it("posts JSON query with service auth and user header", async () => {
+  it("posts JSON query with service auth, user header, and MCP usage headers", async () => {
+    setMcpUsageSession({
+      sessionId: "550e8400-e29b-41d4-a716-446655440000",
+      deployment: "hosted",
+      client: "cursor",
+      version: "1.0.4",
+    });
+
     const responseBody = { publications: [] };
     const mock = mockFetchJson(responseBody);
 
@@ -35,7 +53,9 @@ describe("InternalDslClient", () => {
       clientIp: "198.51.100.4",
     });
 
-    const result = await client.query("search publications return publications limit 1");
+    const result = await runWithMcpTool("search_publications", () =>
+      client.query("search publications return publications limit 1"),
+    );
 
     expect(result).toEqual(responseBody);
     expect(mock).toHaveBeenCalledWith(
@@ -47,20 +67,19 @@ describe("InternalDslClient", () => {
           "X-DIMENSIONS-USER": "user@example.com",
           "X-Forwarded-For": "198.51.100.4",
           Authorization: `Basic ${Buffer.from("svc:secret").toString("base64")}`,
+          [USAGE_HEADER_CHANNEL]: "mcp",
+          [USAGE_HEADER_MCP_TOOL]: "search_publications",
+          [USAGE_HEADER_MCP_SESSION_ID]: "550e8400-e29b-41d4-a716-446655440000",
+          [USAGE_HEADER_MCP_CLIENT]: "cursor",
+          [USAGE_HEADER_MCP_VERSION]: "1.0.4",
+          [USAGE_HEADER_MCP_DEPLOYMENT]: "hosted",
+          "User-Agent": "dimensions-analytics-mcp/1.0.4 (cursor)",
         }),
         body: JSON.stringify({
           query: "search publications return publications limit 1",
           dsl_schema: "external",
           host: "app.example.com",
           variant: "standard",
-          additional_logging_info: {
-            user: "user@example.com",
-            dimensions_user: "user@example.com",
-            channel: "mcp",
-            mcp_user: "mcp+user@example.com",
-            product_variant: "standard",
-            source: "dimensions-analytics-mcp-hosted",
-          },
         }),
       }),
     );
@@ -76,4 +95,48 @@ describe("InternalDslClient", () => {
 
     await expect(client.query("bad query")).rejects.toBeInstanceOf(QuerySyntaxError);
   });
+
+  it("retries on 429 and 5xx like the public HttpClient", async () => {
+    requestRetry.setRequestRetryDelayFn(async () => {});
+
+    const mockFetch = vi
+      .fn()
+      .mockResolvedValueOnce({
+        ok: false,
+        status: 429,
+        statusText: "Too Many Requests",
+        json: () => Promise.resolve({ error: "rate limited" }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ publications: [] }),
+      });
+    globalThis.fetch = mockFetch;
+
+    const client = new InternalDslClient({
+      config: CONFIG,
+      userEmail: "user@example.com",
+      clientIp: "198.51.100.4",
+      maxRetries: 2,
+      retryDelay: 10,
+    });
+
+    const result = await client.query("search publications return publications limit 1");
+    expect(result).toEqual({ publications: [] });
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not set X-Forwarded-For when clientIp is omitted", async () => {
+    mockFetchJson({ publications: [] });
+
+    const client = new InternalDslClient({
+      config: CONFIG,
+      userEmail: "user@example.com",
+    });
+
+    await client.query("search publications return publications limit 1");
+
+    const [, fetchOptions] = (globalThis.fetch as ReturnType<typeof vi.fn>).mock.calls[0];
+    expect(fetchOptions.headers["X-Forwarded-For"]).toBeUndefined();
+  });
 });