@trigger.dev/sdk 0.0.0-python-preview-20250226140121 → 0.0.0-rc-4-8-0-20261021151928

package/docs/mcp-tools.mdx

@@ -0,0 +1,425 @@
+---
+title: "MCP Tools"
+sidebarTitle: "Tools"
+description: "Learn about how to use the tools available in the Trigger.dev MCP Server"
+---
+
+## Documentation and Search Tools
+
+### search_docs
+
+Search the Trigger.dev documentation for guides, examples, and API references.
+
+**Example usage:**
+- `"How do I create a scheduled task?"`
+- `"Show me webhook examples"`
+- `"What are the deployment options?"`
+
+## Project Management Tools
+
+### list_orgs
+
+List all organizations you have access to.
+
+**Example usage:**
+- `"What organizations do I have?"`
+- `"Show me my orgs"`
+
+### list_projects
+
+List all projects in your Trigger.dev account.
+
+**Example usage:**
+- `"What projects do I have?"`
+- `"List my Trigger.dev projects"`
+
+### create_project_in_org
+
+Create a new project in an organization.
+
+**Example usage:**
+- `"Create a new project called 'my-app'"`
+- `"Set up a new Trigger.dev project"`
+
+### initialize_project
+
+Initialize Trigger.dev in your project with automatic setup and configuration.
+
+**Example usage:**
+- `"Set up Trigger.dev in this project"`
+- `"Add Trigger.dev to my app"`
+
+## Task Management Tools
+
+### get_current_worker
+
+Get the current worker for a project, including the worker version, SDK version, and registered tasks with their payload schemas.
+
+**Example usage:**
+- `"What tasks are available?"`
+- `"Show me the tasks in dev"`
+
+### trigger_task
+
+Trigger a task to run with a specific payload. You can add a delay, set tags, configure retries, choose a machine size, pick a region, set a TTL, or use an idempotency key.
+
+**Example usage:**
+- `"Run the email-notification task"`
+- `"Trigger my-task with userId 123"`
+- `"Execute the sync task in production"`
+
+## Run Monitoring Tools
+
+### get_run_details
+
+Get detailed information about a specific task run, including logs and status. Enable debug mode to get the full trace with all logs and spans.
+
+**Example usage:**
+- `"Show me details for run run_abc123"`
+- `"Why did this run fail?"`
+
+### list_runs
+
+List runs for a project. Filter by status, task, tags, version, machine size, or time period.
+
+**Example usage:**
+- `"Show me recent runs"`
+- `"List failed runs from the last 7 days"`
+- `"What runs are currently executing?"`
+
+### wait_for_run_to_complete
+
+Wait for a specific run to finish and return the result.
+
+**Example usage:**
+- `"Wait for run run_abc123 to complete"`
+
+### cancel_run
+
+Cancel a running or queued run.
+
+**Example usage:**
+- `"Cancel run run_abc123"`
+- `"Stop that task"`
+
+### replay_run
+
+Replay a run as a new run of the same task, in the same environment. The new run reuses the original run's payload, metadata, tags, queue, concurrency key, and machine unless you override them. See [Replaying](/replaying) for how each option falls back.
+
+**Parameters:**
+- `runId` (required): The run to replay, starting with `run_`
+- `payload`, `metadata`, `tags` (optional): Replace the original run's values
+- `queue`, `concurrencyKey`, `machine`, `version`, `region`, `delay`, `ttl`, `idempotencyKey`, `maxAttempts`, `maxDuration`, `priority` (optional): Override the trigger options for the new run
+
+**Example usage:**
+- `"Replay run run_abc123"`
+- `"Replay that failed run with userId set to user_456"`
+- `"Replay run run_abc123 on a large-1x machine in 10 minutes"`
+
+## Deployment Tools
+
+### deploy
+
+Deploy your project to staging or production.
+
+**Example usage:**
+- `"Deploy to production"`
+- `"Deploy to staging"`
+
+### list_deploys
+
+List deployments for a project. Filter by status or time period.
+
+**Example usage:**
+- `"Show me recent deployments"`
+- `"What's deployed to production?"`
+
+### list_preview_branches
+
+List all preview branches in the project.
+
+**Example usage:**
+- `"What preview branches exist?"`
+- `"Show me preview deployments"`
+
+## Profile Tools
+
+### whoami
+
+Show the current authenticated user, active CLI profile, email, and API URL.
+
+**Example usage:**
+- `"Who am I logged in as?"`
+- `"What profile am I using?"`
+
+### list_profiles
+
+List all configured CLI profiles and which one is currently active.
+
+**Example usage:**
+- `"What profiles do I have?"`
+- `"Show me my Trigger.dev profiles"`
+
+### switch_profile
+
+Switch the active CLI profile for this MCP session. This changes which Trigger.dev account and API URL are used for all subsequent tool calls.
+
+**Example usage:**
+- `"Switch to my production profile"`
+- `"Use the staging profile"`
+
+## Query and Analytics Tools
+
+### get_query_schema
+
+Get the schema for TRQL queries, including all available tables, their columns, data types, descriptions, and allowed values. Call this before using the query tool to understand what data is available.
+
+**Example usage:**
+- `"What tables and columns can I query?"`
+- `"Show me the query schema"`
+
+### query
+
+Execute a TRQL query against your Trigger.dev data. TRQL is a SQL-style query language for analyzing runs, metrics, and LLM usage.
+
+**Example usage:**
+- `"How many runs failed in the last 7 days?"`
+- `"Show me the top 10 most expensive tasks"`
+- `"Query the average execution duration by task"`
+
+### list_dashboards
+
+List the built-in dashboards and your organization's custom dashboards, with their widgets.
+
+**Example usage:**
+- `"What dashboards are available?"`
+- `"Show me the dashboard widgets"`
+
+### run_dashboard_query
+
+Execute a single widget query from a built-in or custom dashboard. Use `list_dashboards` first to see available dashboards and widget IDs.
+
+**Example usage:**
+- `"Run the total runs widget from the overview dashboard"`
+- `"Show me the LLM cost over time from the AI dashboard"`
+
+### create_dashboard
+
+Create a custom dashboard, optionally with widgets. Each widget has a title, a TRQL query and a display: a table, a bar or line chart, a big number, or a section title. Queries are checked when the dashboard is saved.
+
+**Example usage:**
+- `"Make a dashboard for the email tasks with total runs, failures and runs per day"`
+- `"Create a dashboard that charts p95 duration by task"`
+
+### set_dashboard_widgets
+
+Replace every widget on a custom dashboard, and optionally rename it.
+
+**Example usage:**
+- `"Add a failed runs widget to the email dashboard"`
+- `"Change the runs per day chart to a line chart"`
+
+### get_report
+
+Render an interpreted [health report](/reports) — a deterministic verdict, not a raw panel — as text with sparklines. The `health` report answers whether work is flowing, whether the runs that start are healthy, and whether the telemetry is fresh, with a headline verdict and a suggested next action. Returns markdown by default, or ANSI when `color` is set. Read-only.
+
+**Example usage:**
+- `"Is my production project healthy?"`
+- `"Run the health report for the last 24 hours"`
+- `"Why are my runs backing up?"`
+
+## Dev Server Tools
+
+### start_dev_server
+
+Start the Trigger.dev dev server (`trigger dev`) in the background. Waits up to 30 seconds for the worker to be ready.
+
+**Example usage:**
+- `"Start the dev server"`
+- `"Run trigger dev"`
+
+### stop_dev_server
+
+Stop the running Trigger.dev dev server.
+
+**Example usage:**
+- `"Stop the dev server"`
+
+### dev_server_status
+
+Check the status of the dev server and view recent output. Shows whether it is stopped, starting, ready, or has errors.
+
+**Example usage:**
+- `"Is the dev server running?"`
+- `"Show me the dev server logs"`
+- `"Are there any build errors?"`
+
+<Callout type="warning">
+  The deploy and list_preview_branches tools are not available when the MCP server is running with the `--dev-only` flag. The `--readonly` flag hides deploy, trigger_task, cancel_run, replay_run, create_dashboard, and set_dashboard_widgets.
+</Callout>
+
+## Agent Chat Tools
+
+These tools let you have conversations with [chat agents](/ai-chat/overview) directly from your AI coding tool. See the [Agent MCP guide](/ai-chat/mcp) for a walkthrough.
+
+### list_agents
+
+List all chat agents registered in the current worker. Agents are tasks created with `chat.agent()` or `chat.customAgent()`.
+
+**Example usage:**
+- `"What agents are available?"`
+- `"List my chat agents"`
+
+### start_agent_chat
+
+Start a conversation with a chat agent. Returns a chat ID for use with `send_agent_message`. Optionally preloads the agent so it initializes before the first message.
+
+**Parameters:**
+- `agentId` (required) — The agent task slug (e.g., `"support-agent"`)
+- `chatId` (optional) — A custom conversation ID. Auto-generated if omitted
+- `clientData` (optional) — Client data to include with every message (e.g., `{ userId: "user_123" }`). Must match the agent's `clientDataSchema` if one is defined
+- `preload` (optional, default: `true`) — Whether to preload the agent before the first message
+
+**Example usage:**
+- `"Start a chat with the support agent"`
+- `"Talk to the pr-review agent with userId abc"`
+
+### send_agent_message
+
+Send a message to an active agent chat and get the full response back. The agent remembers full context from previous messages in the same chat.
+
+**Parameters:**
+- `chatId` (required) — The chat ID from `start_agent_chat`
+- `message` (required) — The message text to send
+
+**Example usage:**
+- `"Tell the agent to review the latest PR"`
+- `"Ask it what tools it has available"`
+
+### close_agent_chat
+
+Close an agent chat conversation. The agent exits its loop gracefully. Without this, the agent will close on its own when its idle timeout expires.
+
+**Parameters:**
+- `chatId` (required) — The chat ID to close
+
+**Example usage:**
+- `"Close the chat"`
+- `"End the conversation"`
+
+<Callout type="warning">
+  The `start_agent_chat`, `send_agent_message`, and `close_agent_chat` tools are write operations and are not available in readonly mode.
+</Callout>
+
+## Session Channel Tools
+
+Read and write a session's realtime streams: a named [side channel](/ai-chat/side-channels) or the reserved chat transcript pair. Use these to observe an agent's out-of-band output (a screencast, telemetry) or to send it control input.
+
+### read_session_channel
+
+Read records from a session's realtime stream. By default it returns the records that exist right now after an optional cursor and closes, so it is a point-in-time drain, not a live subscription. Set `timeoutInSeconds` to wait for the next record when none exist yet.
+
+**Parameters:**
+- `sessionId` (required): the session id (`session_*`) or the externalId it was created with
+- `channel` (optional): the named side channel to read. Omit to read the reserved chat transcript pair
+- `io` (optional, default: `out`): which side to read, `out` (producer feed) or `in` (client input)
+- `afterEventId` (optional): cursor. Only return records after this event id. Use the `nextCursor` from a prior read to page forward
+- `maxRecords` (optional, default: `100`): maximum records to return
+- `timeoutInSeconds` (optional): wait up to this many seconds for at least one record when none exist yet
+
+**Example usage:**
+- `"Read the latest frames on the screencast channel for this session"`
+- `"Wait for the next control message on the session's status channel"`
+
+### write_session_channel
+
+Append one record to a named side channel's `in` stream. Sends control input to a running agent (e.g. a pause command) without waking or triggering a run. The reserved transcript and a channel's `out` side are not writable here; `out` is producer-only.
+
+**Parameters:**
+- `sessionId` (required): the session id or externalId
+- `channel` (required): the named side channel to write to
+- `value` (required): the record to append. Pass an object for a structured record (e.g. `{ paused: true }`) or a string for a raw one
+
+**Example usage:**
+- `"Pause the screencast on this session"`
+- `"Send { paused: true } to the viewport channel"`
+
+<Callout type="warning">
+  `write_session_channel` is a write operation and is not available in readonly mode.
+</Callout>
+
+## Webhook Tools
+
+Set up and debug [hosted webhook endpoints](/webhooks/overview). Endpoint ids start with `wh_` and delivery ids with `whd_`; endpoint tools also accept an endpoint's declared id. The same operations are on the [Webhooks API](/management/webhooks/list-endpoints).
+
+### list_webhook_endpoints
+
+List the environment's webhook endpoints: each one's id, declared id, source, status, URL and whether its signing secret is set.
+
+**Example usage:**
+- `"Which webhook endpoints do I have in dev?"`
+
+### get_webhook_endpoint_details
+
+Get an endpoint's subscribers, with the filters that decide which events each accepts, and its setup prompt: the steps for registering the endpoint and its signing secret with the provider.
+
+**Parameters:**
+- `endpointId` (required): the endpoint's declared id (such as `payments`) or `wh_` id
+
+**Example usage:**
+- `"Connect my payments webhook to Stripe"`
+
+### list_webhook_deliveries
+
+List recent deliveries, newest first.
+
+**Parameters:**
+- `endpointId` (optional): only this endpoint's deliveries, by declared id or `wh_` id
+- `status` (optional): only these statuses, such as `["failed", "filtered"]`
+- `period` (optional, default: `7d`): how far back to look
+- `limit` (optional, default: `20`): how many to return, up to 100
+- `cursor` (optional): the cursor from a previous call, for the next page
+
+**Example usage:**
+- `"Did the Stripe checkout event arrive in the last hour?"`
+- `"Show me failed deliveries on the github endpoint"`
+
+### get_webhook_delivery
+
+Get one delivery: its status and error, each subscriber's result (the run or session it started, or why its filter skipped the event), how many waiting runs it resumed, and its event and headers.
+
+**Parameters:**
+- `deliveryId` (required): the delivery's `whd_` id
+
+**Example usage:**
+- `"Why didn't this webhook trigger my order task?"`
+
+### replay_webhook_delivery
+
+Replay a delivery from its stored event. Without `targetId` it goes to every subscriber again, with their filters checked again. With `targetId` it goes to that subscriber even if its filter skipped the event.
+
+**Parameters:**
+- `deliveryId` (required): the delivery's `whd_` id
+- `targetId` (optional): the subscriber id to replay to
+
+**Example usage:**
+- `"Replay that delivery to the refunds task"`
+
+### generate_webhook_secret
+
+Generate a new signing secret for an endpoint and return it once, for providers where you choose the secret (such as GitHub). It replaces any existing secret.
+
+**Parameters:**
+- `endpointId` (required): the endpoint's declared id (such as `payments`) or `wh_` id
+
+### set_webhook_secret
+
+Store a signing secret or public key the provider issued, such as Stripe's `whsec_` secret. It replaces any existing secret.
+
+**Parameters:**
+- `endpointId` (required): the endpoint's declared id (such as `payments`) or `wh_` id
+- `secret` (required): the secret or public key
+
+<Callout type="warning">
+  `replay_webhook_delivery`, `generate_webhook_secret` and `set_webhook_secret` are write operations and are not available in readonly mode.
+</Callout>