# Trigger.dev MCP > Trigger.dev manages and controls complex background workflows directly through your AI agent. This MCP server lets you trigger tasks instantly, schedule recurring cron jobs, monitor job history, and manage environment variables—all without leaving your IDE or chat client. ## Overview - **Category:** developer-tools - **Price:** Free - **Tags:** background-jobs, task-scheduling, workflow-automation, serverless, monitoring ## Description You gotta manage complex workflows without leaving your chat client or IDE. The **Trigger.dev MCP Server** lets your AI agent handle all of it—from kicking off a single task to running massive data batches and setting up recurring cron jobs. You're not just calling an API; you're controlling the entire lifecycle of background processes. ### Starting Jobs, Big or Small Need to run something? You start with simple commands. Use `trigger_task` to fire off a single job instantly using its unique ID. If you gotta process a huge chunk of data—say, sending out thousands of reports—you use `batch_trigger_tasks` to send up to 1,000 tasks in one go. For more structured, multi-step processing, call `create_batch` first; this sets up a new batch container for you. Once that batch finishes, you grab the final output and results using `get_batch_results`. You can also manage intermediate steps with workflows by calling `complete_waitpoint`, which signals that one part of a process is done and ready to move on. ### Keeping Things Running Smoothly Things break. Jobs fail, or they just get interrupted. We got ways to fix that. If a job stalls, you can generate a temporary token with `create_waitpoint_token` to resume the exact process where it stopped. You also control jobs in progress; use `cancel_run` to kill any running background task immediately. If something fails and you gotta try again, call `replay_run` to force that specific job attempt to run through the system again. For fine-tuning a finished job's history, you update its metadata using `update_run_metadata`. ### Checking the Scoreboard: Status and History You need proof it worked, or at least an idea why it didn't. Use `get_run` to pull every detail, status code, and log for one specific job run ID. If you wanna see what happened across multiple environments—maybe checking runs from last week versus yesterday—you use `list_runs`. This tool lets you filter those results by date or status so you only see the junk you care about. Need to know how many jobs are running right now? You can list all active and defined schedules using `list_schedules`. ### Governing the System Environment Every job needs its proper settings, or it'll crap out. This server lets you manage environment variables like a pro. Use `create_env_var` to set up new variables for future jobs, or use `update_env_var` if the value changes but the variable name stays put. Don't forget `delete_env_var` when you’re done with a setting. You can see everything configured by running `list_env_vars`. If you need to change how many tasks run concurrently in a specific queue, use `override_queue_concurrency`. For bigger changes, you can completely halt or restart processing across an entire job queue using `pause_resume_queue`. ### Advanced Automation and Scheduling Setting stuff up to run on its own is where this thing shines. You set recurring tasks with `create_schedule`, which accepts full cron syntax so you don't have to mess with a crontab file manually. If the job gets too popular, slowing it down might be smart. You can change how many jobs are allowed to run at the same time for any given queue by calling `override_queue_concurrency`. ## Tools ### batch_trigger_tasks Triggers many tasks simultaneously in one API call. ### cancel_run Stops a background job that is currently running. ### complete_waitpoint Signals the completion of an intermediate step in a workflow. ### create_batch Starts a new batch job container (Phase 1). ### create_env_var Adds or sets an environment variable for future jobs. ### create_schedule Sets up a recurring job using cron syntax. ### create_waitpoint_token Generates a temporary token needed to resume an interrupted process. ### delete_env_var Removes an existing environment variable setting. ### get_batch_results Retrieves the final output and results for a completed batch job. ### get_run Fetches all details, status, and logs for one specific job run ID. ### list_env_vars Shows a list of every environment variable currently configured. ### list_runs Lists multiple completed or failed job runs in an environment using filters. ### list_schedules Shows all currently active and defined scheduled jobs. ### override_queue_concurrency Changes how many jobs can run at the same time for a given queue. ### pause_resume_queue Stops or restarts job processing on an entire queue. ### replay_run Forces the system to run a specific, failed job attempt again. ### trigger_task Starts a single task immediately by its unique identifier. ### update_env_var Changes the value of an existing environment variable without deleting it. ### update_run_metadata Adds or changes descriptive data about a completed job run. ## Prompt Examples **Prompt:** ``` Trigger the 'image-processing' task with payload { 'url': 'https://example.com/img.jpg' }. ``` **Response:** ``` Task triggered successfully. Run ID: run_abc123. Status: QUEUED. You can check its progress using get_run. ``` **Prompt:** ``` List the last 5 failed runs for the 'sync-data' task. ``` **Response:** ``` I've found 5 failed runs for 'sync-data'. The most recent failure (ID: run_xyz789) occurred at 10:30 AM with error: 'Connection Timeout'. Would you like to replay it? ``` **Prompt:** ``` Create a daily schedule for the 'cleanup-logs' task at midnight. ``` **Response:** ``` Schedule created for 'cleanup-logs' with cron '0 0 * * *'. Deduplication key: 'daily-cleanup-logs'. The task will now run automatically every day at midnight UTC. ``` ## Capabilities ### Initiate Tasks (Single and Batch) You send a command to trigger one or more background jobs by calling tools like `trigger_task` or `batch_trigger_tasks`. ### Monitor Job Status and History Use `get_run` or `list_runs` to retrieve detailed status, payloads, and output logs for specific job executions. ### Automate Scheduling Set up recurring tasks using cron syntax via `create_schedule`, which automatically manages the task lifecycle. ### Manage Execution State Control active jobs by canceling them (`cancel_run`), replaying failures (`replay_run`), or updating their metadata. ### Govern Environment Variables Create, read, update, and delete environment variables using tools like `create_env_var` to ensure tasks run with the right configuration. ## Use Cases ### Debugging a data sync failure The ML Ops Engineer sees the nightly user profile sync failed. Instead of jumping into a dashboard, they ask their agent: 'What happened with the last run for `sync-data`?'. The agent calls `list_runs`, finds the ID, and uses `get_run` to report that the failure was due to an invalid key format in the payload. They then use `replay_run` after updating the necessary environment variables. ### Setting up a daily cleanup job The Backend Engineer needs old log files deleted every midnight, but doesn't want to mess with crontab. They ask their agent: 'Schedule a task to delete logs daily at midnight.' The agent uses `create_schedule` and returns the necessary cron key, automating the setup instantly. ### Validating bulk API writes The Product Manager needs to test writing 500 new records. They ask their agent: 'Trigger a batch task for these 500 IDs.' The agent uses `batch_trigger_tasks`, and the PM monitors progress using `get_batch_results` until all are confirmed successful. ### Handling queue overload The DevOps team notices that peak traffic is causing job failures. They tell their agent: 'Slow down the image processing queue.' The agent calls `pause_resume_queue` to halt jobs, giving the underlying service time to catch up. ## Benefits - Fixing failed data pipelines is instant. Instead of digging through logs, you tell your agent to `list_runs` or use `get_run` to pull the exact payload and error message for a specific run ID. - Automate recurring tasks with `create_schedule`. You define cron syntax in natural language, so you don't have to remember if it's '0 0 * * *' or something else. The system handles the boilerplate. - Test massive data jobs instantly using `batch_trigger_tasks`. Kick off a thousand records processing job with one prompt instead of writing complex looping code. - Control your infrastructure state directly. Use `create_env_var` to set up credentials for testing, and then use `delete_env_var` when the test is done. It keeps your environment clean. - Respond to failures immediately. If a job fails, you can tell your agent to `replay_run`, forcing it to re-execute that specific run without manual intervention. ## How It Works The bottom line is this: you manage your entire asynchronous job lifecycle—from scheduling to debugging—by talking to your AI agent instead of hitting multiple web dashboards. 1. First, subscribe to this server on Vinkius and provide your Trigger.dev Secret Key. 2. Next, tell your AI agent what job needs running (e.g., 'Trigger the nightly data sync task'). 3. The agent translates that into specific tool calls (like `trigger_task` or `create_schedule`), runs them against the server, and returns the status ID. ## Frequently Asked Questions **How do I check if a background job finished successfully using get_run?** You use `get_run` to pull all details for the specific run ID. You'll look at the 'status' field in the payload; it should read 'COMPLETED' or similar successful state. **Can I run a task multiple times if it failed? Which tool do I use?** Yes, you can force a retry using `replay_run`. This sends the exact same job parameters back into the queue, ignoring the initial failure. **I need to trigger 100 tasks at once. Should I use trigger_task or batch_trigger_tasks?** Use `batch_trigger_tasks`. It's designed to send multiple job IDs or payloads in one single request, which is much more efficient than calling the individual `trigger_task` 100 times. **How do I make sure my jobs use the correct API key?** Before triggering anything, you should check or set your credentials using `list_env_vars`, and if necessary, call `create_env_var` to ensure the right variable is active for that job run. **How do I see what scheduled jobs are set up to run automatically using list_schedules?** You use `list_schedules` to view all existing cron-based triggers. This tool shows the schedule's unique key, its next run time, and whether it is active or paused. **What if I need to adjust the resources available for my background tasks? Can I use override_queue_concurrency?** `override_queue_concurrency` lets you control how many jobs run at once. If your system is overloaded, lower this number; if it's underutilized, raise it. **How can I find specific failed runs or filter a large volume of job history using list_runs?** `list_runs` allows advanced filtering. You can narrow down results by date range, status (like 'failed'), or even by the task ID to pinpoint exactly what went wrong. **I need to ensure my tasks use the right configuration values; how do I manage environment variables with list_env_vars?** Use `list_env_vars` to check all currently defined environment variables for your project. You then use other tools like `create_env_var` or `update_env_var` when changes are needed. **Can I trigger multiple background tasks at once?** Yes! You can use the `batch_trigger_tasks` tool to trigger up to 1,000 tasks in a single batch request, which is highly efficient for high-volume workflows. **How do I check the output or error of a specific job run?** Use the `get_run` tool with the specific Run ID. It will return the full status, payload, output, and any attempt details or error logs associated with that run. **Can I schedule a task to run automatically using a cron expression?** Absolutely. Use the `create_schedule` tool to define a task identifier, a cron expression (e.g., '0 0 * * *'), and a deduplication key to automate recurring background jobs.