@langwatch/mcp-server 2.2.0 → 3.0.0

package/src/langwatch-api-dashboards.ts

@@ -1,51 +1,133 @@
-import { makeRequest } from "./langwatch-api.ts";
+import type {
+  DashboardWidget,
+  DashboardWidgetQueryInput,
+} from "./langwatch-api-dashboard-widgets.js";
+import { makeRequest } from "./langwatch-api.js";
 
-export interface DashboardSummary {
+/**
+ * A dashboard in the Dashboards area, at `/api/v1/dashboards`; the project comes from the API key
+ * (`modules/dashboard/contract/src/board-rest.schemas.ts`). Every route answers 404 while
+ * Dashboards is off for the key's project. Analytics Reports live at `/api/v1/analytics/reports`.
+ */
+export interface Dashboard {
   id: string;
   name: string;
-  order: number;
-  graphCount: number;
+  description: string | null;
+  scope: "PRIVATE" | "PROJECT" | "ORGANIZATION";
+  createdById: string | null;
   createdAt: string;
   updatedAt: string;
+  platformUrl: string;
 }
 
-export interface DashboardDetail extends DashboardSummary {
-  graphs: unknown[];
+export interface DashboardListItem extends Dashboard {
+  widgetCount: number;
 }
 
-export interface DashboardListResponse {
-  data: DashboardSummary[];
+const dashboardPath = (dashboardId: string) =>
+  `/api/v1/dashboards/${encodeURIComponent(dashboardId)}`;
+const widgetPath = (dashboardId: string, widgetId: string) =>
+  `${dashboardPath(dashboardId)}/widgets/${encodeURIComponent(widgetId)}`;
+
+/** The key's project's dashboards, each with how many widgets it holds. */
+export async function listDashboards(): Promise<{ data: DashboardListItem[] }> {
+  return makeRequest("GET", "/api/v1/dashboards") as Promise<{ data: DashboardListItem[] }>;
+}
+
+/** Reads one dashboard; a dashboard in another project, or an Analytics Report, answers 404. */
+export async function getDashboard({ dashboardId }: { dashboardId: string }): Promise<Dashboard> {
+  return makeRequest("GET", dashboardPath(dashboardId)) as Promise<Dashboard>;
+}
+
+export async function createDashboard({ name }: { name: string }): Promise<Dashboard> {
+  return makeRequest("POST", "/api/v1/dashboards", { name }) as Promise<Dashboard>;
+}
+
+/** A field left out keeps its value; a `null` description clears it. */
+export async function updateDashboard({
+  dashboardId,
+  ...changes
+}: {
+  dashboardId: string;
+  name?: string;
+  description?: string | null;
+}): Promise<Dashboard> {
+  return makeRequest("PATCH", dashboardPath(dashboardId), changes) as Promise<Dashboard>;
 }
 
-export async function listDashboards(): Promise<DashboardListResponse> {
-  return makeRequest("GET", "/api/v1/dashboards") as Promise<DashboardListResponse>;
+/** Deletes the dashboard with the widgets on it. */
+export async function deleteDashboard({
+  dashboardId,
+}: {
+  dashboardId: string;
+}): Promise<{ id: string; name: string }> {
+  return makeRequest("DELETE", dashboardPath(dashboardId)) as Promise<{ id: string; name: string }>;
 }
 
-export async function getDashboard(id: string): Promise<DashboardDetail> {
+export async function listWidgetsOnDashboard({
+  dashboardId,
+}: {
+  dashboardId: string;
+}): Promise<{ data: DashboardWidget[] }> {
+  return makeRequest("GET", `${dashboardPath(dashboardId)}/widgets`) as Promise<{
+    data: DashboardWidget[];
+  }>;
+}
+
+/** Saves a widget placed on this dashboard at the next free row. */
+export async function createWidgetOnDashboard({
+  dashboardId,
+  ...data
+}: {
+  dashboardId: string;
+  name: string;
+  code: string;
+  queries: DashboardWidgetQueryInput[];
+  description?: string;
+}): Promise<DashboardWidget> {
   return makeRequest(
-    "GET",
-    `/api/v1/dashboards/${encodeURIComponent(id)}`,
-  ) as Promise<DashboardDetail>;
+    "POST",
+    `${dashboardPath(dashboardId)}/widgets`,
+    data,
+  ) as Promise<DashboardWidget>;
 }
 
-export async function createDashboard(data: { name: string }): Promise<DashboardDetail> {
-  return makeRequest("POST", "/api/v1/dashboards", data) as Promise<DashboardDetail>;
+/** A widget on any other dashboard answers 404. */
+export async function getWidgetOnDashboard({
+  dashboardId,
+  widgetId,
+}: {
+  dashboardId: string;
+  widgetId: string;
+}): Promise<DashboardWidget> {
+  return makeRequest("GET", widgetPath(dashboardId, widgetId)) as Promise<DashboardWidget>;
 }
 
-export async function renameDashboard(
-  id: string,
-  data: { name: string },
-): Promise<DashboardDetail> {
+export async function updateWidgetOnDashboard({
+  dashboardId,
+  widgetId,
+  ...changes
+}: {
+  dashboardId: string;
+  widgetId: string;
+  name?: string;
+  code?: string;
+  queries?: DashboardWidgetQueryInput[];
+  description?: string;
+}): Promise<DashboardWidget> {
   return makeRequest(
     "PATCH",
-    `/api/v1/dashboards/${encodeURIComponent(id)}`,
-    data,
-  ) as Promise<DashboardDetail>;
+    widgetPath(dashboardId, widgetId),
+    changes,
+  ) as Promise<DashboardWidget>;
 }
 
-export async function deleteDashboard(id: string): Promise<{ id: string; name: string }> {
-  return makeRequest("DELETE", `/api/v1/dashboards/${encodeURIComponent(id)}`) as Promise<{
-    id: string;
-    name: string;
-  }>;
+export async function deleteWidgetOnDashboard({
+  dashboardId,
+  widgetId,
+}: {
+  dashboardId: string;
+  widgetId: string;
+}): Promise<void> {
+  await makeRequest("DELETE", widgetPath(dashboardId, widgetId));
 }

package/src/langwatch-api-projects.ts

@@ -45,23 +45,6 @@ export async function getProject(id: string): Promise<ProjectSummary> {
   ) as Promise<ProjectSummary>;
 }
 
-/** Identity of the project the calling API key belongs to. */
-export interface CurrentProjectIdentity {
-  id: string;
-  name: string;
-  slug: string;
-  isPersonal: boolean;
-}
-
-/**
- * Resolves the project behind the configured API key. Needed for the
- * `/api/v1/projects/:projectId/...` route family, whose path must name the
- * caller's own project — there is no "current project" shorthand there.
- */
-export async function getCurrentProject(): Promise<CurrentProjectIdentity> {
-  return makeRequest("GET", "/api/v1/me/project") as Promise<CurrentProjectIdentity>;
-}
-
 export async function createProject(data: {
   name: string;
   language: string;

package/src/langwatch-api.ts

@@ -13,6 +13,12 @@ export const MCP_IDENTITY_HEADERS: Record<string, string> = {
   "X-LangWatch-SDK-Version": packageJson.version,
 };
 
+/** The dated API version every request names (specs/api-reference/client-api-version.feature). */
+export const LANGWATCH_API_VERSION = "2026-10-26";
+
+/** Names the hosted MCP server's calls apart from a local server's. */
+export const HOSTED_MCP_HEADER = "X-LangWatch-MCP-Host";
+
 // --- Response types ---
 
 export interface TraceSearchResult {
@@ -275,11 +281,15 @@ export async function makeRequest(
   const url = config.endpoint + path;
   const headers: Record<string, string> = {
     ...MCP_IDENTITY_HEADERS,
+    "X-API-Version": LANGWATCH_API_VERSION,
     "X-Auth-Token": requireApiKey(),
   };
   if (config.projectId) {
     headers["X-Project-Id"] = config.projectId;
   }
+  if (config.hosted) {
+    headers[HOSTED_MCP_HEADER] = "hosted";
+  }
 
   if (body !== undefined) {
     headers["Content-Type"] = "application/json";

package/src/schemas/widget-sources.ts

@@ -0,0 +1,33 @@
+/**
+ * The `sources` input of the widget tools: the trace origins a widget's queries count, checked
+ * here so an unknown one never reaches the platform. Spec: dashboards-v2.feature AC200j, AC200n.
+ */
+import { z } from "zod";
+
+/** The sources the platform takes, "other" being every origin not listed before it. */
+export const WIDGET_SOURCES = [
+  "application",
+  "simulation",
+  "evaluation",
+  "sample",
+  "coding_agent",
+  "ai_tool",
+  "gateway",
+  "workflow",
+  "playground",
+  "langy",
+  "other",
+] as const;
+
+/** A trace origin a widget query can count. */
+export type WidgetSource = (typeof WIDGET_SOURCES)[number];
+
+/** The tools' `sources` input: refused at the tool when it names anything else. */
+export const widgetSourcesInput = z
+  .array(z.enum(WIDGET_SOURCES))
+  .max(WIDGET_SOURCES.length)
+  .nullable()
+  .optional()
+  .describe(
+    `The trace origins every query of the widget counts: any of ${WIDGET_SOURCES.join(", ")} (other = any origin not listed). A new widget counts ["application"]; add "langy" to count your own conversations, as a widget about Langy's requests needs. null makes it unset again, counting the default.`,
+  );

package/src/tools/add-dashboard-widget.ts

@@ -1,19 +1,14 @@
 /**
- * The `add_dashboard_widget` MCP tool: create, then place, as the platform's own write path
- * does. The dashboard is checked first so a typo leaves no unplaced widget behind, and a
- * failed placement deletes the widget it just created.
+ * `add_dashboard_widget`: one create under the dashboard's path, which also places the widget.
  */
 
-import {
-  assignDashboardWidgetToDashboard,
-  createDashboardWidget,
-  deleteDashboardWidget,
-} from "../langwatch-api-dashboard-widgets.js";
-import { getCurrentProject } from "../langwatch-api-projects.js";
-import { assertDashboardExists } from "./dashboard-exists.js";
+import { createWidgetOnDashboard } from "../langwatch-api-dashboards.js";
+import { LangWatchApiError } from "../langwatch-api.js";
+import type { WidgetSource } from "../schemas/widget-sources.js";
 import {
   type DashboardWidgetQueriesInput,
   normalizeDashboardWidgetQueries,
+  withSources,
 } from "./dashboard-widget-queries.js";
 
 export interface AddDashboardWidgetParams {
@@ -21,37 +16,30 @@ export interface AddDashboardWidgetParams {
   name: string;
   code: string;
   queries: DashboardWidgetQueriesInput;
+  /** Set on every query; absent, the platform stores application on each. */
+  sources?: WidgetSource[] | null;
 }
 
 export async function handleAddDashboardWidget(params: AddDashboardWidgetParams): Promise<string> {
-  const queries = normalizeDashboardWidgetQueries({ queries: params.queries });
-
-  const project = await getCurrentProject();
-  await assertDashboardExists({ projectId: project.id, dashboardId: params.dashboardId });
-
-  const widget = await createDashboardWidget({
-    projectId: project.id,
-    name: params.name,
-    code: params.code,
-    queries,
+  const queries = withSources({
+    queries: normalizeDashboardWidgetQueries({ queries: params.queries }),
+    sources: params.sources,
   });
 
+  let widget;
   try {
-    await assignDashboardWidgetToDashboard({
-      projectId: project.id,
-      widgetId: widget.id,
+    widget = await createWidgetOnDashboard({
       dashboardId: params.dashboardId,
+      name: params.name,
+      code: params.code,
+      queries,
     });
   } catch (error) {
-    // The widget now exists but is not on the dashboard we promised — never
-    // leave it dangling because the dashboard vanished between the check
-    // above and this call.
-    await deleteDashboardWidget({
-      projectId: project.id,
-      widgetId: widget.id,
-    }).catch(() => {
-      // Best-effort cleanup; the assign error below is what the caller needs.
-    });
+    if (error instanceof LangWatchApiError && error.status === 404) {
+      throw new Error(
+        `No dashboard with ID "${params.dashboardId}" was found in this project. Use list_dashboards to find a valid dashboard ID.`,
+      );
+    }
     throw error;
   }
 

package/src/tools/create-analytics-report.ts

@@ -0,0 +1,7 @@
+import { createAnalyticsReport } from "../langwatch-api-analytics-reports.ts";
+
+export async function handleCreateAnalyticsReport(params: { name: string }): Promise<string> {
+  const report = await createAnalyticsReport({ name: params.name });
+
+  return `Analytics Report created successfully!\n\n**Name**: ${report.name}\n**ID**: ${report.id}`;
+}

package/src/tools/dashboard-widget-queries.ts

@@ -1,4 +1,17 @@
 import type { DashboardWidgetQueryInput } from "../langwatch-api-dashboard-widgets.js";
+import type { WidgetSource } from "../schemas/widget-sources.js";
+
+/** Every query with `sources` set to the list given; as given when no list was named. */
+export function withSources({
+  queries,
+  sources,
+}: {
+  queries: readonly DashboardWidgetQueryInput[];
+  sources: WidgetSource[] | null | undefined;
+}): DashboardWidgetQueryInput[] {
+  if (sources === undefined) return [...queries];
+  return queries.map((query) => ({ ...query, sources }));
+}
 
 /** A widget file rarely needs more than a couple of named queries (server bound). */
 export const MAX_DASHBOARD_WIDGET_QUERIES = 8;

package/src/tools/dashboards.ts

@@ -0,0 +1,104 @@
+/**
+ * The dashboard tools over `/api/v1/dashboards`: read, create, rename and delete a dashboard,
+ * list a dashboard's widgets and delete one. Spec: modules/dashboard/specs/dashboards-v2.feature
+ * AC199s.
+ */
+
+import {
+  type Dashboard,
+  createDashboard,
+  deleteDashboard,
+  deleteWidgetOnDashboard,
+  getDashboard,
+  listWidgetsOnDashboard,
+  updateDashboard,
+} from "../langwatch-api-dashboards.js";
+
+function describeDashboard(dashboard: Dashboard): string[] {
+  return [
+    `**Name**: ${dashboard.name}`,
+    `**ID**: ${dashboard.id}`,
+    `**Scope**: ${dashboard.scope}`,
+    ...(dashboard.description ? [`**Description**: ${dashboard.description}`] : []),
+    `**URL**: ${dashboard.platformUrl}`,
+  ];
+}
+
+/** Reads only `/api/v1/dashboards`; an Analytics Report's id is not found there. */
+export async function handleGetDashboard({
+  dashboardId,
+}: {
+  dashboardId: string;
+}): Promise<string> {
+  const dashboard = await getDashboard({ dashboardId });
+  return [`# ${dashboard.name}\n`, ...describeDashboard(dashboard)].join("\n");
+}
+
+export async function handleCreateDashboard({ name }: { name: string }): Promise<string> {
+  const dashboard = await createDashboard({ name });
+  return [
+    "Dashboard created.\n",
+    ...describeDashboard(dashboard),
+    "",
+    "> Pass the ID to `add_dashboard_widget` to add a widget to it.",
+  ].join("\n");
+}
+
+export async function handleRenameDashboard({
+  dashboardId,
+  name,
+  description,
+}: {
+  dashboardId: string;
+  name?: string;
+  description?: string;
+}): Promise<string> {
+  if (name === undefined && description === undefined) {
+    throw new Error("Provide at least one of name or description to change.");
+  }
+  const dashboard = await updateDashboard({
+    dashboardId,
+    ...(name === undefined ? {} : { name }),
+    ...(description === undefined ? {} : { description }),
+  });
+  return ["Dashboard updated.\n", ...describeDashboard(dashboard)].join("\n");
+}
+
+export async function handleDeleteDashboard({
+  dashboardId,
+}: {
+  dashboardId: string;
+}): Promise<string> {
+  const deleted = await deleteDashboard({ dashboardId });
+  return `Dashboard "${deleted.name}" deleted with its widgets (ID: ${deleted.id}).`;
+}
+
+export async function handleListDashboardWidgets({
+  dashboardId,
+}: {
+  dashboardId: string;
+}): Promise<string> {
+  const { data: widgets } = await listWidgetsOnDashboard({ dashboardId });
+  if (widgets.length === 0) return `Dashboard "${dashboardId}" has no widgets.`;
+
+  return [
+    `# Widgets on dashboard ${dashboardId} (${widgets.length} total)\n`,
+    ...widgets.flatMap((widget) => [
+      `## ${widget.name}`,
+      `**ID**: ${widget.id}`,
+      `**Queries**: ${widget.definition.queries.map((query) => query.name).join(", ") || "(none)"}`,
+      "",
+    ]),
+  ].join("\n");
+}
+
+export async function handleDeleteDashboardWidget({
+  dashboardId,
+  widgetId,
+}: {
+  dashboardId: string;
+  widgetId: string;
+}): Promise<string> {
+  await deleteWidgetOnDashboard({ dashboardId, widgetId });
+  return `Widget "${widgetId}" deleted from dashboard "${dashboardId}".`;
+}

package/src/tools/delete-analytics-report.ts

@@ -0,0 +1,7 @@
+import { deleteAnalyticsReport } from "../langwatch-api-analytics-reports.ts";
+
+export async function handleDeleteAnalyticsReport(params: { reportId: string }): Promise<string> {
+  const result = await deleteAnalyticsReport({ reportId: params.reportId });
+
+  return `Analytics Report deleted successfully!\n\n**Name**: ${result.name}\n**ID**: ${result.id}`;
+}

package/src/tools/get-analytics-report.ts

@@ -0,0 +1,23 @@
+import { getAnalyticsReport } from "../langwatch-api-analytics-reports.ts";
+
+/** Reads only `/api/v1/analytics/reports`; a Dashboards dashboard's id is not found there. */
+export async function handleGetAnalyticsReport(params: { reportId: string }): Promise<string> {
+  const report = await getAnalyticsReport({ reportId: params.reportId });
+
+  const lines: string[] = [];
+  lines.push(`# ${report.name}\n`);
+  lines.push(`**ID**: ${report.id}`);
+  lines.push(`**Order**: ${report.order}`);
+  lines.push(`**Graphs**: ${Array.isArray(report.graphs) ? report.graphs.length : 0}`);
+  lines.push(`**Created**: ${report.createdAt}`);
+  lines.push(`**Updated**: ${report.updatedAt}`);
+
+  if (Array.isArray(report.graphs) && report.graphs.length > 0) {
+    lines.push("\n## Graphs\n");
+    lines.push("```json");
+    lines.push(JSON.stringify(report.graphs, null, 2));
+    lines.push("```");
+  }
+
+  return lines.join("\n");
+}

package/src/tools/list-analytics-reports.ts

@@ -0,0 +1,27 @@
+import { listAnalyticsReports } from "../langwatch-api-analytics-reports.ts";
+
+export async function handleListAnalyticsReports(): Promise<string> {
+  const result = await listAnalyticsReports();
+  const reports = result.data;
+
+  if (!Array.isArray(reports) || reports.length === 0) {
+    return "No Analytics Reports found in this project.\n\n> Tip: Use `platform_create_analytics_report` to create a new Analytics Report.";
+  }
+
+  const lines: string[] = [];
+  lines.push(`# Analytics Reports (${reports.length} total)\n`);
+
+  for (const report of reports) {
+    lines.push(`## ${report.name}`);
+    lines.push(`**ID**: ${report.id}`);
+    lines.push(`**Graphs**: ${report.graphCount}`);
+    lines.push(`**Updated**: ${report.updatedAt}`);
+    lines.push("");
+  }
+
+  lines.push(
+    "> Use `platform_get_analytics_report` with the ID to see the Analytics Report's details including graphs.",
+  );
+
+  return lines.join("\n");
+}

package/src/tools/list-dashboards.ts

@@ -1,27 +1,26 @@
-import { listDashboards as apiListDashboards } from "../langwatch-api-dashboards.ts";
+/**
+ * The `list_dashboards` MCP tool: the dashboards a widget can be added to, with
+ * the id `add_dashboard_widget` and `update_dashboard_widget` take.
+ */
 
-export async function handleListDashboards(): Promise<string> {
-  const result = await apiListDashboards();
-  const dashboards = result.data;
-
-  if (!Array.isArray(dashboards) || dashboards.length === 0) {
-    return "No dashboards found in this project.\n\n> Tip: Use `platform_create_dashboard` to create a new dashboard.";
-  }
+import { listDashboards } from "../langwatch-api-dashboards.js";
 
-  const lines: string[] = [];
-  lines.push(`# Dashboards (${dashboards.length} total)\n`);
+export async function handleListDashboards(): Promise<string> {
+  const { data: dashboards } = await listDashboards();
 
-  for (const d of dashboards) {
-    lines.push(`## ${d.name}`);
-    lines.push(`**ID**: ${d.id}`);
-    lines.push(`**Graphs**: ${d.graphCount}`);
-    lines.push(`**Updated**: ${d.updatedAt}`);
-    lines.push("");
+  if (dashboards.length === 0) {
+    return "No dashboards found in this project. Create one in the Dashboards area first.";
   }
 
-  lines.push(
-    "> Use `platform_get_dashboard` with the ID to see dashboard details including graphs.",
-  );
-
-  return lines.join("\n");
+  return [
+    `# Dashboards (${dashboards.length} total)\n`,
+    ...dashboards.flatMap((dashboard) => [
+      `## ${dashboard.name}`,
+      `**ID**: ${dashboard.id}`,
+      `**Widgets**: ${dashboard.widgetCount}`,
+      `**URL**: ${dashboard.platformUrl}`,
+      "",
+    ]),
+    "> Pass the ID to `add_dashboard_widget` to add a widget to that dashboard.",
+  ].join("\n");
 }

package/src/tools/report-issue.ts

@@ -7,6 +7,7 @@ import {
 } from "@langwatch/redaction";
 
 import { getConfig } from "../config.ts";
+import { LANGWATCH_API_VERSION } from "../langwatch-api.ts";
 
 /** Transcripts are capped after redaction; oldest lines are dropped first. */
 const MAX_SESSION_BYTES = 8 * 1024 * 1024;
@@ -77,6 +78,7 @@ async function deliverReport(report: RedactedReport, params: ReportIssueParams):
     method: "POST",
     headers: {
       "content-type": "application/json",
+      "x-api-version": LANGWATCH_API_VERSION,
       ...(config.apiKey ? { authorization: `Bearer ${config.apiKey}` } : {}),
     },
     body: JSON.stringify({

package/src/tools/run-experiment.ts

@@ -24,10 +24,14 @@ interface EvaluationStatusResponse {
   };
 }
 
-export async function handleRunExperiment(params: { slug: string }): Promise<string> {
+export async function handleRunExperiment(params: {
+  slug: string;
+  concurrency?: number;
+}): Promise<string> {
   const result = (await makeRequest(
     "POST",
     `/api/v1/experiments/${encodeURIComponent(params.slug)}/run`,
+    params.concurrency !== undefined ? { concurrency: params.concurrency } : undefined,
   )) as EvaluationRunResponse;
 
   const lines: string[] = [];