- Agents
- Workflows
- Tables (local and remote)
- Integrations (HTTP, gRPC, SQL)
- Scripts (Python, docker run)
- Cases (local and remote)
Setup
If you are self-hosted, replacehttps://platform.tracecat.com with your
PUBLIC_APP_URL (e.g. http://localhost or https://tracecat.example.com).
Authentication uses a built-in OIDC provider—your agent is redirected to sign in
through the browser on first connection. If you belong to more than one
organization, Tracecat asks which organizations the connection can access, and
one connection then works across all of them. For clients or environments that cannot
complete a browser sign-in, authenticate with a
personal access token (PAT) instead.
- Claude Code
- OpenAI Codex
- GitHub Copilot
- Cursor
Sign in with OAuth:Or authenticate with a personal access token (PAT).
Set
TRACECAT_MCP_PAT in your environment and reference it with single
quotes so the variable (not the token) is written to the saved config:Personal access tokens
OAuth is the default. For clients or environments that cannot complete a browser sign-in (CI, headless runners, shared dev containers), authenticate with a workspace-scoped personal access token (PAT) instead. PATs work the same on self-hosted and Tracecat Cloud.- In your workspace, go to Settings → MCP and create a token. Set a name and expiration.
- Copy the token when it is shown. It is only displayed once and cannot be retrieved again.
- Pass it as a bearer header from your MCP client — see the PAT option in each Setup tab above for Claude Code, Codex, Copilot, and Cursor.
Treat the PAT like a secret. It grants MCP access scoped to the workspace it
was created in. Always send it in the
Authorization header—never in the URL
or a query string, where it leaks into server, proxy, and browser logs. Keep it
out of command output and application logs, and supply it through an environment
variable or secrets vault rather than hardcoding it in a config file. Revoke it
from Settings → MCP if it is exposed, and prefer short expirations.Starter prompts
Recreate automation from blog post
Audit and improve existing workflows
Build alert triage automation
Automate phishing email response
MCP tools
List all workspaces accessible to the authenticated user.Returns paginated workspace summaries including workspace id/name and the owning org_id/org_slug. Multi-org users may receive workspaces from more than one organization in a single response.
Configure which file extensions and MIME types case attachments may use.A list replaces the workspace’s current allowlist; it does not append. To add or remove one entry, call this tool without arguments first, edit the returned effective list, and pass the full list back. An empty list clears the workspace override so the system defaults apply again. Omitted arguments are left unchanged, and calling with no arguments only reads the current settings. An upload must match both an allowed extension and an allowed MIME type, so update both lists together when adding a file type. Changing settings requires the
workspace:update scope.List the actions in a draft workflow as a compact index-and-ref table.Use this instead of
get_workflow when you only need to know which actions exist, their order, their depends_on wiring, or the current array index of a ref for edit_workflow. It returns one small row per action and no args, so it stays cheap on large workflows. Follow up with get_workflow_action to read one action in full, or get_workflow when you need the whole draft_document.Get a draft workflow’s control flow as a compact Mermaid flowchart.Call this before adding or editing any
run_if, depends_on, or join_strategy. Each node shows the action ref, action type, for_each, join: any, and its run_if; error-path edges are dotted. No args are returned.Use gated_by to see which upstream conditions already guard an action: a skipped ancestor skips everything below it on the success path, so do not restate those conditions in a downstream run_if. join: any means any: it runs once one parent succeeds, even if another parent was skipped, so its gated_by keeps only conditions on every path into it.Get one action from a draft workflow by its
ref.Use this instead of get_workflow when you need the full definition of a single action (its args, run_if, for_each, retry policy, and so on) without loading the whole draft_document. Pair it with list_workflow_actions to discover refs. Edit the action afterwards with edit_workflow using /definition/actions/@<ref>/... paths.Edit a draft workflow using RFC 6902 JSON Patch.Prefer this tool over
update_workflow for focused edits to an existing workflow. If the latest draft_document and draft_revision are already in the context window, reuse them and build the smallest patch that changes the intended fields. Call get_workflow only when the latest draft is missing, stale, or a revision conflict says the draft changed.Patch paths are rooted at draft_document, so action edits use /definition/actions/..., not /actions/....Address actions by ref, not index: /definition/actions/@<ref> (with any suffix, e.g. /definition/actions/@build_alert/args/url) and /layout/actions/@<ref> resolve to the action’s current index when each op runs, so you never need to test an index first or track how earlier ops shifted the array. add to /definition/actions/@<ref> appends a new action when the ref does not exist yet (the value’s ref must match); remove on /definition/actions/@<ref> deletes that action. An unknown ref fails the whole patch and names the known refs. Numeric paths (/definition/actions/N/...) still work with RFC 6902 array rules (/- appends, indexes shift after array edits), but the server re-sorts actions by ref on save, so prefer @<ref>.Update workflow metadata and optional inline YAML.This tool does not accept
patch_ops. Use edit_workflow for RFC 6902 draft patches with a base_revision.Rename a workflow folder by absolute path.The folder keeps its position; its path and every descendant path change.
Move a workflow folder under a new parent path.The folder’s subfolders and workflows move with it.
Move workflows into or out of a folder.This tool is best-effort and non-atomic. If one workflow fails to move, the remaining workflow moves still proceed.
Search or browse available actions and return compact context metadata.Supports three usage modes:
-> Search: provide a literal substring
query to search by name/description across all namespaces; this is not a multi-word keyword search. Example: list_actions(workspace_id, query=“message”)
-> Browse by namespace: provide namespace without query to list all actions in a namespace. Example: list_actions(workspace_id, namespace=“core”)
-> Browse all: omit both to list all available actions.Common namespaces: core, tools, ai. Exact namespace/name matches appear before prefix and description matches. A missing first-page match does not mean the action is absent: continue with next_cursor while has_more is true.Sync the organization’s custom action registry from its remote git repository.Pulls the latest code from the custom registry repo registered in the caller’s organization, builds a versioned tarball, and makes the synced actions available to agents and workflows. Use this after pushing changes to the custom integrations repo, or to roll forward/back to a specific commit. Existing published workflows must be republished to pick up newly synced action versions.
Get full schema and configuration context for a single action.Use this after discovering an action via
list_actions to get the complete parameter schema needed to write the args: block in a workflow definition.Example action names: “core.http_request”, “core.script.run_python”, “core.transform.reshape”.For grouped counts and metrics in workflows, use core.cases.aggregate_cases for cases or core.table.aggregate_rows for table rows. Pass either action name to this tool to get its input schema.Get compact workflow authoring context for selected actions.Returns everything needed to write a workflow definition: action schemas, available secrets, and workspace variables. Use this before calling
create_workflow or update_workflow.Two input modes (provide one or neither):
-> By name: pass actions with an action_names list.
-> By search: pass query to search for actions by name/descriptionValidate a workflow’s draft state.Checks that the workflow DSL is structurally sound and that arguments are valid.
Validate a template action YAML file.Validates YAML parsing, template schema correctness, step action references, argument schemas, and expression references.
Publish (commit) a workflow, creating a new versioned definition.This validates the workflow, freezes registry dependencies, and creates a new workflow definition version.
Run a workflow from its draft state or a published definition.By default runs the current draft (unpublished edits) so changes can be tested before publishing. Draft runs reuse the result of every locked action (see
lock_workflow_action) instead of running it. Set use_draft=False to run a published version instead; published runs ignore locks.Lock a draft action to a past run’s result, or unlock it.While locked, every draft run (
run_workflow with use_draft=True) reuses the action’s result from that run instead of executing it, which lets you debug downstream actions against a fixed input. Published runs ignore locks. Find a lockable run with list_workflow_action_runs.List recent executions for a workflow.Use this to see run history, check which runs succeeded or failed, and find execution IDs for deeper inspection with
get_workflow_execution.Rerun a past execution against the draft or a published version.The new run reuses the past run’s trigger inputs. Each action that succeeded in the past run and exists in the target with the same ref and action type reuses its stored result instead of running. Everything else runs. Actions inside scatter or loop scopes, and control flow actions, always run.Call with
dry_run=true first to see the match plan. Each entry in plan.actions has a status: fixed (result reused), excluded (reusable but not in fixed_action_refs), runs (no reusable result), not_in_target (the target has no action with this ref), or action_changed (the target action uses a different action type). plan.unmatched_refs lists source results the target cannot use, and plan.inputs_error is set when the past inputs fail the target’s input schema.Get status and details of a specific workflow execution.Returns execution metadata (status, timing) and a compact event timeline showing each action’s status, timing, and any errors. Use this to debug failed runs or check the progress of running workflows.Each event’s
result is inlined only when its JSON is short; longer results appear as a cut-off result_truncated preview. To read one action’s complete result at any size, call get_execution_action_result.Request graceful cancellation of a workflow execution.Sends a cancellation request so the run can clean up before it closes with status CANCELED. It may take a moment to stop. Cancelling a run that has already finished does nothing. Call
get_workflow_execution afterwards to confirm the final status.Get the full stored result of one action in a workflow execution.Use this when
get_workflow_execution shows result_truncated for an action, or when the result was offloaded to blob storage, and you need the whole value (a findings list, a classification summary, an API payload). The result is returned as JSON text in byte windows: read total_bytes, and if truncated is true call again with offset=next_offset until next_offset is null. Concatenate the result strings in order to rebuild the JSON.Update an existing case trigger for a workflow.This tool replaces the whole trigger: every call sends
status, event_types and tag_filters, so pass all three. Omitting event_types or tag_filters clears them, and omitting status fails the write outright because the column is non-null. Call get_case_trigger first and send its current values back, changing only what you mean to change. Patching /case_trigger through edit_workflow is partial, unlike this tool.Valid event_types values: case_created, case_updated, case_closed, case_reopened, case_viewed, priority_changed, severity_changed, status_changed, fields_changed, assignee_changed, attachment_created, attachment_deleted, tag_added, tag_removed, payload_changed, task_created, task_deleted, task_status_changed, task_priority_changed, task_workflow_changed, task_assignee_changed, dropdown_value_changed, table_row_linked, table_row_unlinked, comment_created, comment_updated, comment_deleted, comment_reply_created, comment_reply_updated, comment_reply_deleted, parent_changed, sub_cases_added, sub_cases_removed.List the forms of a workspace, newest first.A form turns a workflow’s input schema into a page people fill in. Submitting it runs the workflow. Callers who cannot edit forms only see online forms.
Get a form: its status, its config and the issues the config has.
issues lists what does not resolve against the workflow’s published input schema (its draft inputs before the first publish), each with a loc path into the config. A form with an error-severity issue cannot be filled in until it is fixed. Find form IDs with list_forms.Update the form of a workflow, creating it if the workflow has none.The workflow’s input schema (
entrypoint.expects) supplies each field’s name, type, default and whether it is required. config only controls presentation. Inputs left out of layout are appended in schema order with their default widget. A required input with no default widget, such as dict or list[dict], needs a user or file widget or an autofill. Read the “Form Trigger” section of tracecat://platform/dsl-reference for the layout entries, widgets and rules.List workflow tag definitions in a workspace.Returns a JSON array of tag objects with
id, name, ref, and color.List tags attached to a workflow.Returns a JSON array of tag objects with
id, name, ref, and color.List case views you can see, to run with search_cases(view_id=…).Saved views are personal (only you) or shared with the workspace and come back one page at a time in
saved. The read-only built-in view, assigned_to_me, is defined by Tracecat and comes back separately in builtins. With pinned, both lists hold only the views you pinned.Group cases as sub-cases of a top-level parent case.Sub-cases are one level deep: the parent must be a top-level case, and a case that has its own sub-cases cannot be grouped. Cases already under another parent are moved. Requires the case add-ons entitlement.
Remove sub-cases from their parent case, returning them to the top level. Cases without a parent are left unchanged. Requires the case add-ons entitlement.
Delete a comment from a case.Workspace admins (
case:delete) can delete any comment, including other users’ comments. Deletion is a soft delete: the comment is hidden from the thread but kept in the database and recorded as a case event.Run the workflow associated with a case task.Fetches the task’s
workflow_id and default_trigger_values, merges them with case_id and task_id context (plus any caller-supplied overrides), then executes the latest published version of the workflow.List activity events for a case. Events are system-generated audit entries that track every change to a case — status changes, priority changes, assignee changes, comments, tasks, tags, field changes, etc.
List case tag definitions in a workspace.Returns a JSON array of tag objects with
id, name, ref, and color.List case field definitions in a workspace.Returns a JSON array of field objects with
id, display_name, type, description, nullable, default, reserved, options, and optional kind.Create a case field definition.Supports optional create-only
kind: LONG_TEXT requires type="TEXT" and URL requires type="JSONB".List case dropdown definitions in a workspace. Requires the case add-ons entitlement.Returns a paginated JSON array of dropdown objects with
id, name, ref, icon_name, is_ordered, required_on_closure, position, and embedded options.Create a case dropdown definition with optional initial options. Requires the case add-ons entitlement.
Update a case dropdown definition. Only provided fields are changed. Requires the case add-ons entitlement.
Delete a case dropdown definition along with all its options and per-case values. Requires the case add-ons entitlement.
Update an option within a case dropdown definition. Only provided fields are changed. Requires the case add-ons entitlement.
Set or clear a dropdown value on a case. Provide exactly one of
definition_id or definition_ref, and at most one of option_id or option_ref; omit both option arguments to clear the value. Requires the case add-ons entitlement.Rename a table folder by absolute path.The folder keeps its position; its path and every descendant path change.
Move tables into or out of a folder.This tool is best-effort and non-atomic. If one table fails to move, the remaining table moves still proceed.
Add a column to an existing table. Migrating a table is never needed to add a field. This alters the schema every workflow and view reads, so tell the user which table and column you are about to change and get their confirmation before calling this tool.
Create a workspace variable.Variable values are not encrypted. Do not put credentials or other sensitive values in variables; use workspace secrets instead.
Update a workspace variable.Omitted fields are left unchanged.
values replaces the full key set, so call get_variable first and send every key you want to keep.Delete a workspace variable.Workflows that still reference
${{ VARS.<name>... }} will fail to resolve it after deletion.Create an agent preset in the selected workspace.Use
skills to attach published skills. Each binding contains skill_id only; the preset always runs each skill’s latest published version, so there is no version to pin.Attach tools via actions, mcp_integration_ids, or a skill’s metadata.tools.Use subagents to attach other presets as subagents. Each ref contains preset (the child preset slug) and optional name (runtime alias), description, and max_turns. Always omit preset_version so the subagent follows the child preset’s latest version; set it only when the user explicitly asks to pin a specific version. A child preset cannot have its own subagents, and its tools can require manual approval only when an enabled agent backend supports subagent approvals.Presets are not available in chat by default. Set use_in_chat=true only when the user explicitly asks to enable the preset in chat.Update an existing agent preset in the selected workspace.Use
skills to replace attached published skills. Each binding contains skill_id. Omit skills to leave bindings unchanged, or pass an empty list to detach all skills. Attached skills always run at their latest published version, so do not call this after publish_skill just to refresh a skill version; only pass skills when adding or removing a skill.Attach tools via actions, mcp_integration_ids, or a skill’s metadata.tools.Use subagents to replace attached preset-backed subagents. Each ref contains preset (the child preset slug) and optional name (runtime alias), description, and max_turns. Always omit preset_version so the subagent follows the child preset’s latest version; set it only when the user explicitly asks to pin a specific version. When re-sending existing subagents, drop any preset_version the user did not ask for. Omit subagents to leave them unchanged, or pass an empty list to detach all subagents. A child preset cannot have its own subagents, and its tools can require manual approval only when an enabled agent backend supports subagent approvals.Set clear_output_type=true to remove an existing output_type (agent returns plain text). Omitting output_type leaves it unchanged.Set use_in_chat only when the user explicitly asks to enable or disable the preset in chat. Omit it to leave chat availability unchanged.Rename an agent folder by absolute path.The folder keeps its position; its path and every descendant path change.
Move agent presets into or out of a folder by preset slug.This tool is best-effort and non-atomic. If one preset fails to move, the remaining preset moves still proceed.
Rename a skill folder by absolute path.The folder keeps its position; its path and every descendant path change.
Move skills into or out of a folder by skill slug.This tool is best-effort and non-atomic. If one skill fails to move, the remaining skill moves still proceed.
List workspace skills with IDs, names, and current published versions.Use this before updating, publishing, or attaching skills to agent presets.
Get skill details and the mutable draft manifest, or read one draft file.Without
path, return the draft manifest: paths, SHA-256 digests, sizes, draft_revision, is_publishable, and validation_errors; it never returns file contents. Call this before updating an existing skill to reconcile after a draft_revision_conflict and to see what a complete-tree replacement would delete.With path, read that one file from the draft. Small UTF-8 text files are returned inline. Other files return a short-lived download URL whose bytes must be fetched to disk with a plain HTTP GET; never inline downloaded bytes into context.Prepare direct HTTP downloads of the complete mutable skill draft.Pass the response to the local helper, which streams each file’s bytes to disk and verifies its SHA-256 digest. Never fetch these URLs into model context. Use
get_skill without path when only file digests are needed, and use get_skill with path to read one small text file inline.Prepare direct HTTP uploads for a complete local skill directory.This is the preferred local-directory upload path. Pass file paths, SHA-256 digests, sizes, and content types only; never inline file contents or base64. Omit
skill_id and provide name to create a skill, or provide skill_id and omit name/description to replace an existing draft.Upload every file to its short-lived URL with the returned method and headers, then call complete_skill_upload with the returned skill_id, base_revision, paths, and upload IDs.Declare the skill’s tools in its SKILL.md frontmatter metadata.tools.Attach staged uploads and replace a skill draft with the local file set.Call this only after every URL returned by
prepare_skill_upload has received its raw file bytes. Files absent from this complete set are removed. base_revision prevents overwriting a concurrent draft edit. This does not publish the draft.Publish a skill draft into an immutable skill version.Only published skills can be attached to agent presets. Presets that already have this skill attached pick up the new version automatically on their next run; no
update_agent_preset call is needed afterwards.