feat(cli): Expand and improve the MCP server and dev CLI command (#3224)

## Summary

Major expansion of the MCP server (14 → 25 tools), context efficiency
optimizations, new API endpoints, and a fix for the dev CLI leaking
build directories on disk.

### New MCP tools

- **Query & analytics**: `get_query_schema`, `query`, `list_dashboards`,
`run_dashboard_query` — query your data using TRQL directly from AI
assistants
- **Profile management**: `whoami`, `list_profiles`, `switch_profile` —
see and switch CLI profiles per-project (persisted to
`.trigger/mcp.json`)
- **Dev server control**: `start_dev_server`, `stop_dev_server`,
`dev_server_status` — start/stop `trigger dev` and stream build output
- **Task introspection**: `get_task_schema` — get payload schema for a
specific task (split out from `get_current_worker` to reduce context)

### New API endpoints

- `GET /api/v1/query/schema` — discover TRQL tables and columns
(server-driven, multi-table)
- `GET /api/v1/query/dashboards` — list built-in dashboard widgets and
their queries

### New features

- **`--readonly` flag** — hides write tools (`deploy`, `trigger_task`,
`cancel_run`) so agents can't make changes
- **`read:query` JWT scope** — new authorization scope for query
endpoints, with per-table granularity (`read:query:runs`,
`read:query:llm_metrics`, etc.)
- **Paginated trace output** — `get_run_details` now paginates trace
events via cursor, caching the full trace in a temp file so subsequent
pages don't re-fetch
- **MCP tool annotations** — all tools now have
`readOnlyHint`/`destructiveHint` annotations for clients that support
them
- **Project-scoped profile persistence** — `switch_profile` saves to
`.trigger/mcp.json` (gitignored), automatically loaded on next MCP
server start

### Context optimizations

- `get_query_schema` requires a table name — returns one table's schema
instead of all tables (60-80% fewer tokens)
- `get_current_worker` no longer inlines payload schemas — use
`get_task_schema` for specific tasks
- Query results formatted as text tables instead of JSON (~50% fewer
tokens for flat data)
- `cancel_run`, `list_deploys`, `list_preview_branches` formatted as
text instead of raw `JSON.stringify()`
- Schema and dashboard API responses cached (1hr and 5min respectively)

### Bug fixes

- Fixed `search_docs` failing due to renamed upstream Mintlify tool
(`SearchTriggerDev` → `search_trigger_dev`)
- Fixed `list_deploys` failing when deployments have null
`runtime`/`runtimeVersion` fields (fixes #3139)
- Fixed `list_preview_branches` crashing due to incorrect response shape
access
- Fixed `metrics` table column documented as `value` instead of
`metric_value` in query docs
- Fixed `/api/v1/query` not accepting JWT auth (added `allowJWT: true`)

### Dev CLI build directory fix

The dev CLI was leaking `build-*` directories in `.trigger/tmp/` on
every rebuild, accumulating hundreds of MB over time (842MB observed).
Three layers of protection added:

1. **During session**: deprecated workers are pruned (capped at 2
retained) when no active runs reference them, preventing unbounded
accumulation
2. **On SIGKILL/crash**: the watchdog process now cleans up
`.trigger/tmp/` when it detects the parent CLI was killed
3. **On next startup**: existing `clearTmpDirs()` wipes any remaining
orphans

## Test plan

- [ ] `pnpm run mcp:smoke` — 17 automated smoke tests for all read-only
MCP tools
- [ ] `pnpm run mcp:test list` — verify 25 tools registered (21 in
`--readonly` mode)
- [ ] `pnpm run mcp:test --readonly list` — verify write tools hidden
- [ ] Manual: start dev server, trigger task, rebuild multiple times,
verify build dirs stay capped at 4
- [ ] Manual: SIGKILL the dev CLI, verify watchdog cleans up
`.trigger/tmp/`
- [ ] Verify new API endpoints return correct data: `GET
/api/v1/query/schema`, `GET /api/v1/query/dashboards`

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: ericallam

.changeset/fix-dev-build-dir-leak.md

@@ -0,0 +1,5 @@
+---
+"trigger.dev": patch
+---
+
+Fix dev CLI leaking build directories on rebuild, causing disk space accumulation. Deprecated workers are now pruned (capped at 2 retained) when no active runs reference them. The watchdog process also cleans up `.trigger/tmp/` when the dev CLI is killed ungracefully (e.g. SIGKILL from pnpm).

.changeset/fix-list-deploys-nullable.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/core": patch
+---
+
+Fix `list_deploys` MCP tool failing when deployments have null `runtime` or `runtimeVersion` fields.

.changeset/mcp-query-tools.md

@@ -0,0 +1,42 @@
+---
+"@trigger.dev/core": patch
+"trigger.dev": patch
+---
+
+MCP server improvements: new tools, bug fixes, and new flags.
+
+**New tools:**
+- `get_query_schema` — discover available TRQL tables and columns
+- `query` — execute TRQL queries against your data
+- `list_dashboards` — list built-in dashboards and their widgets
+- `run_dashboard_query` — execute a single dashboard widget query
+- `whoami` — show current profile, user, and API URL
+- `list_profiles` — list all configured CLI profiles
+- `switch_profile` — switch active profile for the MCP session
+- `start_dev_server` — start `trigger dev` in the background and stream output
+- `stop_dev_server` — stop the running dev server
+- `dev_server_status` — check dev server status and view recent logs
+
+**New API endpoints:**
+- `GET /api/v1/query/schema` — query table schema discovery
+- `GET /api/v1/query/dashboards` — list built-in dashboards
+
+**New features:**
+- `--readonly` flag hides write tools (`deploy`, `trigger_task`, `cancel_run`) so the AI cannot make changes
+- `read:query` JWT scope for query endpoint authorization
+- `get_run_details` trace output is now paginated with cursor support
+- MCP tool annotations (`readOnlyHint`, `destructiveHint`) for all tools
+
+**Bug fixes:**
+- Fixed `search_docs` tool failing due to renamed upstream Mintlify tool (`SearchTriggerDev` → `search_trigger_dev`)
+- Fixed `list_deploys` failing when deployments have null `runtime`/`runtimeVersion` fields (#3139)
+- Fixed `list_preview_branches` crashing due to incorrect response shape access
+- Fixed `metrics` table column documented as `value` instead of `metric_value` in query docs
+- Fixed dev CLI leaking build directories on rebuild — deprecated workers now clean up their build dirs when their last run completes
+
+**Context optimizations:**
+- `get_query_schema` now requires a table name and returns only one table's schema (was returning all tables)
+- `get_current_worker` no longer inlines payload schemas; use new `get_task_schema` tool instead
+- Query results formatted as text tables instead of JSON (~50% fewer tokens)
+- `cancel_run`, `list_deploys`, `list_preview_branches` formatted as text instead of raw JSON
+- Schema and dashboard API responses cached to avoid redundant fetches

apps/webapp/app/routes/api.v1.query.dashboards._index.ts

@@ -0,0 +1,54 @@
+import { json } from "@remix-run/server-runtime";
+import type { DashboardSummary, DashboardWidgetSummary } from "@trigger.dev/core/v3/schemas";
+import type { BuiltInDashboard } from "~/presenters/v3/MetricDashboardPresenter.server";
+import { createLoaderApiRoute } from "~/services/routeBuilders/apiBuilder.server";
+import { builtInDashboard } from "~/presenters/v3/BuiltInDashboards.server";
+
+const BUILT_IN_DASHBOARD_KEYS = ["overview", "llm"];
+
+function serializeDashboard(dashboard: BuiltInDashboard): DashboardSummary {
+  const widgets: DashboardWidgetSummary[] = [];
+
+  if (dashboard.layout.version === "1") {
+    for (const [id, widget] of Object.entries(dashboard.layout.widgets)) {
+      // Skip title widgets — they're just section headers
+      if (widget.display.type === "title") continue;
+
+      widgets.push({
+        id,
+        title: widget.title,
+        query: widget.query,
+        type: widget.display.type,
+      });
+    }
+  }
+
+  return {
+    key: dashboard.key,
+    title: dashboard.title,
+    widgets,
+  };
+}
+
+export const loader = createLoaderApiRoute(
+  {
+    allowJWT: true,
+    corsStrategy: "all",
+    findResource: async () => 1,
+    authorization: {
+      action: "read",
+      resource: () => ({ query: "dashboards" }),
+      superScopes: ["read:query", "read:all", "admin"],
+    },
+  },
+  async () => {
+    const dashboards = BUILT_IN_DASHBOARD_KEYS.map((key) => {
+      try {
+        return serializeDashboard(builtInDashboard(key));
+      } catch {
+        return null;
+      }
+    }).filter((d): d is DashboardSummary => d !== null);
+    return json({ dashboards });
+  }
+);

apps/webapp/app/routes/api.v1.query.schema.ts

@@ -0,0 +1,58 @@
+import { json } from "@remix-run/server-runtime";
+import type { ColumnSchema, TableSchema } from "@internal/tsql";
+import { createLoaderApiRoute } from "~/services/routeBuilders/apiBuilder.server";
+import { querySchemas } from "~/v3/querySchemas";
+
+function serializeColumn(col: ColumnSchema) {
+  const result: Record<string, unknown> = {
+    name: col.name,
+    type: col.type,
+  };
+
+  if (col.description) {
+    result.description = col.description;
+  }
+  if (col.example) {
+    result.example = col.example;
+  }
+  if (col.allowedValues && col.allowedValues.length > 0) {
+    if (col.valueMap) {
+      result.allowedValues = Object.values(col.valueMap);
+    } else {
+      result.allowedValues = col.allowedValues;
+    }
+  }
+  if (col.coreColumn) {
+    result.coreColumn = true;
+  }
+
+  return result;
+}
+
+function serializeTable(table: TableSchema) {
+  const columns = Object.values(table.columns).map(serializeColumn);
+
+  return {
+    name: table.name,
+    description: table.description,
+    timeColumn: table.timeConstraint,
+    columns,
+  };
+}
+
+export const loader = createLoaderApiRoute(
+  {
+    allowJWT: true,
+    corsStrategy: "all",
+    findResource: async () => 1,
+    authorization: {
+      action: "read",
+      resource: () => ({ query: "schema" }),
+      superScopes: ["read:query", "read:all", "admin"],
+    },
+  },
+  async () => {
+    const tables = querySchemas.map(serializeTable);
+    return json({ tables });
+  }
+);

apps/webapp/app/routes/api.v1.query.ts

@@ -5,6 +5,7 @@ import { createActionApiRoute } from "~/services/routeBuilders/apiBuilder.server
 import { executeQuery, type QueryScope } from "~/services/queryService.server";
 import { logger } from "~/services/logger.server";
 import { rowsToCSV } from "~/utils/dataExport";
+import { querySchemas } from "~/v3/querySchemas";
 
 const BodySchema = z.object({
   query: z.string(),
@@ -15,10 +16,30 @@ const BodySchema = z.object({
   format: z.enum(["json", "csv"]).default("json"),
 });
 
+/** Extract table names from a TRQL query for authorization */
+function detectTables(query: string): string[] {
+  return querySchemas
+    .filter((s) => {
+      const escaped = s.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      return new RegExp(`\\bFROM\\s+${escaped}\\b`, "i").test(query);
+    })
+    .map((s) => s.name);
+}
+
 const { action, loader } = createActionApiRoute(
   {
     body: BodySchema,
+    allowJWT: true,
     corsStrategy: "all",
+    findResource: async () => 1,
+    authorization: {
+      action: "read",
+      resource: (_, __, ___, body) => {
+        const tables = detectTables(body.query);
+        return { query: tables.length > 0 ? tables : "all" };
+      },
+      superScopes: ["read:query", "read:all", "admin"],
+    },
   },
   async ({ body, authentication }) => {
     const { query, scope, period, from, to, format } = body;

apps/webapp/app/services/authorization.server.ts

@@ -1,6 +1,6 @@
 export type AuthorizationAction = "read" | "write" | string; // Add more actions as needed
 
-const ResourceTypes = ["tasks", "tags", "runs", "batch", "waitpoints", "deployments", "inputStreams"] as const;
+const ResourceTypes = ["tasks", "tags", "runs", "batch", "waitpoints", "deployments", "inputStreams", "query"] as const;
 
 export type AuthorizationResources = {
   [key in (typeof ResourceTypes)[number]]?: string | string[];

apps/webapp/test/authorization.test.ts

@@ -310,6 +310,84 @@ describe("checkAuthorization", () => {
     });
   });
 
+  describe("Query resource type", () => {
+    it("should grant access with read:query super scope", () => {
+      const entity: AuthorizationEntity = {
+        type: "PUBLIC_JWT",
+        scopes: ["read:query"],
+      };
+      const result = checkAuthorization(
+        entity,
+        "read",
+        { query: "runs" },
+        ["read:query", "read:all", "admin"]
+      );
+      expect(result.authorized).toBe(true);
+    });
+
+    it("should grant access with table-specific query scope", () => {
+      const entity: AuthorizationEntity = {
+        type: "PUBLIC_JWT",
+        scopes: ["read:query:runs"],
+      };
+      const result = checkAuthorization(entity, "read", { query: "runs" });
+      expect(result.authorized).toBe(true);
+    });
+
+    it("should deny access to different table with table-specific scope", () => {
+      const entity: AuthorizationEntity = {
+        type: "PUBLIC_JWT",
+        scopes: ["read:query:runs"],
+      };
+      const result = checkAuthorization(entity, "read", { query: "llm_metrics" });
+      expect(result.authorized).toBe(false);
+    });
+
+    it("should grant access with general read:query scope to any table", () => {
+      const entity: AuthorizationEntity = {
+        type: "PUBLIC_JWT",
+        scopes: ["read:query"],
+      };
+
+      const runsResult = checkAuthorization(entity, "read", { query: "runs" });
+      expect(runsResult.authorized).toBe(true);
+
+      const metricsResult = checkAuthorization(entity, "read", { query: "metrics" });
+      expect(metricsResult.authorized).toBe(true);
+
+      const llmResult = checkAuthorization(entity, "read", { query: "llm_metrics" });
+      expect(llmResult.authorized).toBe(true);
+    });
+
+    it("should grant access to multiple tables when querying with super scope", () => {
+      const entity: AuthorizationEntity = {
+        type: "PUBLIC_JWT",
+        scopes: ["read:query"],
+      };
+      const result = checkAuthorization(
+        entity,
+        "read",
+        { query: ["runs", "llm_metrics"] },
+        ["read:query", "read:all", "admin"]
+      );
+      expect(result.authorized).toBe(true);
+    });
+
+    it("should grant access to schema with read:query scope", () => {
+      const entity: AuthorizationEntity = {
+        type: "PUBLIC_JWT",
+        scopes: ["read:query"],
+      };
+      const result = checkAuthorization(
+        entity,
+        "read",
+        { query: "schema" },
+        ["read:query", "read:all", "admin"]
+      );
+      expect(result.authorized).toBe(true);
+    });
+  });
+
   describe("Without super scope", () => {
     const entityWithoutSuperPermissions: AuthorizationEntity = {
       type: "PUBLIC_JWT",

packages/cli-v3/package.json

@@ -78,7 +78,9 @@
     "test:e2e": "vitest --run -c ./e2e/vitest.config.ts",
     "update-version": "tsx ../../scripts/updateVersion.ts",
     "install-mcp": "./install-mcp.sh",
-    "inspector": "npx @modelcontextprotocol/inspector dist/esm/index.js mcp --log-file .mcp.log --api-url http://localhost:3030"
+    "inspector": "npx @modelcontextprotocol/inspector dist/esm/index.js mcp --log-file .mcp.log --api-url http://localhost:3030",
+    "mcp:test": "tsx src/mcp/tools.test.ts",
+    "mcp:smoke": "tsx src/mcp/smoke.test.ts"
   },
   "dependencies": {
     "@clack/prompts": "0.11.0",

packages/cli-v3/src/commands/mcp.ts

@@ -20,6 +20,7 @@ const McpCommandOptions = CommonCommandOptions.extend({
   projectRef: z.string().optional(),
   logFile: z.string().optional(),
   devOnly: z.boolean().default(false),
+  readonly: z.boolean().default(false),
   rulesInstallManifestPath: z.string().optional(),
   rulesInstallBranch: z.string().optional(),
 });
@@ -36,6 +37,10 @@ export function configureMcpCommand(program: Command) {
         "--dev-only",
         "Only run the MCP server for the dev environment. Attempts to access other environments will fail."
       )
+      .option(
+        "--readonly",
+        "Run in read-only mode. Write tools (deploy, trigger_task, cancel_run) are hidden from the AI."
+      )
       .option("--log-file <log file>", "The file to log to")
       .addOption(
         new CommandOption(
@@ -97,6 +102,7 @@ export async function mcpCommand(options: McpCommandOptions) {
 
   server.server.oninitialized = async () => {
     fileLogger?.log("initialized mcp command", { options, argv: process.argv });
+    await context.loadProjectProfile();
   };
 
   // Start receiving messages on stdin and sending messages on stdout
@@ -111,6 +117,7 @@ export async function mcpCommand(options: McpCommandOptions) {
     fileLogger,
     apiUrl: options.apiUrl ?? CLOUD_API_URL,
     profile: options.profile,
+    readonly: options.readonly,
   });
 
   registerTools(context);