Skip to main content

Trigger.dev

Trigger.dev is an open-source platform for running background tasks and AI agents written in TypeScript. The Willow connector calls the Trigger.dev management API (https://api.trigger.dev by default), so an AI assistant can trigger and replay runs, read traces and errors, manage schedules, queues, deployments, waitpoint tokens, and environment variables, and query run data with TRQL.

Trigger.dev appears twice in the catalog, and the two entries do different things:

  • Trigger.dev with a By Willow badge — this page. A connector that calls the management API with an environment API key.
  • Trigger.dev with an Official badge — the official MCP server, Trigger.dev's own trigger.dev mcp server, run by Willow in read-only mode and connected with a personal access token.

Which one do you want​

If you needUse
An agent to change things: trigger, replay or cancel runs, manage schedules, queues, deployments or environment variablesBy Willow connector
A shared identity scoped to a single environment, with an access preset you chooseBy Willow connector
One connection that reaches every project and environment your account can see, acting as youOfficial server
Runs, traces, deployments and TRQL queries, read onlyEither

Running both is fine. The reads overlap, and each covers something the other cannot.

Authentication​

Trigger.dev supports one method for this connector.

API key​

Willow sends a Trigger.dev environment API key as Authorization: Bearer <key>. Keys look like tr_dev_sk_… or tr_prod_sk_….

A key belongs to one project and one environment (Development, Staging, Preview, or Production). Everything the tools list or change is in that environment, so add one connection per environment you want to reach. Trigger.dev has no OAuth flow for this API.

Create the key:

  1. In the Trigger.dev dashboard, select the project and environment, then open API keys.
  2. Click New API key and enter a descriptive name (for example, Willow). Optionally set an expiration date.
  3. Choose the narrowest access preset that covers the tools you want to use (see Access presets).
  4. Copy the key. Trigger.dev shows the full value only once.

Creating a key needs permission to manage API keys for that environment. Your dashboard disables the button when your role doesn't have it.

Access presets​

The preset decides which tools work. The free and hobby plans only offer No restrictions. The other presets need the Pro or Enterprise plan. Self-hosted installs also only offer No restrictions.

PresetWhat it allows
ObserverRead runs, tasks, batches, logs, traces, queues, errors, and webhooks.
OperatorObserve and operate on runs, queues, errors, and webhooks, and trigger tasks.
Task operatorTrigger and inspect or operate on the runs of all tasks, or of up to 10 selected tasks.
Trigger onlyTrigger runs and batches for all tasks, or up to 10 selected tasks.
Waitpoints onlyCreate, list, and retrieve waitpoint tokens.
Deploy onlyDeploy versions, sync environment variables, and manage Preview branches.
Variables onlyRead and write environment variables.
No restrictionsFull access to the environment.

Self-hosted API URL​

If you run Trigger.dev yourself, enter your instance's API URL in the API URL field (for example, https://trigger.example.com). Leave it empty for Trigger.dev Cloud, which uses https://api.trigger.dev.

Configure in Willow​

  1. In Willow, go to MCP Servers → + Add MCP server.
  2. Find the Trigger.dev card with the By Willow badge and click + Use.
  3. Under Authentication, select API Key and paste the environment API key.
  4. Self-hosted only: enter your API URL.
  5. Click Save Changes.
  6. To check the connection, run List Runs with no arguments. It returns the runs from the last 7 days in the key's environment.

Available Tools​

The Trigger.dev connector provides 47 tools.

Runs (10 tools)​

  • List Runs — filter by status, task, tag, version, schedule, error group, and time window; cursor pagination
  • Get Run — status, payload, output, tags, metadata, and related runs
  • Get Run Result — final output or error of a finished run
  • Get Run Trace — the span tree of a run, with messages, durations, errors, and events
  • Get Run Events — flat list of span events and log lines
  • Cancel Run — cancel a run that is in progress
  • Replay Run — start a new run from an existing one, optionally with a new payload or options
  • Reschedule Run — change the delay of a DELAYED run
  • Add Run Tags — add up to 10 tags to a run
  • Update Run Metadata — replace a run's metadata

Tasks and batches (4 tools)​

  • Trigger Task — start a run of a deployed task with a payload and options (delay, TTL, tags, idempotency key, concurrency key, machine)
  • Batch Trigger Tasks — start up to 1,000 runs in one call
  • Get Batch — batch status, run ids, and success and failure counts
  • Get Batch Results — results of the batch's finished runs

Schedules (7 tools)​

  • List Schedules — cron expression, timezone, next run, and active flag
  • Get Schedule
  • Create Schedule — create an imperative cron schedule for a task
  • Update Schedule
  • Delete Schedule
  • Activate Schedule
  • Deactivate Schedule

Update, delete, activate, and deactivate only work on imperative schedules, the ones created in the dashboard or with schedules.create(). Declarative schedules defined in code can't be changed here.

Deployments (4 tools)​

  • List Deployments — filter by status and time window
  • Get Deployment — status, version, image, any error, and the tasks in its worker
  • Get Latest Deployment
  • Promote Deployment — make a previously deployed version the current one

Errors (5 tools)​

  • List Errors — error groups with counts and first and last seen
  • Get Error — one error group and the worker versions it affected
  • Resolve Error
  • Ignore Error — for a duration, until a threshold is exceeded, or indefinitely
  • Unresolve Error

Queues (5 tools)​

  • List Queues — running and queued counts, paused state, and concurrency limits
  • Get Queue — by id, or by name and type
  • Pause or Resume Queue
  • Override Queue Concurrency
  • Reset Queue Concurrency — back to the limit defined in code

Query and dashboards (3 tools)​

  • Execute Query — run a TRQL query over runs, metrics, and LLM usage
  • Get Query Schema — the tables and columns TRQL can use
  • List Dashboards — built-in and custom dashboards with their widgets

Waitpoint tokens (4 tools)​

  • Create Waitpoint Token
  • List Waitpoint Tokens
  • Get Waitpoint Token
  • Complete Waitpoint Token — unblock the run waiting on the token, with optional data

Environment variables (5 tools)​

  • List Environment Variables
  • Get Environment Variable
  • Create Environment Variable
  • Update Environment Variable
  • Delete Environment Variable

These tools take the project ref (starts with proj_, shown in the project settings) and the environment (dev, staging, or prod). They return and change real secret values, so consider whether you want them enabled for everyone who uses the connection.

Troubleshooting​

401 Unauthorized on every call​

Cause: The key is missing, mistyped, expired, or revoked. An unauthenticated request returns No authorization header provided.

Solution: Create a new key on the environment's API keys page and paste it again. Check the key's expiration date.

403 Forbidden on some tools​

Cause: The key's access preset probably doesn't cover that operation, for example an Observer key calling Trigger Task, or a task-restricted key calling a task it wasn't given.

Solution: Create a key with a wider preset, or add the task to the key. A batch succeeds only if the key can access every task in it.

Runs or schedules from another environment are missing​

Cause: Each key reads one environment. A Development key can't see Production runs.

Solution: Add a second connection with the key for the other environment.

Get Run Result returns 404​

Cause: The run doesn't exist, or hasn't finished yet.

Solution: Use Get Run to check the status, and call Get Run Result once it is COMPLETED or FAILED.

List Runs returns nothing for older runs​

Cause: Without a created-at filter, Trigger.dev returns only runs from the last 7 days.

Solution: Pass period, or created_from and created_to.

Update or delete on a schedule fails​

Cause: The schedule is declarative, defined in your code, rather than imperative.

Solution: Change it in code and deploy. Use Deactivate Schedule only on imperative schedules.

Additional Resources​

On this page