github-featured/triggerdotdev--trigger.dev
2
0
Fork 0
Code Issues Pull Requests Deployments Models Agent Notes Packages Projects Releases Wiki Activity

docs: MCP Server 2.0 (#2385)

Browse Source 
* Add MCP Server documentation to documentation site

This change introduces comprehensive documentation for the Trigger.dev MCP Server, covering its installation, usage, and available tools. The addition is necessary to provide users with detailed guidance on leveraging the MCP Server for managing Trigger.dev projects, tasks, and deployment processes.

- Updated `docs.json` to include a new section for the MCP Server documentation, improving navigation and accessibility.
- Added `mcp-introduction.mdx` as an introductory guide to the MCP Server, detailing its purpose and installation steps.
- Included `mcp-tools.mdx`, a document outlining each tool available in the MCP Server, complete with descriptions and example usages.
- The new content is aimed at improving user understanding and efficiency in using Trigger.dev's MCP Server capabilities.

* Refactor MCP installation documentation

The changes were necessary to streamline the MCP installation guidance and align our documentation with the latest client support capabilities. Removing the manual installation section and redundant information helps reduce confusion for users.

- Updated installation instructions to lead with auto-configuration for supported clients.
- Cleaned up the options and examples sections to enhance clarity.
- Reformatted client configuration details for better readability.
- Removed outdated links in the "Next Steps" section, focusing on more direct resources such as available MCP tools.

* mcp docs edits

* Add debugMode to get_run_details

* add cancel_run

* Add list deployments tools

* Add list preview branches tool

* Docs: adds agent rules page

* Adds redirect for the CLI path to work

* Adds subagent install image

---------

Co-authored-by: James Ritchie <james@trigger.dev>
This commit is contained in:
Eric Allam
2025-08-22 15:37:35 +01:00
committed by GitHub
parent ad26cded99
commit 96243efe16
5 changed files with 844 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/docs.json
+12 -1
View File
@@ -165,6 +165,10 @@
}
]
},
{
"group": "MCP Server",
"pages": ["mcp-introduction", "mcp-tools", "mcp-agent-rules"]
},
{
"group": "Using the Dashboard",
"pages": ["run-tests", "troubleshooting-alerts", "replaying", "bulk-actions"]
@@ -298,7 +302,6 @@
"guides/ai-agents/verify-news-article"
]
},
"guides/cursor-rules",
"guides/frameworks/drizzle",
"guides/frameworks/prisma",
"guides/frameworks/sequin",
@@ -620,6 +623,14 @@
"source": "/management/projects/runs",
"destination": "/management/overview"
},
{
"source": "/guides/cursor-rules",
"destination": "/mcp-agent-rules"
},
{
"source": "/agents/rules/overview",
"destination": "/mcp-agent-rules"
},
{
"source": "/upgrade-to-v4",
"destination": "/migrating-from-v3"
docs/images/claude-code-subagent.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 107 KiB

docs/mcp-agent-rules.mdx
+118
View File
@@ -0,0 +1,118 @@
---
title: "Agent rules"
sidebarTitle: "Agent rules"
description: "Learn how to use the Trigger.dev agent rules with the MCP server"
tag: "new"
---
## What are Trigger.dev agent rules?
Trigger.dev agent rules are comprehensive instruction sets that guide AI assistants to write optimal Trigger.dev code. These rules ensure your AI assistant understands best practices, current APIs, and recommended patterns when working with Trigger.dev projects.
## Installation
Install the agent rules with the following command:
```bash
npx trigger.dev@latest install-rules
```
## Available rule sets
We provide five specialized rule sets, each optimized for different aspects of Trigger.dev development:
| Rule set | Tokens | Description | GitHub |
|:---------|:-------|:------------|:------------|
| **Basic tasks** | 1,200 | Essential rules for writing basic Trigger.dev tasks and fundamental patterns | [View](https://github.com/triggerdotdev/trigger.dev/blob/main/rules/4.0.0/basic-tasks.md) |
| **Advanced tasks** | 3,000 | Comprehensive rules for complex workflows, error handling, and advanced task patterns | [View](https://github.com/triggerdotdev/trigger.dev/blob/main/rules/4.0.0/advanced-tasks.md) |
| **Scheduled tasks** | 780 | Specialized guidance for cron jobs, scheduled workflows, and time-based triggers | [View](https://github.com/triggerdotdev/trigger.dev/blob/main/rules/4.0.0/scheduled-tasks.md) |
| **Configuration** | 1,900 | Complete guide for trigger.config.ts setup, environment configuration, and project structure | [View](https://github.com/triggerdotdev/trigger.dev/blob/main/rules/4.0.0/config.md) |
| **Realtime** | 1,700 | Using Trigger.dev Realtime features and frontend integration patterns | [View](https://github.com/triggerdotdev/trigger.dev/blob/main/rules/4.0.0/realtime.md) |
## Claude Code subagent
For Claude Code users, we provide a subagent called `trigger-dev-expert` that's an expert at writing well-structured Trigger.dev code.
### Installation
The subagent is available as an option when running the rules installation command. Select "Claude Code" as your client and choose to include the subagent when prompted.
![Claude Code subagent installation](/images/claude-code-subagent.png)
### Usage
Activate the subagent in your prompts by requesting it explicitly:
```markdown
use the trigger-dev-expert subagent to create a trigger.dev job that accepts a video url, processes it with ffmpeg to extract the audio, runs the audio through a text-to-speech API like openai, and then uploads both the transcription and the audio to s3
```
The subagent works best when combined with the appropriate rule sets installed alongside it, providing both high-level architectural guidance and detailed implementation knowledge.
## Supported AI clients
The Trigger.dev rules work across a wide range of AI coding assistants and editors:
| Client | Rule activation | Docs |
|:--------|:----------------|:--------------|
| **Cursor** | Automatic when working in trigger directories | [Link](https://docs.cursor.com/en/context/rules#rules/) |
| **Claude Code** | Context-aware activation + custom subagent | [Link](https://docs.anthropic.com/en/docs/claude-code) |
| **VSCode Copilot** | Integration with GitHub Copilot chat | [Link](https://code.visualstudio.com/docs/copilot/overview) |
| **Windsurf** | Automatic activation in Trigger.dev projects | [Link](https://docs.windsurf.com/windsurf/cascade/memories#rules) |
| **Gemini CLI** | Command-line integration | [Link](https://ai.google.dev/gemini-api/docs) |
| **Cline** | Automatic context detection | [Link](https://github.com/cline/cline) |
| **Sourcegraph AMP** | Code intelligence integration | [Link](https://sourcegraph.com/docs) |
| **Kilo** | Custom rule integration | [Link](https://kilocode.ai/docs/advanced-usage/custom-rules) |
| **Ruler** | Rule management | [Link](https://github.com/intellectronica/ruler) |
| **AGENTS.md** | Universal format for OpenAI Codex, Jules, OpenCode, etc. | |
### Rule activation behavior
Different AI tools handle rules differently:
- **Automatic Activation**: Cursor, Windsurf, VSCode Copilot, and Cline automatically apply relevant rules when working in Trigger.dev projects or when `trigger.config.ts` is detected
- **Context-Aware**: Claude Code intelligently applies rules based on the current context and file types
- **Manual Integration**: AGENTS.md clients and others append rules to configuration files for manual activation
## Keeping rules updated
Trigger.dev rules are regularly updated to reflect new features, API changes, and best practices. The CLI includes automatic update detection.
### Automatic update notifications
When running `npx trigger.dev@latest dev`, you'll receive notifications when newer rule versions are available with a simple update command.
### Manual updates
Update rules anytime with:
```bash
npx trigger.dev@latest install-rules
```
The update process replaces existing rules without creating duplicates, keeping your configuration files clean and organized.
### Why updates matter
- **Current API patterns**: Access the latest Trigger.dev APIs and features
- **Performance optimizations**: Benefit from improved patterns and practices
- **Deprecated pattern avoidance**: Prevent AI assistants from generating outdated code
- **New feature support**: Immediate access to newly released capabilities
## Getting started
1. Install the rules:
```bash
npx trigger.dev@latest install-rules
```
2. Follow the prompts to install the rules for your AI client.
3. Consider installing the `trigger-dev-expert` subagent if using Claude Code.
## Next steps
- [Install the MCP server](/mcp-introduction) for complete Trigger.dev integration
- [Explore MCP tools](/mcp-tools) for project management and task execution
docs/mcp-introduction.mdx
+187
View File
@@ -0,0 +1,187 @@
---
title: "MCP Introduction"
sidebarTitle: "Introduction"
description: "Learn how to install and configure the Trigger.dev MCP Server"
tag: "new"
---
## What is the Trigger.dev MCP Server?
The Trigger.dev MCP (Model Context Protocol) Server enables AI assistants to interact directly with your Trigger.dev projects. It provides a comprehensive set of tools to:
- Search Trigger.dev documentation
- Initialize new Trigger.dev projects
- List and manage your projects and organizations
- Get task information and trigger task runs
- Deploy projects to different environments
- Monitor run details and list runs with filtering options
## Installation
### Automatic Installation (Recommended)
The easiest way to install the Trigger.dev MCP Server is using the interactive installation wizard:
```bash
npx trigger.dev@latest install-mcp
```
This command will guide you through:
1. Selecting which MCP clients to configure
2. Choosing installation scope (user, project, or local)
3. Automatically configuring the selected clients
## Command Line Options
The `install-mcp` command supports the following options:
### Core Options
- `-p, --project-ref <project ref>` - Scope the MCP server to a specific Trigger.dev project by providing its project ref
- `-t, --tag <package tag>` - The version of the trigger.dev CLI package to use for the MCP server (default: latest or v4-beta)
- `--dev-only` - Restrict the MCP server to the dev environment only
- `--yolo` - Install the MCP server into all supported clients automatically
- `--scope <scope>` - Choose the scope of the MCP server: `user`, `project`, or `local`
- `--client <clients...>` - Choose specific client(s) to install into
### Configuration Options
- `--log-file <log file>` - Configure the MCP server to write logs to a file
- `-a, --api-url <value>` - Configure a custom Trigger.dev API URL
- `-l, --log-level <level>` - Set CLI log level (debug, info, log, warn, error, none)
## Authentication
You can use the MCP server without authentication with the `search_docs` tool, but for any other tool call you will need to authenticate the MCP server via the same method as the [Trigger.dev CLI](/cli-login-commands).The first time you attempt to use a tool that requires authentication, you will be prompted to authenticate the MCP server via the MCP client.
### Examples
Install for all supported clients:
```bash
npx trigger.dev@latest install-mcp --yolo
```
Install for specific clients:
```bash
npx trigger.dev@latest install-mcp --client claude-code cursor --scope user
```
Install with development environment restriction:
```bash
npx trigger.dev@latest install-mcp --dev-only --project-ref proj_abc123
```
## Supported MCP Clients
The Trigger.dev MCP Server supports the following clients:
| Client | Scope Options | Configuration File | Documentation |
| -------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Claude Code** | user, project, local | `~/.claude.json` or `./.mcp.json` (project/local scope) | [Claude Code MCP Docs](https://docs.anthropic.com/en/docs/claude-code/mcp) |
| **Cursor** | user, project | `~/.cursor/mcp.json` (user) or `./.cursor/mcp.json` (project) | [Cursor MCP Docs](https://docs.cursor.com/features/mcp) |
| **VSCode** | user, project | `~/Library/Application Support/Code/User/mcp.json` (user) or `./.vscode/mcp.json` (project) | [VSCode MCP Docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) |
| **Zed** | user | `~/.config/zed/settings.json` | [Zed Context Servers Docs](https://zed.dev/docs/context-servers) |
| **Windsurf** | user | `~/.codeium/windsurf/mcp_config.json` | [Windsurf MCP Docs](https://docs.codeium.com/windsurf/mcp) |
| **Gemini CLI** | user, project | `~/.gemini/settings.json` (user) or `./.gemini/settings.json` (project) | [Gemini CLI MCP Tutorial](https://medium.com/@joe.njenga/gemini-cli-mcp-tutorial-setup-commands-practical-use-step-by-step-example-b57f55db5f4a) |
| **Charm Crush** | user, project, local | `~/.config/crush/crush.json` (user), `./crush.json` (project), or `./.crush.json` (local) | [Charm MCP Docs](https://github.com/charmbracelet/mcp) |
| **Cline** | user | `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` | [Cline MCP Docs](https://github.com/saoudrizwan/claude-dev#mcp) |
| **OpenAI Codex CLI** | user | `~/.codex/config.toml` | See OpenAI Codex CLI documentation for MCP configuration |
| **Sourcegraph AMP** | user | `~/.config/amp/settings.json` | [Sourcegraph AMP MCP Docs](https://docs.sourcegraph.com/amp/mcp) |
| **opencode** | user, project | `~/.config/opencode/opencode.json` (user) or `./opencode.json` (project) | [opencode MCP Docs](https://opencode.ai/docs/mcp-servers/) |
## Manual Configuration
If your client isn't directly supported by the installer, you can configure it manually. The MCP server uses the following configuration:
**Server Name:** `trigger`
**Command:** `npx`
**Arguments:** `["trigger.dev@latest", "mcp"]`
### Example JSON Configuration
```json
{
"mcpServers": {
"trigger": {
"command": "npx",
"args": ["trigger.dev@latest", "mcp"]
}
}
}
```
### Example TOML Configuration (for Codex CLI)
```toml
[mcp_servers.trigger]
command = "npx"
args = ["trigger.dev@latest", "mcp"]
```
### Additional Options
You can add these optional arguments to customize the server behavior:
- `--log-file <path>` - Log to a specific file
- `--api-url <url>` - Use a custom Trigger.dev API URL
- `--dev-only` - Restrict to dev environment only
- `--project-ref <ref>` - Scope to a specific project
## Environment-Specific Configuration
### Development Only
To restrict the MCP server to only work with the development environment:
```json
{
"mcpServers": {
"trigger": {
"command": "npx",
"args": ["trigger.dev@latest", "mcp", "--dev-only"]
}
}
}
```
### Project-Scoped
To scope the server to a specific project:
```json
{
"mcpServers": {
"trigger": {
"command": "npx",
"args": ["trigger.dev@latest", "mcp", "--project-ref", "proj_your_project_ref"]
}
}
}
```
## Verification
After installation, restart your MCP client and look for a server named "trigger". The server should connect automatically and provide access to all Trigger.dev tools.
## Getting Started
Once installed, you can start using the MCP server by asking your AI assistant questions like:
- `"Search the trigger docs for a ffmpeg example"`
- `"Initialize trigger.dev in my project"`
- `"Get all tasks in my project"`
- `"Trigger my foobar task with a sample payload"`
- `"Get the details of the latest run for my foobar task"`
- `"List all runs for my foobar task"`
- `"Deploy my project to staging"`
- `"Deploy my project to production"`
## Next Steps
- [Explore available MCP tools](/mcp-tools)
docs/mcp-tools.mdx
+527
View File
@@ -0,0 +1,527 @@
---
title: "MCP Tools"
sidebarTitle: "Tools"
description: "Learn about the tools available in the Trigger.dev MCP Server"
tag: "new"
---
The Trigger.dev MCP Server provides a comprehensive set of tools that enable AI assistants to interact with your Trigger.dev projects. These tools cover everything from project management to task execution and monitoring.
## Documentation and Search Tools
### search_docs
Search across the Trigger.dev documentation to find relevant information, code examples, API references, and guides.
<ParamField query="query" type="string" required>
The search query to find information in the Trigger.dev documentation
</ParamField>
**Usage Examples:**
- "How do I create a scheduled task?"
- "webhook examples"
- "deployment configuration"
- "error handling patterns"
<CodeGroup>
```json Example Usage
{
"tool": "search_docs",
"arguments": {
"query": "webhook examples"
}
}
```
</CodeGroup>
## Project Management Tools
### list_projects
List all projects in your Trigger.dev account.
**No parameters required**
<ResponseField name="projects" type="array">
Array of project objects containing project details, IDs, and metadata
</ResponseField>
<CodeGroup>
```json Example Response
{
"projects": [
{
"id": "proj_abc123",
"name": "My App",
"slug": "my-app",
"organizationId": "org_xyz789"
}
]
}
```
</CodeGroup>
### list_orgs
List all organizations you have access to.
**No parameters required**
<ResponseField name="orgs" type="array">
Array of organization objects containing organization details and metadata
</ResponseField>
### create_project_in_org
Create a new project in an organization.
<ParamField query="orgParam" type="string" required>
The organization to create the project in, can either be the organization slug or the ID. Use the
`list_orgs` tool to get a list of organizations and ask the user to select one.
</ParamField>
<ParamField query="name" type="string" required>
The name of the project to create
</ParamField>
<CodeGroup>
```json Example Usage
{
"tool": "create_project_in_org",
"arguments": {
"orgParam": "my-org",
"name": "New Project"
}
}
```
</CodeGroup>
### initialize_project
Initialize Trigger.dev in your project with automatic setup and configuration.
<ParamField query="orgParam" type="string" required>
The organization to create the project in, can either be the organization slug or the ID. Use the
`list_orgs` tool to get a list of organizations and ask the user to select one.
</ParamField>
<ParamField query="projectRef" type="string" optional>
The trigger.dev project ref, starts with `proj_`. We will attempt to automatically detect the
project ref if running inside a directory that includes a trigger.config.ts file.
</ParamField>
<ParamField query="projectName" type="string" required>
The name of the project to create. If projectRef is not provided, we will use this name to create
a new project in the organization you select.
</ParamField>
<ParamField query="cwd" type="string" required>
The current working directory of the project
</ParamField>
## Task Management Tools
### get_tasks
Get all tasks in a project.
<ParamField query="projectRef" type="string" optional>
The trigger.dev project ref, starts with `proj_`. We will attempt to automatically detect the
project ref if running inside a directory that includes a trigger.config.ts file.
</ParamField>
<ParamField query="configPath" type="string" optional>
The path to the trigger.config.ts file. Only used when the trigger.config.ts file is not at the
root dir (like in a monorepo setup). If not provided, we will try to find the config file in the
current working directory.
</ParamField>
<ParamField query="environment" type="string" default="dev">
The environment to get tasks for. Options: `dev`, `staging`, `prod`, `preview`
</ParamField>
<ParamField query="branch" type="string" optional>
The branch to get tasks for, only used for preview environments
</ParamField>
<CodeGroup>
```json Example Usage
{
"tool": "get_tasks",
"arguments": {
"projectRef": "proj_abc123",
"environment": "dev"
}
}
```
</CodeGroup>
### trigger_task
Trigger a task to run.
<ParamField query="projectRef" type="string" optional>
The trigger.dev project ref, starts with `proj_`. We will attempt to automatically detect the
project ref if running inside a directory that includes a trigger.config.ts file.
</ParamField>
<ParamField query="configPath" type="string" optional>
The path to the trigger.config.ts file. Only used when the trigger.config.ts file is not at the
root dir (like in a monorepo setup).
</ParamField>
<ParamField query="environment" type="string" default="dev">
The environment to trigger the task in. Options: `dev`, `staging`, `prod`, `preview`
</ParamField>
<ParamField query="branch" type="string" optional>
The branch to trigger the task in, only used for preview environments
</ParamField>
<ParamField query="taskId" type="string" required>
The ID/slug of the task to trigger. Use the `get_tasks` tool to get a list of tasks and ask the
user to select one if it's not clear which one to use.
</ParamField>
<ParamField query="payload" type="string" required>
The payload to trigger the task with, must be a valid JSON string
</ParamField>
<ParamField query="options" type="object" optional>
Additional options for the task run
<Expandable title="options properties">
<ParamField query="queue.name" type="string" optional>
The name of the queue to trigger the task in, by default will use the queue configured in the
task
</ParamField>
<ParamField query="delay" type="string | datetime" optional>
The delay before the task run is executed
</ParamField>
<ParamField query="idempotencyKey" type="string" optional>
The idempotency key to use for the task run
</ParamField>
<ParamField query="machine" type="string" optional>
The machine preset to use for the task run. Options: `micro`, `small-1x`, `small-2x`,
`medium-1x`, `medium-2x`, `large-1x`, `large-2x`
</ParamField>
<ParamField query="maxAttempts" type="integer" optional>
The maximum number of attempts to retry the task run
</ParamField>
<ParamField query="maxDuration" type="number" optional>
The maximum duration in seconds of the task run
</ParamField>
<ParamField query="tags" type="array" optional>
Tags to add to the task run. Must be less than 128 characters and cannot have more than 5
</ParamField>
<ParamField query="ttl" type="string | integer" default="10m">
The time to live of the task run. If the run doesn't start executing within this time, it will
be automatically cancelled.
</ParamField>
</Expandable>
</ParamField>
<CodeGroup>
```json Example Usage
{
"tool": "trigger_task",
"arguments": {
"projectRef": "proj_abc123",
"taskId": "email-notification",
"payload": "{\"email\": \"user@example.com\", \"subject\": \"Hello World\"}",
"options": {
"tags": ["urgent"],
"maxAttempts": 3
}
}
}
```
</CodeGroup>
## Run Monitoring Tools
### get_run_details
Get the details of a specific task run.
<ParamField query="projectRef" type="string" optional>
The trigger.dev project ref, starts with `proj_`. We will attempt to automatically detect the
project ref if running inside a directory that includes a trigger.config.ts file.
</ParamField>
<ParamField query="configPath" type="string" optional>
The path to the trigger.config.ts file. Only used when the trigger.config.ts file is not at the
root dir (like in a monorepo setup).
</ParamField>
<ParamField query="environment" type="string" default="dev">
The environment to get the run details from. Options: `dev`, `staging`, `prod`, `preview`
</ParamField>
<ParamField query="branch" type="string" optional>
The branch to get the run details from, only used for preview environments
</ParamField>
<ParamField query="runId" type="string" required>
The ID of the run to get the details of, starts with `run_`
</ParamField>
<ParamField query="debugMode" type="boolean" optional>
Enable debug mode to get more detailed information about the run, including the entire trace (all logs and spans for the run and any child run). Set this to true if prompted to debug a run.
</ParamField>
### cancel_run
Cancel a running task.
<ParamField query="runId" type="string" required>
The ID of the run to cancel, starts with `run_`
</ParamField>
<ParamField query="projectRef" type="string" optional>
The trigger.dev project ref, starts with `proj_`. We will attempt to automatically detect the
project ref if running inside a directory that includes a trigger.config.ts file.
</ParamField>
<ParamField query="configPath" type="string" optional>
The path to the trigger.config.ts file. Only used when the trigger.config.ts file is not at the
root dir (like in a monorepo setup).
</ParamField>
<ParamField query="environment" type="string" default="dev">
The environment to cancel the run in. Options: `dev`, `staging`, `prod`, `preview`
</ParamField>
<ParamField query="branch" type="string" optional>
The branch to cancel the run in, only used for preview environments
</ParamField>
<CodeGroup>
```json Example Usage
{
"tool": "cancel_run",
"arguments": {
"runId": "run_abc123",
"projectRef": "proj_abc123"
}
}
```
</CodeGroup>
### list_runs
List all runs for a project with comprehensive filtering options.
<ParamField query="projectRef" type="string" optional>
The trigger.dev project ref, starts with `proj_`. We will attempt to automatically detect the
project ref if running inside a directory that includes a trigger.config.ts file.
</ParamField>
<ParamField query="configPath" type="string" optional>
The path to the trigger.config.ts file. Only used when the trigger.config.ts file is not at the
root dir (like in a monorepo setup).
</ParamField>
<ParamField query="environment" type="string" default="dev">
The environment to list runs from. Options: `dev`, `staging`, `prod`, `preview`
</ParamField>
<ParamField query="branch" type="string" optional>
The branch to list runs from, only used for preview environments
</ParamField>
<ParamField query="cursor" type="string" optional>
The cursor to use for pagination, starts with `run_`
</ParamField>
<ParamField query="limit" type="integer" optional>
The number of runs to list in a single page. Up to 100
</ParamField>
<ParamField query="status" type="string" optional>
Filter for runs with this run status. Options: `PENDING_VERSION`, `QUEUED`, `DEQUEUED`,
`EXECUTING`, `WAITING`, `COMPLETED`, `CANCELED`, `FAILED`, `CRASHED`, `SYSTEM_FAILURE`, `DELAYED`,
`EXPIRED`, `TIMED_OUT`
</ParamField>
<ParamField query="taskIdentifier" type="string" optional>
Filter for runs that match this task identifier
</ParamField>
<ParamField query="version" type="string" optional>
Filter for runs that match this version, e.g. `20250808.3`
</ParamField>
<ParamField query="tag" type="string" optional>
Filter for runs that include this tag
</ParamField>
<ParamField query="from" type="string" optional>
Filter for runs created after this ISO 8601 timestamp
</ParamField>
<ParamField query="to" type="string" optional>
Filter for runs created before this ISO 8601 timestamp
</ParamField>
<ParamField query="period" type="string" optional>
Filter for runs created in the last N time period. Examples: `7d`, `30d`, `365d`
</ParamField>
<ParamField query="machine" type="string" optional>
Filter for runs that match this machine preset. Options: `micro`, `small-1x`, `small-2x`,
`medium-1x`, `medium-2x`, `large-1x`, `large-2x`
</ParamField>
<CodeGroup>
```json Example Usage
{
"tool": "list_runs",
"arguments": {
"projectRef": "proj_abc123",
"status": "COMPLETED",
"limit": 10,
"period": "7d"
}
}
```
</CodeGroup>
## Deployment Tools
### deploy
Deploy a project to staging or production environments.
<ParamField query="projectRef" type="string" optional>
The trigger.dev project ref, starts with `proj_`. We will attempt to automatically detect the
project ref if running inside a directory that includes a trigger.config.ts file.
</ParamField>
<ParamField query="configPath" type="string" optional>
The path to the trigger.config.ts file. Only used when the trigger.config.ts file is not at the
root dir (like in a monorepo setup).
</ParamField>
<ParamField query="environment" type="string" default="prod">
The environment to deploy to. Options: `staging`, `prod`, `preview`
</ParamField>
<ParamField query="branch" type="string" optional>
The branch to deploy, only used for preview environments
</ParamField>
<ParamField query="skipPromotion" type="boolean" optional>
Skip promoting the deployment to the current deployment for the environment
</ParamField>
<ParamField query="skipSyncEnvVars" type="boolean" optional>
Skip syncing environment variables when using the syncEnvVars extension
</ParamField>
<ParamField query="skipUpdateCheck" type="boolean" optional>
Skip checking for @trigger.dev package updates
</ParamField>
<CodeGroup>
```json Example Usage
{
"tool": "deploy",
"arguments": {
"projectRef": "proj_abc123",
"environment": "prod",
"skipUpdateCheck": true
}
}
```
</CodeGroup>
### list_deployments
List deployments for a project with comprehensive filtering options.
<ParamField query="projectRef" type="string" optional>
The trigger.dev project ref, starts with `proj_`. We will attempt to automatically detect the
project ref if running inside a directory that includes a trigger.config.ts file.
</ParamField>
<ParamField query="configPath" type="string" optional>
The path to the trigger.config.ts file. Only used when the trigger.config.ts file is not at the
root dir (like in a monorepo setup).
</ParamField>
<ParamField query="environment" type="string" default="prod">
The environment to list deployments for. Options: `staging`, `prod`, `preview`
</ParamField>
<ParamField query="branch" type="string" optional>
The branch to list deployments from, only used for preview environments
</ParamField>
<ParamField query="cursor" type="string" optional>
The deployment ID to start the search from, to get the next page
</ParamField>
<ParamField query="limit" type="number" optional>
The number of deployments to return, defaults to 20 (max 100)
</ParamField>
<ParamField query="status" type="string" optional>
Filter deployments that are in this status. Options: `PENDING`, `BUILDING`, `DEPLOYING`, `DEPLOYED`, `FAILED`, `CANCELED`, `TIMED_OUT`
</ParamField>
<ParamField query="from" type="string" optional>
The date to start the search from, in ISO 8601 format
</ParamField>
<ParamField query="to" type="string" optional>
The date to end the search, in ISO 8601 format
</ParamField>
<ParamField query="period" type="string" optional>
The period to search within. Examples: `1d`, `7d`, `3h`
</ParamField>
<CodeGroup>
```json Example Usage
{
"tool": "list_deployments",
"arguments": {
"projectRef": "proj_abc123",
"environment": "prod",
"status": "DEPLOYED",
"limit": 10
}
}
```
</CodeGroup>
### list_preview_branches
List all preview branches in the project.
<ParamField query="projectRef" type="string" optional>
The trigger.dev project ref, starts with `proj_`. We will attempt to automatically detect the
project ref if running inside a directory that includes a trigger.config.ts file.
</ParamField>
<ParamField query="configPath" type="string" optional>
The path to the trigger.config.ts file. Only used when the trigger.config.ts file is not at the
root dir (like in a monorepo setup). If not provided, we will try to find the config file in the
current working directory.
</ParamField>
<CodeGroup>
```json Example Usage
{
"tool": "list_preview_branches",
"arguments": {
"projectRef": "proj_abc123"
}
}
```
</CodeGroup>
<Callout type="warning">
The deploy tool and list_preview_branches tool are not available when the MCP server is running with the `--dev-only` flag.
</Callout>