# Trigger.dev MCP

> Trigger.dev gives your AI agent direct control over your background job infrastructure. You can list task runs, check for failures in specific environments, inspect full payloads, or even trigger a new job run—all conversationally, without opening the dashboard.

## Overview
- **Category:** ship-it
- **Price:** Free
- **Tags:** background-jobs, workflow-automation, event-driven, task-scheduling, observability, typescript

## Description

You don't gotta jump through a dozen dashboards just to check why some background job blew up. **Trigger.dev** gives your AI agent direct access to your entire job infrastructure, letting you manage everything with plain English commands. It’s like having the full admin console right in your chat window.

### What You Can Control

Your agent can first scope your investigation by calling `list_projects`, which returns every project name and ID connected to Trigger.dev so you know exactly what context you're working in. It runs `list_environments` to give you a full list of deployment scopes—things like 'staging' or 'production'—letting you pinpoint where the failure happened. You can also use `list_schedules` to retrieve all scheduled tasks, showing their specific cron schedule definitions so you know when things are supposed to run.

When you need to see what jobs have actually run, your agent calls `list_runs`. This tool lists multiple task runs based on criteria like a time window or status (say, 'failed' or 'completed'), giving you an immediate overview of execution times and statuses. If you find a specific job ID that needs deep inspection, the agent uses `get_run` to retrieve comprehensive details for that run. That dump includes the full logs, the exact input payloads used, and any error stacks generated during the process.

If a job is running wild or doing something it shouldn't, you can instantly stop it by calling `cancel_run`, which kills a background task immediately using its unique ID. If you find a bug fix that needs testing without writing new code, the agent runs `replay_run`. This re-executes a specific past job run, using its original input payload so you can verify fixes safely.

Need to test something right now? You don't need an external webhook or manual setup. The agent calls `trigger_task` to manually start an asynchronous background process instantly, simulating exactly what an incoming event would do.

### How Your Agent Handles It

You just tell your AI client what you want done—for example, 'Show me all failed inventory sync jobs in production that ran last week.' The agent handles the sequence: it first uses `list_environments` to confirm 'production' is a valid scope. Then, it combines `list_runs` with filtering logic for status and time range. It presents you with the list of IDs, so you can then tell it, 'Get me the full logs for run ID 123.' The agent executes `get_run`, pulling back every log line and payload detail without you ever touching a dashboard. If you find something that looks good but needs to be validated against current data, you just ask it to replay the job using its previous settings via `replay_run`.

## Tools

### list_projects
Retrieves the names and IDs of every project connected to Trigger.dev, helping you narrow down the context.

### list_runs
Lists multiple task runs based on criteria like time frame or status (e.g., 'failed' or 'completed').

### get_run
Retrieves comprehensive details for a single job run, including logs and input payloads.

### trigger_task
Manually starts an asynchronous background task right now, simulating an incoming webhook or event.

### cancel_run
Stops a currently running background task immediately using its unique ID.

### replay_run
Re-executes a specific job run using its previous input payload to test fixes without writing new code.

### list_schedules
Retrieves a list of scheduled tasks, showing their cron schedule definitions.

### list_environments
Returns a list of all configured deployment scopes (like 'dev' or 'prod') so you can scope your query correctly.

## Prompt Examples

**Prompt:** 
```
Are there any failed background jobs in production?
```

**Response:** 
```
I found 2 failed runs in the last 24 hours: 'process-webhook' failed with a timeout error (3 retries exhausted) and 'sync-inventory' failed due to a database connection error. Both occurred between 3:00-3:15 AM UTC.
```

**Prompt:** 
```
Show me the details of the last 'process-webhook' run.
```

**Response:** 
```
Run ID: run_abc123. Status: FAILED. Duration: 30.2s (timeout at 30s). Error: 'Request timeout after 30000ms at postWebhook step'. Input payload: {event: 'order.created', id: 'ord_xyz'}. Retries: 3/3 exhausted.
```

**Prompt:** 
```
How many jobs ran successfully today?
```

**Response:** 
```
Today's stats: 1,247 total runs — 1,238 successful (99.3%), 7 failed (0.6%), and 2 currently running. Average execution time: 2.4 seconds. Most active task: 'process-order' with 892 runs.
```

## Capabilities

### List all task runs
The agent retrieves a list of job executions, showing status (success/fail) and duration.

### Get specific run details
You retrieve the full history for one run ID, including logs, input payloads, and error stacks.

### List project environments
The agent queries the available deployment scopes (e.g., dev, staging) so you can target your investigation.

### Trigger a new job task
You initiate an asynchronous background process immediately using the tool.

### Replay a completed run
The agent runs a previously successful or failed job again to verify fixes without manual setup.

## Use Cases

### A webhook failed overnight
The system reported an issue with order processing. Instead of logging into Trigger.dev, the developer asks their agent: 'Show me all failed runs for process-webhook in production.' The agent uses `list_runs` and reports two failure IDs immediately, allowing the dev to use `get_run` on the worst one.

### Verifying a database fix
After updating connection credentials, the ops engineer wants to verify the job runs correctly. They ask their agent to 'replay the inventory sync run' using the old payload. The agent calls `replay_run`, confirming the job completes successfully without new errors.

### Checking deployment safety
A feature is moving from staging to prod. Before promotion, a tech lead asks: 'What are the last 10 runs for this project in the staging environment?' The agent calls `list_environments` and then `list_runs`, providing a clear audit trail across environments.

### Simulating an event trigger
You need to test a new payment flow without actually processing money. You ask your agent: 'Trigger the payment processor task now.' The agent executes `trigger_task`, giving you a run ID that you can monitor live using other tools.

## Benefits

- See immediate failover status using `list_runs`. You don't have to click through dozens of logs; the agent gives you a summarized list of failures, showing which tasks need attention right now.
- Debug complex issues by calling `get_run` with a specific run ID. This tool pulls up the full payload and error stack in one go, eliminating manual log hunting across different tabs.
- Test fixes safely without touching production code. Use `replay_run` to re-execute a failed job against its original input data, confirming the fix works before deployment.
- Scope your investigation instantly with `list_environments`. You can ask for 'failed runs in staging' and never accidentally look at live production data again.
- Control the system when it breaks. If a process is stuck, you don't wait—you call `cancel_run` via your agent to halt the job immediately.

## How It Works

The bottom line is: you get instant, conversational visibility into your entire background job pipeline without touching a UI dashboard.

1. Subscribe to the Trigger.dev integration on Vinkius and generate your Secret API Key.
2. Instruct your AI agent with a specific request (e.g., 'What failed jobs ran yesterday?').
3. The agent uses the appropriate tool (`list_runs`, `get_run`, etc.) to pull live data directly from Trigger.dev's API and reports it in plain text.

## Frequently Asked Questions

**How do I get my Trigger.dev API key?**
Log in to your Trigger.dev dashboard at **cloud.trigger.dev**. Open your project, then find the **API Keys** section in the project settings. Copy your **Secret API Key** (it starts with `tr_dev_` for development or `tr_prod_` for production). Paste it into the configuration field below. For Personal Access Tokens (used for admin operations), go to **Profile → Personal Access Tokens** tab instead.

**Can my AI agent tell me why a background job failed in production?**
Yes. Ask your agent to list failed runs and it returns the task name, error message, stack trace, execution duration, and retry count for each failure. You can then drill into a specific run to see the exact input payload and which step failed — cutting your debugging time from minutes to seconds.

**What if I'm on-call and need to check job health at 2 AM?**
Just ask your AI agent 'Are there any failed jobs in production?' and get an instant triage report — number of failures, which tasks are affected, when they started failing, and whether retries resolved them. No need to open a browser, log in, or navigate dashboards in the middle of the night.

**Does it support multiple environments like dev, staging, and production?**
Yes. Each API key is scoped to a specific environment (dev or prod), just like in Trigger.dev itself. You can configure separate integrations for each environment, or switch between them by updating the API key — giving you full control over which environment your AI agent queries.

**How do I use the `trigger_task` tool to run a job manually?**
Yes, your agent can trigger tasks instantly. You just specify the task name and any input payload it requires. This lets you test workflows on demand without having to wait for cron schedules.

**When I use `get_run`, what details can my AI agent see about the task?**
The agent sees comprehensive run data, including input payloads, final outputs, and full execution logs. This means you get everything needed to debug an issue without manually scraping logs.

**Can I use Trigger.dev to fix bad data by replaying a job using `replay_run`?**
Yep, you can use the `replay_run` tool to rerun completed tasks. This is useful for fixing bugs or testing fixes on historical data without affecting your live production environment.

**How do I know which projects are available using `list_projects`?**
The agent will list all accessible projects and environments for you. This gives instant visibility into your entire job infrastructure, so you don't have to guess where a task belongs.