Tracecat MCP - Tracecat Docs

Tracecat works best with agentic coding tools (Claude Code, Cursor, Codex, OpenCode). Agents connected to Tracecat MCP gain the ability to build and orchestrate core Tracecat resources:

Agents
Workflows
Tables (local and remote)
Integrations (HTTP, gRPC, SQL)
Scripts (Python, docker run)
Cases (local and remote)

Tracecat MCP turns any coding agent into a security automation architect and engineer.

Setup

If you are self-hosted, replace https://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. 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

claude mcp add -t http tracecat https://platform.tracecat.com/mcp
claude
/mcp

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:

claude mcp add --transport http tracecat https://platform.tracecat.com/mcp \
  --header 'Authorization: Bearer ${TRACECAT_MCP_PAT}'

codex mcp add tracecat --url https://platform.tracecat.com/mcp
codex mcp login tracecat

Or authenticate with a personal access token (PAT). Set TRACECAT_MCP_PAT in your environment, then reference it by name:

codex mcp add tracecat --url https://platform.tracecat.com/mcp \
  --bearer-token-env-var TRACECAT_MCP_PAT

copilot
/mcp add
# Server Name: tracecat
# Server Type: HTTP
# URL: https://platform.tracecat.com/mcp
# Tools: *

Follow GitHub Copilot MCP setup for the latest CLI prompts.Or add this server to ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "tracecat": {
      "type": "http",
      "url": "https://platform.tracecat.com/mcp",
      "tools": ["*"]
    }
  }
}

To use a personal access token (PAT) instead of OAuth, add an Authorization header (${TRACECAT_MCP_PAT} is read from your environment):

"headers": {
  "Authorization": "Bearer ${TRACECAT_MCP_PAT}"
}

On Tracecat Cloud, click Add Tracecat to Cursor to add it in one click. Otherwise configure .cursor/mcp.json manually:

{
  "mcpServers": {
    "tracecat": {
      "url": "https://platform.tracecat.com/mcp"
    }
  }
}

To use a personal access token (PAT) instead of OAuth, add an Authorization header (Cursor resolves ${env:TRACECAT_MCP_PAT} from your environment):

"headers": {
  "Authorization": "Bearer ${env:TRACECAT_MCP_PAT}"
}

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_workspaces

tool

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.

create_workflow

tool

Create a new workflow in a workspace.

get_workflow

tool

Get metadata for a specific workflow.

edit_workflow

tool

Edit a draft workflow using RFC 6902 JSON Patch.

update_workflow

tool

Update workflow metadata and optional inline YAML.

list_workflows

tool

List workflows in a workspace.

list_workflow_tree

tool

List workflow folders and workflows under a path.

create_workflow_folder

tool

Create a workflow folder by absolute path.

rename_workflow_folder

tool

Rename a workflow folder by absolute path.

move_workflow_folder

tool

Move a workflow folder under a new parent path.

delete_workflow_folder

tool

Delete a workflow folder by absolute path.

move_workflows

tool

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.

list_actions

tool

Search or browse available actions and return compact context metadata.Supports three usage modes: -> Search: provide query to search by name/description across all namespaces. Example: list_actions(workspace_id, query=“send 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.

sync_custom_registry

tool

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_action_context

tool

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”.

get_workflow_authoring_context

tool

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/description

validate_workflow

tool

Validate a workflow’s draft state.Checks that the workflow DSL is structurally sound and that arguments are valid.

prepare_template_file_upload

tool

Prepare a staged template YAML upload for remote /mcp clients.

validate_template_action

tool

Validate a template action YAML file.Validates YAML parsing, template schema correctness, step action references, argument schemas, and expression references.

publish_workflow

tool

Publish (commit) a workflow, creating a new versioned definition.This validates the workflow, freezes registry dependencies, and creates a new workflow definition version.

run_draft_workflow

tool

Run a workflow from its current draft state (without publishing).Optionally update the workflow’s title/description before running.

run_published_workflow

tool

Run the latest published version of a workflow.The workflow must have been published (committed) at least once.

list_workflow_executions

tool

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.

get_workflow_execution

tool

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.

get_webhook

tool

Get webhook configuration for a workflow.

update_webhook

tool

Update webhook configuration for a workflow.

get_case_trigger

tool

Get case trigger configuration for a workflow.

update_case_trigger

tool

Update an existing case trigger for a workflow.

list_workflow_tags

tool

List workflow tag definitions in a workspace.Returns a JSON array of tag objects with id, name, ref, and color.

create_workflow_tag

tool

Create a workflow tag definition.

update_workflow_tag

tool

Update a workflow tag definition.

delete_workflow_tag

tool

Delete a workflow tag definition.

List tags attached to a workflow.Returns a JSON array of tag objects with id, name, ref, and color.

add_workflow_tag

tool

Attach an existing workflow tag definition to a workflow.

remove_workflow_tag

tool

Remove a workflow tag association from a workflow.

list_cases

tool

List cases in a workspace with default sorting.

search_cases

tool

Search cases with filtering and sorting.

get_case

tool

Get a specific case with full details including fields, tags, and description.

create_case

tool

Create a new case.

update_case

tool

Update a case. Only provided fields are changed.

list_case_comments

tool

List all comments for a case.

list_case_comment_threads

tool

List comment threads for a case. Each thread contains the root comment and its replies.

create_case_comment

tool

Create a new comment on a case. Provide parent_id to reply to an existing comment.

update_case_comment

tool

Update an existing comment on a case.

delete_case_comment

tool

Delete a comment from a case.

list_case_tasks

tool

List all tasks for a case.

get_case_task

tool

Get a specific case task by ID.

create_case_task

tool

Create a new task on a case.

update_case_task

tool

Update a case task. Only provided fields are changed.

run_case_task

tool

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_case_events

tool

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_tags

tool

List case tag definitions in a workspace.Returns a JSON array of tag objects with id, name, ref, and color.

create_case_tag

tool

Create a case tag definition.

update_case_tag

tool

Update a case tag definition.

delete_case_tag

tool

Delete a case tag definition.

List tags attached to a case.Returns a JSON array of tag objects with id, name, ref, and color.

add_case_tag

tool

Attach a case tag to a case.

remove_case_tag

tool

Remove a case tag association from a case.

list_case_fields

tool

List case field definitions in a workspace.Returns a JSON array of field objects with id, type, description, nullable, default, reserved, options, and optional kind.

create_case_field

tool

Create a case field definition.Supports optional create-only kind: LONG_TEXT requires type="TEXT" and URL requires type="JSONB".

update_case_field

tool

Update a case field definition.

list_case_dropdowns

tool

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.

Add an option to a case dropdown definition. 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.

Delete an option from a case dropdown definition. 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.

list_tables

tool

List workspace tables.

create_table

tool

Create a table with optional columns.

get_table

tool

Get table definition and index metadata.

update_table

tool

Update table metadata.

insert_table_row

tool

Insert a table row.

insert_rows

tool

Insert multiple table rows.

update_table_row

tool

Update a table row.

update_rows

tool

Update multiple table rows with the same values.

search_table_rows

tool

Search rows in a table.

export_csv

tool

Export table data as a staged download URL.

create_column_index

tool

Create a unique index on a table column. Only one unique index per table is allowed.

drop_column_index

tool

Drop the unique index on a table column.

list_variables

tool

List workspace variables.

get_variable

tool

Get a workspace variable.

list_secrets_metadata

tool

List secret metadata without secret values.

get_secret_metadata

tool

Get secret metadata by name without secret values.

list_integrations

tool

List workspace integrations useful for workflow and preset authoring.

get_agent_preset_authoring_context

tool

Get models, integrations, output_type guidance, and other preset authoring context.

create_agent_preset

tool

Create an agent preset in the selected workspace.Use skills to attach published skill versions. Each binding requires skill_id and skill_version_id from list_skills and publish_skill.

update_agent_preset

tool

Update an existing agent preset in the selected workspace.Use skills to replace attached published skill-version bindings. Each binding requires skill_id and skill_version_id. Omit skills to leave bindings unchanged, or pass an empty list to detach all skills.

list_agent_tree

tool

List agent folders and presets under a path.

create_agent_folder

tool

Create an agent folder by absolute path.

rename_agent_folder

tool

Rename an agent folder by absolute path.

move_agent_folder

tool

Move an agent folder under a new parent path.

delete_agent_folder

tool

Delete an agent folder by absolute path.

move_agent_presets

tool

Move agent presets into or out of a folder by preset slug.

list_skills

tool

List workspace skills with IDs, names, and current published versions.Use this before updating, publishing, or attaching skills to agent presets.

upload_skill

tool

Upload a local skill directory into Tracecat as a workspace skill.This creates a new logical skill. Use update_skill when replacing an existing skill draft to avoid duplicate skill rows with the same name.Agents should read the local directory themselves, preserve relative paths, include the root SKILL.md file, and pass every file in files using content_base64.

update_skill

tool

Replace an existing skill draft with a local skill directory.This does not publish the draft. Call publish_skill after the update if the skill should be attachable to agent presets.

publish_skill

tool

Publish a skill draft into an immutable skill version.Only published skill versions can be attached to agent presets.

list_agent_presets

tool

List saved agent preset slugs and names.Use get_agent_preset for the full preset definition.

get_agent_preset

tool

Get the full configuration for a saved agent preset by slug.

run_agent_preset

tool

Run an agent preset with a prompt and return text or approval status.Creates an ephemeral session, triggers the agent workflow, and waits for the response. The agent has access to all tools configured on the preset.

​Setup

​Personal access tokens

​Starter prompts

​MCP tools

Setup

Personal access tokens

Starter prompts

MCP tools