docs(cli): Expand and improve the MCP server and dev CLI command

Depends on #3224

Author: ericallam

docs/docs.json

@@ -323,7 +323,7 @@
           },
           {
             "group": "Query API",
-            "pages": ["management/query/execute"]
+            "pages": ["management/query/execute", "management/query/schema", "management/query/dashboards"]
           }
         ]
       },

docs/management/query/dashboards.mdx

@@ -0,0 +1,4 @@
+---
+title: "List dashboards"
+openapi: "v3-openapi GET /api/v1/query/dashboards"
+---

docs/management/query/schema.mdx

@@ -0,0 +1,4 @@
+---
+title: "Get query schema"
+openapi: "v3-openapi GET /api/v1/query/schema"
+---

docs/mcp-introduction.mdx

@@ -14,6 +14,7 @@ The Trigger.dev MCP (Model Context Protocol) Server enables AI assistants to int
 - Get task information and trigger task runs
 - Deploy projects to different environments
 - Monitor run details and list runs with filtering options
+- Query your data with TRQL and run built-in dashboard metrics
 
 ## Installation
 
@@ -306,6 +307,7 @@ The `install-mcp` command supports these options:
 - `-p, --project-ref <project ref>` — Scope the MCP server to a specific project
 - `-t, --tag <package tag>` — CLI package version to use (default: latest)
 - `--dev-only` — Restrict to the dev environment only
+- `--readonly` — Read-only mode. Hides write tools (`deploy`, `trigger_task`, `cancel_run`) so the AI cannot make changes to your account
 - `--yolo` — Install into all supported clients automatically
 - `--scope <scope>` — `user`, `project`, or `local`
 - `--client <clients...>` — Install into specific client(s)
@@ -336,6 +338,12 @@ Restrict to dev environment for a specific project:
 npx trigger.dev@latest install-mcp --dev-only --project-ref proj_abc123
 ```
 
+Read-only mode (prevents AI from deploying or triggering tasks):
+
+```bash
+npx trigger.dev@latest install-mcp --readonly
+```
+
 To add these options to a manual config, append them to the `args` array:
 
 ```json
@@ -358,6 +366,9 @@ Once installed, you can start using the MCP server by asking your AI assistant q
 - `"List all runs for my foobar task"`
 - `"Deploy my project to staging"`
 - `"Deploy my project to production"`
+- `"How many runs failed in the last 7 days?"`
+- `"Show me the overview dashboard metrics"`
+- `"What tables can I query?"`
 
 ## Next Steps
 

docs/mcp-tools.mdx

@@ -128,6 +128,93 @@ List all preview branches in the project.
 - `"What preview branches exist?"`
 - `"Show me preview deployments"`
 
+## Profile Tools
+
+### whoami
+
+Show the current authenticated user, active CLI profile, email, and API URL.
+
+**Example usage:**
+- `"Who am I logged in as?"`
+- `"What profile am I using?"`
+
+### list_profiles
+
+List all configured CLI profiles and which one is currently active.
+
+**Example usage:**
+- `"What profiles do I have?"`
+- `"Show me my Trigger.dev profiles"`
+
+### switch_profile
+
+Switch the active CLI profile for this MCP session. This changes which Trigger.dev account and API URL are used for all subsequent tool calls.
+
+**Example usage:**
+- `"Switch to my production profile"`
+- `"Use the staging profile"`
+
+## Query and Analytics Tools
+
+### get_query_schema
+
+Get the schema for TRQL queries, including all available tables, their columns, data types, descriptions, and allowed values. Call this before using the query tool to understand what data is available.
+
+**Example usage:**
+- `"What tables and columns can I query?"`
+- `"Show me the query schema"`
+
+### query
+
+Execute a TRQL query against your Trigger.dev data. TRQL is a SQL-style query language for analyzing runs, metrics, and LLM usage.
+
+**Example usage:**
+- `"How many runs failed in the last 7 days?"`
+- `"Show me the top 10 most expensive tasks"`
+- `"Query the average execution duration by task"`
+
+### list_dashboards
+
+List available built-in dashboards with their widgets. Each dashboard contains pre-built queries for common metrics.
+
+**Example usage:**
+- `"What dashboards are available?"`
+- `"Show me the dashboard widgets"`
+
+### run_dashboard_query
+
+Execute a single widget query from a built-in dashboard. Use `list_dashboards` first to see available dashboards and widget IDs.
+
+**Example usage:**
+- `"Run the total runs widget from the overview dashboard"`
+- `"Show me the LLM cost over time from the AI dashboard"`
+
+## Dev Server Tools
+
+### start_dev_server
+
+Start the Trigger.dev dev server (`trigger dev`) in the background. Waits up to 30 seconds for the worker to be ready.
+
+**Example usage:**
+- `"Start the dev server"`
+- `"Run trigger dev"`
+
+### stop_dev_server
+
+Stop the running Trigger.dev dev server.
+
+**Example usage:**
+- `"Stop the dev server"`
+
+### dev_server_status
+
+Check the status of the dev server and view recent output. Shows whether it is stopped, starting, ready, or has errors.
+
+**Example usage:**
+- `"Is the dev server running?"`
+- `"Show me the dev server logs"`
+- `"Are there any build errors?"`
+
 <Callout type="warning">
-  The deploy and list_preview_branches tools are not available when the MCP server is running with the `--dev-only` flag.
+  The deploy and list_preview_branches tools are not available when the MCP server is running with the `--dev-only` flag. The `--readonly` flag hides deploy, trigger_task, and cancel_run.
 </Callout>

docs/observability/query.mdx

@@ -7,14 +7,15 @@ description: "Query allows you to write custom queries against your data using T
 
 - `runs`: contains all task run data including status, timing, costs, and task output. Run metadata (key-value set in your task) is not available on the Query page.
 - `metrics`: contains metrics data for your runs including CPU, memory, and your custom metrics
+- `llm_metrics`: contains LLM/AI metrics including token usage, costs, latency, and model performance data from GenAI spans
 
 ### `metrics` table columns
 
 | Column | Type | Description |
 | :--- | :--- | :--- |
 | `metric_name` | string | Metric identifier (e.g., `process.cpu.utilization`) |
 | `metric_type` | string | `gauge`, `sum`, or `histogram` |
-| `value` | number | The observed value |
+| `metric_value` | number | The observed value |
 | `bucket_start` | datetime | 10-second aggregation bucket start time |
 | `run_id` | string | Associated run ID |
 | `task_identifier` | string | Task slug |
@@ -34,7 +35,7 @@ Use `prettyFormat()` to format metric values for display:
 ```sql
 SELECT
   timeBucket(),
-  prettyFormat(avg(value), 'bytes') AS avg_memory
+  prettyFormat(avg(metric_value), 'bytes') AS avg_memory_usage
 FROM metrics
 WHERE metric_name = 'process.memory.usage'
 GROUP BY timeBucket
@@ -225,7 +226,7 @@ Use `GROUP BY` with aggregate functions:
 ```sql
 SELECT
   task_identifier,
-  avg(value) AS avg_memory
+  avg(metric_value) AS avg_memory
 FROM metrics
 WHERE metric_name = 'process.memory.usage'
 GROUP BY task_identifier
@@ -529,7 +530,7 @@ Track process CPU utilization bucketed over time.
 ```sql
 SELECT
   timeBucket(),
-  avg(value) AS avg_cpu
+  avg(metric_value) AS avg_cpu
 FROM metrics
 WHERE metric_name = 'process.cpu.utilization'
 GROUP BY timeBucket
@@ -544,7 +545,7 @@ Average process memory usage per task identifier over the last 7 days.
 ```sql
 SELECT
   task_identifier,
-  avg(value) AS avg_memory
+  avg(metric_value) AS avg_memory
 FROM metrics
 WHERE metric_name = 'process.memory.usage'
 GROUP BY task_identifier

docs/v3-openapi.yaml

@@ -1148,6 +1148,126 @@ paths:
                 "format": "json"
               }'
 
+  "/api/v1/query/schema":
+    get:
+      operationId: get_query_schema_v1
+      summary: Get query schema
+      description: Get the schema for TRQL queries, including all available tables, their columns, data types, descriptions, and allowed values.
+      responses:
+        "200":
+          description: Schema retrieved successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  tables:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        name:
+                          type: string
+                          description: Table name used in TRQL queries
+                        description:
+                          type: string
+                          description: Description of the table
+                        timeColumn:
+                          type: string
+                          description: The primary time column for this table
+                        columns:
+                          type: array
+                          items:
+                            type: object
+                            properties:
+                              name:
+                                type: string
+                                description: Column name
+                              type:
+                                type: string
+                                description: ClickHouse data type
+                              description:
+                                type: string
+                                description: Column description
+                              example:
+                                type: string
+                                description: Example value
+                              allowedValues:
+                                type: array
+                                items:
+                                  type: string
+                                description: Allowed values for enum-like columns
+                              coreColumn:
+                                type: boolean
+                                description: Whether this is a core column included in default queries
+        "401":
+          description: Unauthorized - API key is missing or invalid
+      tags:
+        - query
+      security:
+        - secretKey: []
+      x-codeSamples:
+        - lang: curl
+          label: cURL
+          source: |-
+            curl "https://api.trigger.dev/api/v1/query/schema" \
+              -H "Authorization: Bearer tr_dev_1234"
+
+  "/api/v1/query/dashboards":
+    get:
+      operationId: list_dashboards_v1
+      summary: List built-in dashboards
+      description: List available built-in dashboards with their widgets. Each dashboard contains pre-built TRQL queries for common metrics like run success rates, costs, and LLM usage.
+      responses:
+        "200":
+          description: Dashboards listed successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  dashboards:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        key:
+                          type: string
+                          description: Dashboard identifier (e.g. "overview", "llm")
+                        title:
+                          type: string
+                          description: Dashboard display title
+                        widgets:
+                          type: array
+                          items:
+                            type: object
+                            properties:
+                              id:
+                                type: string
+                                description: Widget identifier
+                              title:
+                                type: string
+                                description: Widget display title
+                              query:
+                                type: string
+                                description: The TRQL query this widget executes
+                              type:
+                                type: string
+                                enum: [bignumber, chart, table]
+                                description: Widget display type
+        "401":
+          description: Unauthorized - API key is missing or invalid
+      tags:
+        - query
+      security:
+        - secretKey: []
+      x-codeSamples:
+        - lang: curl
+          label: cURL
+          source: |-
+            curl "https://api.trigger.dev/api/v1/query/dashboards" \
+              -H "Authorization: Bearer tr_dev_1234"
+
   "/api/v1/runs/{runId}/reschedule":
     parameters:
       - $ref: "#/components/parameters/runId"