Trigger.dev MCP Tool Patterns
Reference for every MCP tool provided by the official Trigger.dev MCP server (v4.4.4 — 33 tools across 9 categories).
Note: This plugin provides MCP knowledge, not the MCP connection. Install the MCP server via npx trigger.dev@latest install-mcp or configure it manually in your project.
Install the MCP Server
# Interactive installer (detects installed clients)
npx trigger.dev@latest install-mcp
# Target a specific client
npx trigger.dev@latest install-mcp --client claude-code
# Install across all supported clients
npx trigger.dev@latest install-mcp --yolo
Install Flags
| Flag |
Purpose |
--client <name...> |
Install for specific client(s) — claude-code, cursor, windsurf, vscode, zed, cline, gemini-cli, amp, openai-codex, crush, opencode, ruler |
--scope <scope> |
user, project, or local config file |
--dev-only |
Restrict tools to the dev environment only (hides deploy, list_preview_branches) |
--readonly |
Hide write tools (deploy, trigger_task, cancel_run) — agent cannot make changes |
--project-ref <ref> |
Scope MCP to a single project (proj_xxx) |
--tag <tag> |
Pin CLI package version |
-a, --api-url <url> |
Self-hosted API URL |
--log-file <path> |
Write MCP server logs to file |
--log-level <level> |
debug / info / log / warn / error / none |
--yolo |
Install into every supported client |
Manual Config Example
{
"mcpServers": {
"trigger": {
"command": "npx",
"args": ["trigger.dev@latest", "mcp", "--dev-only", "--project-ref", "proj_abc123"]
}
}
}
Tool annotations: every tool carries readOnlyHint / destructiveHint metadata so MCP clients can gate write operations. --readonly enforces it server-side.
Shared Parameters
Most tools accept these optional parameters:
| Parameter |
Description |
Default |
projectRef |
Project ref (proj_xxx) |
Auto-detected from trigger.config.ts |
configPath |
Path to trigger.config.ts |
Auto |
environment |
dev, staging, prod, preview |
dev |
branch |
Branch name (required with preview) |
— |
Documentation & Search
| Tool |
Description |
search_docs |
Search Trigger.dev documentation |
Project & Organization
| Tool |
Description |
list_orgs |
List your organizations |
list_projects |
List your projects |
create_project_in_org |
Create a new project in an org |
initialize_project |
Init Trigger.dev in a directory |
Task Management
| Tool |
Description |
get_current_worker |
Worker version, SDK version, task list, machine presets (no longer inlines payload schemas in v4.4.4) |
get_task_schema |
Fetch the payload schema for a specific task (replaces the inlined schemas that used to live on get_current_worker) |
trigger_task |
Trigger a task with payload and options |
Run Monitoring
| Tool |
Description |
list_runs |
List and filter runs by status, task, tag, period |
get_run_details |
Run trace, logs, output — trace output is paginated with a cursor since v4.4.4 |
get_span_details |
Inspect a single span inside a run — attributes, events, AI enrichment (model, tokens, cost), child runs. Span IDs now appear in get_run_details output. |
wait_for_run_to_complete |
Wait for a run to finish |
cancel_run |
Cancel a running/queued run |
Deployment
| Tool |
Description |
deploy |
Deploy to staging/production/preview |
list_deploys |
List deployments with filters |
list_preview_branches |
List preview branches (not available with --dev-only) |
Profile
| Tool |
Description |
whoami |
Show current profile, user, and API URL |
list_profiles |
List all configured CLI profiles and the active one |
switch_profile |
Change the active profile for this MCP session (affects all subsequent tool calls) |
Query & Analytics
Powered by TRQL (Trigger.dev Query Language — SQL over ClickHouse). See the observability skill for TRQL syntax and examples.
| Tool |
Description |
get_query_schema |
Get columns, types, and descriptions for one TRQL table (now requires a table name — runs, metrics, or llm_metrics) |
query |
Execute a TRQL query. Results returned as text tables (~50% fewer tokens than JSON) |
list_dashboards |
List built-in dashboards and their widget IDs |
run_dashboard_query |
Execute a single widget query from a built-in dashboard |
Dev Server
| Tool |
Description |
start_dev_server |
Start trigger dev in the background (waits up to 30s for the worker to be ready) |
stop_dev_server |
Stop the running dev server |
dev_server_status |
Show status (stopped / starting / ready / error) and recent log lines (lines default 50) |
Managed Prompts
Trigger.dev Managed Prompts — versioned prompts with dashboard overrides. See the managed-prompts skill for the full workflow.
| Tool |
Description |
list_prompts |
List managed prompts — slug, current version, override status, version count |
get_prompt_versions |
List versions for one prompt — labels (current/override/latest), source (code/dashboard), model, content |
promote_prompt_version |
Promote a code-sourced version to current (dashboard overrides use override tools) |
create_prompt_override |
Create a dashboard override (takes precedence over the current code version) |
update_prompt_override |
Update the active dashboard override |
remove_prompt_override |
Remove the override — revert to the current code version |
reactivate_prompt_override |
Reactivate a prior dashboard-sourced version as the active override |
Common Patterns
Trigger and Monitor
1. get_current_worker(environment="dev") → task list
2. get_task_schema(taskIdentifier="process-order") → payload schema
3. trigger_task(taskId, payload) → run ID
4. wait_for_run_to_complete(runId) → result
Debug a Failed Run with AI Enrichment
1. list_runs(status="FAILED", period="1d")
2. get_run_details(runId) → error trace + span IDs
3. get_span_details(runId, spanId) → llm model, tokens, cost per AI call
4. search_docs(query="<error topic>")
Deploy Flow
1. deploy(environment="staging")
2. trigger_task(environment="staging") → verify
3. deploy(environment="prod")
4. list_deploys(environment="prod", limit=1) → confirm
Initialize Project
1. list_orgs() → pick org
2. initialize_project(orgParam, projectName, cwd)
3. get_current_worker(environment="dev") → verify
Dev Server Lifecycle (agent-controlled)
1. start_dev_server(configPath?) → launches `trigger dev` in background
2. dev_server_status(lines=50) → poll until status="ready"
3. trigger_task(...) → test against the dev worker
4. stop_dev_server() → tear down when done
Query Analytics (TRQL)
1. get_query_schema(table="runs") → column list
2. query({
query: "SELECT status, count() FROM runs GROUP BY status",
period: "7d"
}) → text table
Dashboard Metrics
1. list_dashboards() → { dashboardId, widgets: [{ widgetId, title }] }
2. run_dashboard_query(dashboardId, widgetId, period="30d") → widget data
Switch Profile Mid-Session
1. whoami() → current profile + API URL
2. list_profiles() → available profiles
3. switch_profile("self-hosted-prod") → all subsequent tool calls use the new profile
Prompt Override Hotfix
1. list_prompts(environment="prod") → find slug
2. get_prompt_versions(slug="customer-reply") → see current/override state
3. create_prompt_override(slug, textContent="...revised copy...", commitMessage="Fix tone issue")
4. (iterate) update_prompt_override(slug, textContent="...")
5. remove_prompt_override(slug) → revert to code version when code is redeployed
Best Practices
- Prefer
get_task_schema before trigger_task — get_current_worker no longer ships schemas inline.
- Use
limit and period to avoid fetching too many runs.
- Use
idempotencyKey in trigger options to prevent duplicate runs.
- Default to the dev environment for safety; switch explicitly with
switch_profile or environment=.
- For monorepos, always pass
configPath.
- For production-facing MCP setups, install with
--readonly to hide deploy, trigger_task, and cancel_run.
- Before a TRQL
query, always call get_query_schema(table) — it's cached server-side since v4.4.4, so there's no penalty.
- Respect the query 10k-row cap — add
LIMIT and time filters.
- For Managed Prompts, prefer
promote_prompt_version over long-lived overrides when iteration should flow through code; use overrides for hotfixes.
Deeper Reference
- @references/mcp-tools-reference.md — complete parameter documentation + REST API
- Sibling skills: observability (TRQL + dashboards), managed-prompts (prompt versioning workflow)
1---2name: mcp-patterns-43description: Trigger.dev MCP tools reference — all 33 tools, parameters, usage patterns, and common workflows as of v4.4.4. Use when the user asks about "trigger.dev MCP tools", "which trigger.dev tools are available", "how to use trigger.dev MCP", "trigger task via MCP", "list runs MCP", "profile switching", "TRQL queries from MCP", "dev server control", or "managed prompts overrides".4---56# Trigger.dev MCP Tool Patterns78Reference for every MCP tool provided by the official Trigger.dev MCP server (v4.4.4 — 33 tools across 9 categories).910> **Note:** This plugin provides MCP **knowledge**, not the MCP connection. Install the MCP server via `npx trigger.dev@latest install-mcp` or configure it manually in your project.1112## Install the MCP Server1314```bash15# Interactive installer (detects installed clients)16npx trigger.dev@latest install-mcp1718# Target a specific client19npx trigger.dev@latest install-mcp --client claude-code2021# Install across all supported clients22npx trigger.dev@latest install-mcp --yolo23```2425### Install Flags2627| Flag | Purpose |28|------|---------|29| `--client <name...>` | Install for specific client(s) — claude-code, cursor, windsurf, vscode, zed, cline, gemini-cli, amp, openai-codex, crush, opencode, ruler |30| `--scope <scope>` | `user`, `project`, or `local` config file |31| `--dev-only` | Restrict tools to the dev environment only (hides `deploy`, `list_preview_branches`) |32| `--readonly` | Hide write tools (`deploy`, `trigger_task`, `cancel_run`) — agent cannot make changes |33| `--project-ref <ref>` | Scope MCP to a single project (proj_xxx) |34| `--tag <tag>` | Pin CLI package version |35| `-a, --api-url <url>` | Self-hosted API URL |36| `--log-file <path>` | Write MCP server logs to file |37| `--log-level <level>` | debug / info / log / warn / error / none |38| `--yolo` | Install into every supported client |3940### Manual Config Example4142```json43{44 "mcpServers": {45 "trigger": {46 "command": "npx",47 "args": ["trigger.dev@latest", "mcp", "--dev-only", "--project-ref", "proj_abc123"]48 }49 }50}51```5253> **Tool annotations:** every tool carries `readOnlyHint` / `destructiveHint` metadata so MCP clients can gate write operations. `--readonly` enforces it server-side.5455## Shared Parameters5657Most tools accept these optional parameters:5859| Parameter | Description | Default |60|-----------|-------------|---------|61| `projectRef` | Project ref (proj_xxx) | Auto-detected from trigger.config.ts |62| `configPath` | Path to trigger.config.ts | Auto |63| `environment` | dev, staging, prod, preview | dev |64| `branch` | Branch name (required with preview) | — |6566## Documentation & Search6768| Tool | Description |69|------|-------------|70| `search_docs` | Search Trigger.dev documentation |7172## Project & Organization7374| Tool | Description |75|------|-------------|76| `list_orgs` | List your organizations |77| `list_projects` | List your projects |78| `create_project_in_org` | Create a new project in an org |79| `initialize_project` | Init Trigger.dev in a directory |8081## Task Management8283| Tool | Description |84|------|-------------|85| `get_current_worker` | Worker version, SDK version, task list, machine presets (**no longer inlines payload schemas** in v4.4.4) |86| `get_task_schema` | Fetch the payload schema for a specific task (replaces the inlined schemas that used to live on `get_current_worker`) |87| `trigger_task` | Trigger a task with payload and options |8889## Run Monitoring9091| Tool | Description |92|------|-------------|93| `list_runs` | List and filter runs by status, task, tag, period |94| `get_run_details` | Run trace, logs, output — **trace output is paginated with a cursor** since v4.4.4 |95| `get_span_details` | Inspect a single span inside a run — attributes, events, AI enrichment (model, tokens, cost), child runs. Span IDs now appear in `get_run_details` output. |96| `wait_for_run_to_complete` | Wait for a run to finish |97| `cancel_run` | Cancel a running/queued run |9899## Deployment100101| Tool | Description |102|------|-------------|103| `deploy` | Deploy to staging/production/preview |104| `list_deploys` | List deployments with filters |105| `list_preview_branches` | List preview branches (not available with `--dev-only`) |106107## Profile108109| Tool | Description |110|------|-------------|111| `whoami` | Show current profile, user, and API URL |112| `list_profiles` | List all configured CLI profiles and the active one |113| `switch_profile` | Change the active profile for this MCP session (affects all subsequent tool calls) |114115## Query & Analytics116117Powered by TRQL (Trigger.dev Query Language — SQL over ClickHouse). See the **observability** skill for TRQL syntax and examples.118119| Tool | Description |120|------|-------------|121| `get_query_schema` | Get columns, types, and descriptions for one TRQL table (now requires a `table` name — `runs`, `metrics`, or `llm_metrics`) |122| `query` | Execute a TRQL query. Results returned as text tables (~50% fewer tokens than JSON) |123| `list_dashboards` | List built-in dashboards and their widget IDs |124| `run_dashboard_query` | Execute a single widget query from a built-in dashboard |125126## Dev Server127128| Tool | Description |129|------|-------------|130| `start_dev_server` | Start `trigger dev` in the background (waits up to 30s for the worker to be ready) |131| `stop_dev_server` | Stop the running dev server |132| `dev_server_status` | Show status (`stopped` / `starting` / `ready` / `error`) and recent log lines (`lines` default 50) |133134## Managed Prompts135136Trigger.dev Managed Prompts — versioned prompts with dashboard overrides. See the **managed-prompts** skill for the full workflow.137138| Tool | Description |139|------|-------------|140| `list_prompts` | List managed prompts — slug, current version, override status, version count |141| `get_prompt_versions` | List versions for one prompt — labels (`current`/`override`/`latest`), source (`code`/`dashboard`), model, content |142| `promote_prompt_version` | Promote a code-sourced version to current (dashboard overrides use override tools) |143| `create_prompt_override` | Create a dashboard override (takes precedence over the current code version) |144| `update_prompt_override` | Update the active dashboard override |145| `remove_prompt_override` | Remove the override — revert to the current code version |146| `reactivate_prompt_override` | Reactivate a prior dashboard-sourced version as the active override |147148## Common Patterns149150### Trigger and Monitor151152```1531. get_current_worker(environment="dev") → task list1542. get_task_schema(taskIdentifier="process-order") → payload schema1553. trigger_task(taskId, payload) → run ID1564. wait_for_run_to_complete(runId) → result157```158159### Debug a Failed Run with AI Enrichment160161```1621. list_runs(status="FAILED", period="1d")1632. get_run_details(runId) → error trace + span IDs1643. get_span_details(runId, spanId) → llm model, tokens, cost per AI call1654. search_docs(query="<error topic>")166```167168### Deploy Flow169170```1711. deploy(environment="staging")1722. trigger_task(environment="staging") → verify1733. deploy(environment="prod")1744. list_deploys(environment="prod", limit=1) → confirm175```176177### Initialize Project178179```1801. list_orgs() → pick org1812. initialize_project(orgParam, projectName, cwd)1823. get_current_worker(environment="dev") → verify183```184185### Dev Server Lifecycle (agent-controlled)186187```1881. start_dev_server(configPath?) → launches `trigger dev` in background1892. dev_server_status(lines=50) → poll until status="ready"1903. trigger_task(...) → test against the dev worker1914. stop_dev_server() → tear down when done192```193194### Query Analytics (TRQL)195196```1971. get_query_schema(table="runs") → column list1982. query({199 query: "SELECT status, count() FROM runs GROUP BY status",200 period: "7d"201 }) → text table202```203204### Dashboard Metrics205206```2071. list_dashboards() → { dashboardId, widgets: [{ widgetId, title }] }2082. run_dashboard_query(dashboardId, widgetId, period="30d") → widget data209```210211### Switch Profile Mid-Session212213```2141. whoami() → current profile + API URL2152. list_profiles() → available profiles2163. switch_profile("self-hosted-prod") → all subsequent tool calls use the new profile217```218219### Prompt Override Hotfix220221```2221. list_prompts(environment="prod") → find slug2232. get_prompt_versions(slug="customer-reply") → see current/override state2243. create_prompt_override(slug, textContent="...revised copy...", commitMessage="Fix tone issue")2254. (iterate) update_prompt_override(slug, textContent="...")2265. remove_prompt_override(slug) → revert to code version when code is redeployed227```228229## Best Practices230231- **Prefer `get_task_schema` before `trigger_task`** — `get_current_worker` no longer ships schemas inline.232- Use `limit` and `period` to avoid fetching too many runs.233- Use `idempotencyKey` in trigger options to prevent duplicate runs.234- Default to the dev environment for safety; switch explicitly with `switch_profile` or `environment=`.235- For monorepos, always pass `configPath`.236- For production-facing MCP setups, install with `--readonly` to hide `deploy`, `trigger_task`, and `cancel_run`.237- Before a TRQL `query`, always call `get_query_schema(table)` — it's cached server-side since v4.4.4, so there's no penalty.238- Respect the query 10k-row cap — add `LIMIT` and time filters.239- For Managed Prompts, prefer `promote_prompt_version` over long-lived overrides when iteration should flow through code; use overrides for hotfixes.240241## Deeper Reference242243- @references/mcp-tools-reference.md — complete parameter documentation + REST API244- Sibling skills: **observability** (TRQL + dashboards), **managed-prompts** (prompt versioning workflow)
agents-store