@langwatch/mcp-server 2.2.0 → 3.0.0

package/pyproject.toml

@@ -7,21 +7,36 @@ requires-python = ">=3.11"
 dependencies = [
   "ipykernel>=7.3.0",
   "langwatch",
-  "litellm>=1.96.0",
-  "mcp[cli]>=2.0.0",
+  "litellm>=1.100.4", # security: litellm advisories up to GHSA-7hp6-4w63-5g45, fixed in 1.100.4
+  "mcp[cli]>=2.2.0", # security: MCP SDK unbounded StreamableHTTP sessions, fixed in 2.2.0 (#2823)
   "pandas>=2.3.2",
   "tenacity>=9.1.4",
 ]
 
 [tool.uv]
+# exclude-newer-package below needs uv 0.9.25+ (dev/docs/best_practices/dependency-age-gates.md).
+required-version = ">=0.9.25"
 exclude-newer = "7 days"
 
+# Security fix released inside the 7-day window above, admitted up to a fixed
+# date so the rest of the tree keeps the cooldown. Drop it once the date is
+# more than 7 days old (#8958).
+exclude-newer-package = { certifi = "2026-10-21T00:00:00Z" }
+
 # Transitive-dependency security pins. Keep these even when the importing
 # package isn't a direct dependency, so a future re-resolution can't silently
 # pull a vulnerable version back in.
 constraint-dependencies = [
   "python-dotenv>=1.2.2", # security: python-dotenv advisory (#934)
   "python-liquid>=2.2.1", # security: python-liquid advisory (#1528)
+  "tornado>=6.5.9", # security: tornado advisories (#2159, #2173, #2233, #2665-#2667)
+  "anyio>=4.14.2", # security: anyio advisories (#2430, #2431)
+  "httpx2>=2.12.0", # security: httpx2 advisories (#2312, #2313, #2329)
+  "pyjwt>=2.15.0", # security: PyJWT advisories covering <=2.14.0 (#2479, #2615)
+  "urllib3>=2.8.0", # security: urllib3 advisories covering <2.8.0 (#2591, #2592, #2608)
+  "fsspec>=2026.6.0", # security: fsspec advisory covering <2026.6.0 (#2731)
+  "aiohttp>=3.14.4", # security: aiohttp advisories covering <=3.14.3, two HIGH (#2842-#2844)
+  "certifi>=2026.10.19", # security: certifi advisory covering <2026.10.19 (#2897)
 ]
 
 [tool.uv.sources]

package/src/config.d.ts

@@ -2,6 +2,8 @@ export interface McpConfig {
   apiKey: string | undefined;
   endpoint: string;
   projectId?: string;
+  /** Set by the hosted MCP server, so the platform tells its calls from a local server's. */
+  hosted?: boolean;
 }
 
 export declare function initConfig(args: {

package/src/config.ts

@@ -4,6 +4,8 @@ export interface McpConfig {
   apiKey: string | undefined;
   endpoint: string;
   projectId?: string;
+  /** Set by the hosted MCP server, so the platform tells its calls from a local server's. */
+  hosted?: boolean;
 }
 
 // Store on globalThis to share config between CJS and ESM module instances.

package/src/create-mcp-server.ts

@@ -28,6 +28,7 @@ import {
   triggerActionSchema,
   validateActionParamsForAction,
 } from "./schemas/triggers.ts";
+import { widgetSourcesInput } from "./schemas/widget-sources.ts";
 import { handleExperimentResults } from "./tools/get-experiment-results.ts";
 import { handleExperimentListRuns } from "./tools/list-experiment-runs.ts";
 import { handleExperimentList } from "./tools/list-experiments.ts";
@@ -38,7 +39,7 @@ import { handleUpdateTestSuite } from "./tools/update-test-suite.ts";
 const modelSchema = z
   .string()
   .describe(
-    'Model in "provider/model-name" format, e.g., "openai/gpt-4o", "anthropic/claude-sonnet-4-5-20250929"',
+    'Model in "provider/model-name" format, e.g., "openai/gpt-6-luna", "anthropic/claude-sonnet-4-5-20250929"',
   );
 
 /**
@@ -91,6 +92,7 @@ function registerTools(server: McpServer): void {
   registerEvaluatorTools(server);
   registerModelProviderTools(server);
   registerAgentTools(server);
+  registerAnalyticsReportTools(server);
   registerDashboardTools(server);
   registerWorkflowTools(server);
   registerAnnotationTools(server);
@@ -1321,97 +1323,110 @@ function registerAgentTools(server: McpServer): void {
   );
 }
 
-// --- Platform Dashboard Tools (require API key) ---
-function registerDashboardTools(server: McpServer): void {
+// --- Platform Analytics Report Tools (require API key) ---
+function registerAnalyticsReportTools(server: McpServer): void {
   server.tool(
-    "platform_list_dashboards",
-    "List all analytics dashboards in the LangWatch project.",
+    "platform_list_analytics_reports",
+    "List the Analytics Reports in the LangWatch project (/api/v1/analytics/reports). Dashboards, which hold widgets, are listed by list_dashboards.",
     {},
-    withToolLogging("platform_list_dashboards", async () => {
+    withToolLogging("platform_list_analytics_reports", async () => {
       requireApiKey();
-      const { handleListDashboards } = await import("./tools/list-dashboards.ts");
+      const { handleListAnalyticsReports } = await import("./tools/list-analytics-reports.ts");
       return {
-        content: [{ type: "text", text: await handleListDashboards() }],
+        content: [{ type: "text", text: await handleListAnalyticsReports() }],
       };
     }),
   );
 
   server.tool(
-    "platform_get_dashboard",
-    "Get a dashboard by its ID, including its graphs.",
+    "platform_get_analytics_report",
+    "Get an Analytics Report by its ID, including its graphs. A Dashboards dashboard's ID is not found here; read it with get_dashboard.",
     {
-      id: z.string().describe("The dashboard ID"),
+      reportId: z.string().describe("The Analytics Report ID"),
     },
-    withToolLogging("platform_get_dashboard", async (params) => {
+    withToolLogging("platform_get_analytics_report", async (params) => {
       requireApiKey();
-      const { handleGetDashboard } = await import("./tools/get-dashboard.ts");
+      const { handleGetAnalyticsReport } = await import("./tools/get-analytics-report.ts");
       return {
-        content: [{ type: "text", text: await handleGetDashboard(params) }],
+        content: [{ type: "text", text: await handleGetAnalyticsReport(params) }],
       };
     }),
   );
 
   server.tool(
-    "platform_create_dashboard",
-    "Create a new analytics dashboard.",
+    "platform_create_analytics_report",
+    "Create a new Analytics Report.",
     {
-      name: z.string().describe("Dashboard name"),
+      name: z.string().describe("Analytics Report name"),
     },
-    withToolLogging("platform_create_dashboard", async (params) => {
+    withToolLogging("platform_create_analytics_report", async (params) => {
       requireApiKey();
-      const { handleCreateDashboard } = await import("./tools/create-dashboard.ts");
+      const { handleCreateAnalyticsReport } = await import("./tools/create-analytics-report.ts");
       return {
-        content: [{ type: "text", text: await handleCreateDashboard(params) }],
+        content: [
+          {
+            type: "text",
+            text: await handleCreateAnalyticsReport(params),
+          },
+        ],
       };
     }),
   );
 
   server.tool(
-    "platform_delete_dashboard",
-    "Delete a dashboard and all its graphs.",
+    "platform_delete_analytics_report",
+    "Delete an Analytics Report and all its graphs.",
     {
-      id: z.string().describe("The dashboard ID to delete"),
+      reportId: z.string().describe("The Analytics Report ID to delete"),
     },
-    withToolLogging("platform_delete_dashboard", async (params) => {
+    withToolLogging("platform_delete_analytics_report", async (params) => {
       requireApiKey();
-      const { handleDeleteDashboard } = await import("./tools/delete-dashboard.ts");
+      const { handleDeleteAnalyticsReport } = await import("./tools/delete-analytics-report.ts");
       return {
-        content: [{ type: "text", text: await handleDeleteDashboard(params) }],
+        content: [
+          {
+            type: "text",
+            text: await handleDeleteAnalyticsReport(params),
+          },
+        ],
       };
     }),
   );
 
   server.tool(
-    "platform_rename_dashboard",
-    "Rename a dashboard.",
+    "platform_rename_analytics_report",
+    "Rename an Analytics Report.",
     {
-      id: z.string().describe("The dashboard ID to rename"),
-      name: z.string().describe("The new name for the dashboard"),
+      reportId: z.string().describe("The Analytics Report ID to rename"),
+      name: z.string().describe("The new name for the Analytics Report"),
     },
-    withToolLogging("platform_rename_dashboard", async (params) => {
+    withToolLogging("platform_rename_analytics_report", async (params) => {
       requireApiKey();
-      const { renameDashboard } = await import("./langwatch-api-dashboards.ts");
-      const result = await renameDashboard(params.id, { name: params.name });
+      const { renameAnalyticsReport } = await import("./langwatch-api-analytics-reports.ts");
+      const result = await renameAnalyticsReport({ reportId: params.reportId, name: params.name });
       return {
         content: [
           {
             type: "text",
-            text: `Dashboard "${result.name}" renamed successfully (ID: ${result.id}).`,
+            text: `Analytics Report "${result.name}" renamed successfully (ID: ${result.id}).`,
           },
         ],
       };
     }),
   );
+}
 
+// --- Dashboard Tools (require API key) ---
+function registerDashboardTools(server: McpServer): void {
   server.tool(
-    "list_dashboard_boards",
-    "Lists the project's boards in the Dashboards area, with each one's ID and widget count. Use an ID from here as the dashboardId of add_dashboard_widget and update_dashboard_widget; the analytics dashboards platform_list_dashboards lists hold no widgets.",
+    "list_dashboards",
+    "Lists the project's dashboards in the Dashboards area, with each one's ID and widget count. Use an ID from here as the dashboardId of add_dashboard_widget and update_dashboard_widget; the Analytics Reports platform_list_analytics_reports lists hold no widgets.",
     {},
-    withToolLogging("list_dashboard_boards", async () => {
+    withToolLogging("list_dashboards", async () => {
       requireApiKey();
-      const { handleListDashboardBoards } = await import("./tools/list-dashboard-boards.js");
+      const { handleListDashboards } = await import("./tools/list-dashboards.js");
       return {
-        content: [{ type: "text", text: await handleListDashboardBoards() }],
+        content: [{ type: "text", text: await handleListDashboards() }],
       };
     }),
   );
@@ -1422,7 +1437,7 @@ function registerDashboardTools(server: McpServer): void {
     {
       dashboardId: z
         .string()
-        .describe("The Dashboards board to add the widget to, as list_dashboard_boards lists it"),
+        .describe("The dashboard to add the widget to, as list_dashboards lists it"),
       name: z.string().describe("The widget's display name"),
       code: z
         .string()
@@ -1444,6 +1459,7 @@ function registerDashboardTools(server: McpServer): void {
         .describe(
           "The widget's named LangWatchQL queries: either {name: sql} or an array of {name, sql}. Max 8. Validate each statement with run_query first.",
         ),
+      sources: widgetSourcesInput,
     },
     withToolLogging("add_dashboard_widget", async (params) => {
       requireApiKey();
@@ -1456,7 +1472,7 @@ function registerDashboardTools(server: McpServer): void {
 
   server.tool(
     "update_dashboard_widget",
-    "Changes one custom widget on a dashboard: its name, its TSX `code`, its named LangWatchQL `queries` or its `description`. Pass only the fields to change; every field left out keeps its stored value. Validate any new query's SQL with run_query first. Returns the updated widget.",
+    "Changes one custom widget on a dashboard: its name, its TSX `code`, its named LangWatchQL `queries`, its `description` or the `sources` its queries count. Pass only the fields to change; every field left out keeps its stored value. Validate any new query's SQL with run_query first. Returns the updated widget.",
     {
       dashboardId: z.string().describe("The dashboard the widget is on"),
       widgetId: z.string().describe("The widget to change, as add_dashboard_widget returned it"),
@@ -1487,6 +1503,7 @@ function registerDashboardTools(server: McpServer): void {
         .string()
         .optional()
         .describe("What the widget's info tip says: a sentence or two"),
+      sources: widgetSourcesInput,
     },
     withToolLogging("update_dashboard_widget", async (params) => {
       requireApiKey();
@@ -1496,6 +1513,87 @@ function registerDashboardTools(server: McpServer): void {
       };
     }),
   );
+
+  registerDashboardCrudTools(server);
+}
+
+/** Dashboard CRUD and a dashboard's widgets, over `/api/v1/dashboards`. */
+function registerDashboardCrudTools(server: McpServer): void {
+  const dashboardId = z.string().describe("The dashboard's ID, as list_dashboards lists it");
+  const text = (value: string) => ({ content: [{ type: "text" as const, text: value }] });
+
+  server.tool(
+    "get_dashboard",
+    "Reads one dashboard in the Dashboards area: its name, scope, description and address. An Analytics Report's ID is not found here; read it with platform_get_analytics_report.",
+    { dashboardId },
+    withToolLogging("get_dashboard", async (params) => {
+      requireApiKey();
+      const { handleGetDashboard } = await import("./tools/dashboards.js");
+      return text(await handleGetDashboard(params));
+    }),
+  );
+
+  server.tool(
+    "create_dashboard",
+    "Creates an empty dashboard in the Dashboards area. Add widgets to it with add_dashboard_widget.",
+    { name: z.string().describe("The dashboard's name") },
+    withToolLogging("create_dashboard", async (params) => {
+      requireApiKey();
+      const { handleCreateDashboard } = await import("./tools/dashboards.js");
+      return text(await handleCreateDashboard(params));
+    }),
+  );
+
+  server.tool(
+    "rename_dashboard",
+    "Changes a dashboard's name and/or description; a field left out keeps its value.",
+    {
+      dashboardId,
+      name: z.string().optional().describe("The dashboard's new name"),
+      description: z.string().optional().describe("The dashboard's new description"),
+    },
+    withToolLogging("rename_dashboard", async (params) => {
+      requireApiKey();
+      const { handleRenameDashboard } = await import("./tools/dashboards.js");
+      return text(await handleRenameDashboard(params));
+    }),
+  );
+
+  server.tool(
+    "delete_dashboard",
+    "Deletes a dashboard together with the widgets on it. This cannot be undone.",
+    { dashboardId },
+    withToolLogging("delete_dashboard", async (params) => {
+      requireApiKey();
+      const { handleDeleteDashboard } = await import("./tools/dashboards.js");
+      return text(await handleDeleteDashboard(params));
+    }),
+  );
+
+  server.tool(
+    "list_dashboard_widgets",
+    "Lists the custom widgets on one dashboard, with each widget's ID and query names.",
+    { dashboardId },
+    withToolLogging("list_dashboard_widgets", async (params) => {
+      requireApiKey();
+      const { handleListDashboardWidgets } = await import("./tools/dashboards.js");
+      return text(await handleListDashboardWidgets(params));
+    }),
+  );
+
+  server.tool(
+    "delete_dashboard_widget",
+    "Deletes one custom widget from a dashboard. A widget on another dashboard is not found.",
+    {
+      dashboardId,
+      widgetId: z.string().describe("The widget's ID, as list_dashboard_widgets lists it"),
+    },
+    withToolLogging("delete_dashboard_widget", async (params) => {
+      requireApiKey();
+      const { handleDeleteDashboardWidget } = await import("./tools/dashboards.js");
+      return text(await handleDeleteDashboardWidget(params));
+    }),
+  );
 }
 
 // --- Platform Workflow Tools (require API key) ---
@@ -2026,6 +2124,15 @@ function registerExperimentTools(server: McpServer): void {
     "Start an experiment run by slug. Returns a run ID for polling status.",
     {
       slug: z.string().describe("The experiment slug to run"),
+      concurrency: z
+        .number()
+        .int()
+        .min(1)
+        .max(24)
+        .optional()
+        .describe(
+          "Cells (one row against one target) to run at once, for this run only (default: the server's setting). Use 1 to run them one at a time, in order.",
+        ),
     },
     withToolLogging("platform_run_experiment", async (params) => {
       requireApiKey();

package/src/langwatch-api-analytics-reports.ts

@@ -0,0 +1,62 @@
+import { makeRequest } from "./langwatch-api.ts";
+
+/** An Analytics Report, at `/api/v1/analytics/reports`. Dashboards live at `/api/v1/dashboards`. */
+export interface AnalyticsReportSummary {
+  id: string;
+  name: string;
+  order: number;
+  graphCount: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface AnalyticsReportDetail extends AnalyticsReportSummary {
+  graphs: unknown[];
+}
+
+export interface AnalyticsReportListResponse {
+  data: AnalyticsReportSummary[];
+}
+
+const reportPath = (reportId: string) =>
+  `/api/v1/analytics/reports/${encodeURIComponent(reportId)}`;
+
+export async function listAnalyticsReports(): Promise<AnalyticsReportListResponse> {
+  return makeRequest("GET", "/api/v1/analytics/reports") as Promise<AnalyticsReportListResponse>;
+}
+
+export async function getAnalyticsReport({
+  reportId,
+}: {
+  reportId: string;
+}): Promise<AnalyticsReportDetail> {
+  return makeRequest("GET", reportPath(reportId)) as Promise<AnalyticsReportDetail>;
+}
+
+export async function createAnalyticsReport({
+  name,
+}: {
+  name: string;
+}): Promise<AnalyticsReportDetail> {
+  return makeRequest("POST", "/api/v1/analytics/reports", {
+    name,
+  }) as Promise<AnalyticsReportDetail>;
+}
+
+export async function renameAnalyticsReport({
+  reportId,
+  name,
+}: {
+  reportId: string;
+  name: string;
+}): Promise<AnalyticsReportDetail> {
+  return makeRequest("PATCH", reportPath(reportId), { name }) as Promise<AnalyticsReportDetail>;
+}
+
+export async function deleteAnalyticsReport({
+  reportId,
+}: {
+  reportId: string;
+}): Promise<{ id: string; name: string }> {
+  return makeRequest("DELETE", reportPath(reportId)) as Promise<{ id: string; name: string }>;
+}

package/src/langwatch-api-dashboard-widgets.ts

@@ -1,4 +1,4 @@
-import { makeRequest } from "./langwatch-api.js";
+import type { WidgetSource } from "./schemas/widget-sources.js";
 
 /**
  * One named LangWatchQL statement a widget may run, as the REST endpoint validates it
@@ -12,6 +12,8 @@ export interface DashboardWidgetQueryInput {
     type: "string" | "number" | "boolean";
     default?: string | number | boolean;
   }[];
+  /** The trace origins the query counts; `null` makes it unset, counting application. */
+  sources?: WidgetSource[] | null;
 }
 
 /** Where a widget came from, as the platform records it. */
@@ -43,70 +45,3 @@ export interface DashboardWidget {
   colSpan: number;
   rowSpan: number;
 }
-
-/** Saves a new widget, unplaced (not yet on any dashboard). */
-export async function createDashboardWidget(params: {
-  projectId: string;
-  name: string;
-  code: string;
-  queries: DashboardWidgetQueryInput[];
-}): Promise<DashboardWidget> {
-  const { projectId, ...data } = params;
-  return makeRequest(
-    "POST",
-    `/api/v1/projects/${encodeURIComponent(projectId)}/analytics/dashboard-widgets`,
-    data,
-  ) as Promise<DashboardWidget>;
-}
-
-/** Reads one widget; a widget in another project answers 404. */
-export async function getDashboardWidget(params: {
-  projectId: string;
-  widgetId: string;
-}): Promise<DashboardWidget> {
-  return makeRequest(
-    "GET",
-    `/api/v1/projects/${encodeURIComponent(params.projectId)}/analytics/dashboard-widgets/${encodeURIComponent(params.widgetId)}`,
-  ) as Promise<DashboardWidget>;
-}
-
-/** Changes the fields given; every field left out keeps its stored value. */
-export async function updateDashboardWidget(params: {
-  projectId: string;
-  widgetId: string;
-  name?: string;
-  code?: string;
-  queries?: DashboardWidgetQueryInput[];
-  description?: string;
-}): Promise<DashboardWidget> {
-  const { projectId, widgetId, ...data } = params;
-  return makeRequest(
-    "PATCH",
-    `/api/v1/projects/${encodeURIComponent(projectId)}/analytics/dashboard-widgets/${encodeURIComponent(widgetId)}`,
-    data,
-  ) as Promise<DashboardWidget>;
-}
-
-/** Places an existing widget on a dashboard, at the next free row. */
-export async function assignDashboardWidgetToDashboard(params: {
-  projectId: string;
-  widgetId: string;
-  dashboardId: string;
-}): Promise<DashboardWidget> {
-  return makeRequest(
-    "POST",
-    `/api/v1/projects/${encodeURIComponent(params.projectId)}/analytics/dashboard-widgets/${encodeURIComponent(params.widgetId)}/dashboard`,
-    { dashboardId: params.dashboardId },
-  ) as Promise<DashboardWidget>;
-}
-
-/** Deletes a widget. Used to undo a create when placing it fails. */
-export async function deleteDashboardWidget(params: {
-  projectId: string;
-  widgetId: string;
-}): Promise<void> {
-  await makeRequest(
-    "DELETE",
-    `/api/v1/projects/${encodeURIComponent(params.projectId)}/analytics/dashboard-widgets/${encodeURIComponent(params.widgetId)}`,
-  );
-}