> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracecat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tracecat MCP

> Drive Tracecat from your own agent harness over MCP: build, edit, and run workflows and cases through Claude, Cursor, ChatGPT, or any MCP client.

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)](/automations/tracecat-mcp#personal-access-tokens) instead.

<Tabs sync={false}>
  <Tab title="Claude Code" icon="https://cdn.simpleicons.org/anthropic">
    Sign in with OAuth:

    ```bash theme={null}
    claude mcp add -t http tracecat https://platform.tracecat.com/mcp
    claude
    /mcp
    ```

    Or authenticate with a [personal access token (PAT)](/automations/tracecat-mcp#personal-access-tokens).
    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:

    ```bash theme={null}
    claude mcp add --transport http tracecat https://platform.tracecat.com/mcp \
      --header 'Authorization: Bearer ${TRACECAT_MCP_PAT}'
    ```
  </Tab>

  <Tab title="OpenAI Codex" icon="https://cdn.jsdelivr.net/npm/simple-icons@latest/icons/openai.svg">
    Sign in with OAuth:

    ```bash theme={null}
    codex mcp add tracecat --url https://platform.tracecat.com/mcp
    codex mcp login tracecat
    ```

    Or authenticate with a [personal access token (PAT)](/automations/tracecat-mcp#personal-access-tokens).
    Set `TRACECAT_MCP_PAT` in your environment, then reference it by name:

    ```bash theme={null}
    codex mcp add tracecat --url https://platform.tracecat.com/mcp \
      --bearer-token-env-var TRACECAT_MCP_PAT
    ```
  </Tab>

  <Tab title="GitHub Copilot" icon="https://cdn.simpleicons.org/github">
    ```bash theme={null}
    copilot
    /mcp add
    # Server Name: tracecat
    # Server Type: HTTP
    # URL: https://platform.tracecat.com/mcp
    # Tools: *
    ```

    Follow [GitHub Copilot MCP setup](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers) for the latest CLI prompts.

    Or add this server to `~/.copilot/mcp-config.json`:

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

    To use a [personal access token (PAT)](/automations/tracecat-mcp#personal-access-tokens) instead of
    OAuth, add an `Authorization` header (`${TRACECAT_MCP_PAT}` is read from your
    environment):

    ```json theme={null}
    "headers": {
      "Authorization": "Bearer ${TRACECAT_MCP_PAT}"
    }
    ```
  </Tab>

  <Tab title="Cursor" icon="https://cdn.simpleicons.org/cursor">
    On Tracecat Cloud, click [Add Tracecat to Cursor](https://cursor.com/en-US/install-mcp?name=tracecat\&config=eyJ1cmwiOiJodHRwczovL3BsYXRmb3JtLnRyYWNlY2F0LmNvbS9tY3AifQ)
    to add it in one click. Otherwise configure `.cursor/mcp.json` manually:

    ```json theme={null}
    {
      "mcpServers": {
        "tracecat": {
          "url": "https://platform.tracecat.com/mcp"
        }
      }
    }
    ```

    To use a [personal access token (PAT)](/automations/tracecat-mcp#personal-access-tokens) instead of
    OAuth, add an `Authorization` header (Cursor resolves `${env:TRACECAT_MCP_PAT}`
    from your environment):

    ```json theme={null}
    "headers": {
      "Authorization": "Bearer ${env:TRACECAT_MCP_PAT}"
    }
    ```
  </Tab>
</Tabs>

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

1. In your workspace, go to **Settings → MCP** and create a token. Set a name and
   expiration.
2. Copy the token when it is shown. It is only displayed once and cannot be
   retrieved again.
3. Pass it as a bearer header from your MCP client — see the **PAT** option in
   each [Setup](#setup) tab above for Claude Code, Codex, Copilot, and Cursor.

<Note>
  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.
</Note>

## Starter prompts

<Prompt description="Recreate automation from blog post" icon="newspaper" actions={["copy"]}>
  Recreate a security automation based on a blog post.

  Review the following examples and ask me if I have a specific one in mind, or if I'd like to implement one of these:

  * Slack's Distributed Security Alerting ([https://slack.engineering/distributed-security-alerting/](https://slack.engineering/distributed-security-alerting/))
  * AWS Incident Response Playbooks ([https://github.com/aws-samples/aws-incident-response-playbooks](https://github.com/aws-samples/aws-incident-response-playbooks))
  * GitLab SIRT Incident Response ([https://handbook.gitlab.com/handbook/security/security-operations/sirt/sec-incident-response/](https://handbook.gitlab.com/handbook/security/security-operations/sirt/sec-incident-response/))
  * Reddit's Threat Detection ([https://www.reddit.com/r/RedditEng/comments/1riyeam/how\_reddit\_does\_threat\_detection/](https://www.reddit.com/r/RedditEng/comments/1riyeam/how_reddit_does_threat_detection/))

  Once we've selected a post:

  1. Analyze the post to identify the core workflow logic, required data tables, and integration points.
  2. Design and implement the necessary Tracecat workflows and tables.
  3. Question any assumptions in the original post that might not apply to a modern cloud-native environment.
  4. Ask clarifying questions about my specific environment, such as preferred communication channels or existing security stack.
</Prompt>

<Prompt description="Audit and improve existing workflows" icon="clipboard-check" actions={["copy"]}>
  Audit my existing Tracecat workflows, tables, and cases.

  Goal:

  1. Suggest improvements for efficiency, reliability, and security.
  2. Identify missing components, with a specific focus on SLAs, reporting, and observability.
  3. Question assumptions about my current data retention and alerting thresholds.
  4. Ask clarifying questions about my team's response requirements and reporting stakeholders.
</Prompt>

<Prompt description="Build alert triage automation" icon="shield-alert" actions={["copy"]}>
  Build a security automation for automated alert triage and response.

  Tasks:

  1. Create a workflow triggered by a webhook that receives inbound security alerts.
  2. Ask me if I have a SIEM or central log repository (like Splunk or Sentinel) that should be the primary alert source.
  3. Implement an AI analysis step using `ai.action` or `ai.agent` to interpret the alert context.
  4. Ask which enrichment integrations (such as VirusTotal or urlscan.io) I'd like to include for reputation checks.
  5. Ensure the workflow creates a case for any alert that meets a specific risk threshold.
  6. Question assumptions about alert fidelity and whether automated actions should be taken without human review.
  7. Ask clarifying questions about my data schemas, expected alert volume, and specific response SLAs.
</Prompt>

<Prompt description="Automate phishing email response" icon="mail-warning" actions={["copy"]}>
  Build an automated response for user-reported phishing emails.

  Tasks:

  1. Design a workflow that triggers when a user submits a suspicious email to our phishing reporting mailbox.
  2. Use a script or AI step to extract all URLs, domains, and attachments from the email body.
  3. Perform reputation checks and sandboxing using my available security tools (e.g., URLScan, Joe Sandbox, or CrowdStrike).
  4. Ask which email service (Microsoft 365 or Google Workspace) I'd like to integrate with for automated deletion or quarantine.
  5. Create a case to notify the SOC if the email is confirmed malicious.
  6. Question assumptions about whether automated deletion should happen for "suspicious" but not "confirmed" hits.
  7. Ask clarifying questions about our internal whitelist of trusted senders and domains.
</Prompt>

## MCP tools

<ResponseField name="list_workspaces" type="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.
</ResponseField>

<ResponseField name="create_workflow" type="tool">
  Create a new workflow in a workspace.
</ResponseField>

<ResponseField name="get_workflow" type="tool">
  Get metadata for a specific workflow.
</ResponseField>

<ResponseField name="edit_workflow" type="tool">
  Edit a draft workflow using RFC 6902 JSON Patch.
</ResponseField>

<ResponseField name="update_workflow" type="tool">
  Update workflow metadata and optional inline YAML.
</ResponseField>

<ResponseField name="list_workflows" type="tool">
  List workflows in a workspace.
</ResponseField>

<ResponseField name="list_workflow_tree" type="tool">
  List workflow folders and workflows under a path.
</ResponseField>

<ResponseField name="create_workflow_folder" type="tool">
  Create a workflow folder by absolute path.
</ResponseField>

<ResponseField name="rename_workflow_folder" type="tool">
  Rename a workflow folder by absolute path.
</ResponseField>

<ResponseField name="move_workflow_folder" type="tool">
  Move a workflow folder under a new parent path.
</ResponseField>

<ResponseField name="delete_workflow_folder" type="tool">
  Delete a workflow folder by absolute path.
</ResponseField>

<ResponseField name="move_workflows" type="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.
</ResponseField>

<ResponseField name="list_actions" type="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`.
</ResponseField>

<ResponseField name="sync_custom_registry" type="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.
</ResponseField>

<ResponseField name="get_action_context" type="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".
</ResponseField>

<ResponseField name="get_workflow_authoring_context" type="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
</ResponseField>

<ResponseField name="validate_workflow" type="tool">
  Validate a workflow's draft state.

  Checks that the workflow DSL is structurally sound and that arguments are valid.
</ResponseField>

<ResponseField name="prepare_template_file_upload" type="tool">
  Prepare a staged template YAML upload for remote `/mcp` clients.
</ResponseField>

<ResponseField name="validate_template_action" type="tool">
  Validate a template action YAML file.

  Validates YAML parsing, template schema correctness, step action references, argument schemas, and expression references.
</ResponseField>

<ResponseField name="publish_workflow" type="tool">
  Publish (commit) a workflow, creating a new versioned definition.

  This validates the workflow, freezes registry dependencies, and creates a new workflow definition version.
</ResponseField>

<ResponseField name="run_draft_workflow" type="tool">
  Run a workflow from its current draft state (without publishing).

  Optionally update the workflow's title/description before running.
</ResponseField>

<ResponseField name="run_published_workflow" type="tool">
  Run the latest published version of a workflow.

  The workflow must have been published (committed) at least once.
</ResponseField>

<ResponseField name="list_workflow_executions" type="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`.
</ResponseField>

<ResponseField name="get_workflow_execution" type="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.
</ResponseField>

<ResponseField name="get_webhook" type="tool">
  Get webhook configuration for a workflow.
</ResponseField>

<ResponseField name="update_webhook" type="tool">
  Update webhook configuration for a workflow.
</ResponseField>

<ResponseField name="get_case_trigger" type="tool">
  Get case trigger configuration for a workflow.
</ResponseField>

<ResponseField name="update_case_trigger" type="tool">
  Update an existing case trigger for a workflow.
</ResponseField>

<ResponseField name="list_workflow_tags" type="tool">
  List workflow tag definitions in a workspace.

  Returns a JSON array of tag objects with `id`, `name`, `ref`, and `color`.
</ResponseField>

<ResponseField name="create_workflow_tag" type="tool">
  Create a workflow tag definition.
</ResponseField>

<ResponseField name="update_workflow_tag" type="tool">
  Update a workflow tag definition.
</ResponseField>

<ResponseField name="delete_workflow_tag" type="tool">
  Delete a workflow tag definition.
</ResponseField>

<ResponseField name="list_tags_for_workflow" type="tool">
  List tags attached to a workflow.

  Returns a JSON array of tag objects with `id`, `name`, `ref`, and `color`.
</ResponseField>

<ResponseField name="add_workflow_tag" type="tool">
  Attach an existing workflow tag definition to a workflow.
</ResponseField>

<ResponseField name="remove_workflow_tag" type="tool">
  Remove a workflow tag association from a workflow.
</ResponseField>

<ResponseField name="list_cases" type="tool">
  List cases in a workspace with default sorting.
</ResponseField>

<ResponseField name="search_cases" type="tool">
  Search cases with filtering and sorting.
</ResponseField>

<ResponseField name="get_case" type="tool">
  Get a specific case with full details including fields, tags, and description.
</ResponseField>

<ResponseField name="create_case" type="tool">
  Create a new case.
</ResponseField>

<ResponseField name="update_case" type="tool">
  Update a case. Only provided fields are changed.
</ResponseField>

<ResponseField name="list_case_comments" type="tool">
  List all comments for a case.
</ResponseField>

<ResponseField name="list_case_comment_threads" type="tool">
  List comment threads for a case. Each thread contains the root comment and its replies.
</ResponseField>

<ResponseField name="create_case_comment" type="tool">
  Create a new comment on a case. Provide `parent_id` to reply to an existing comment.
</ResponseField>

<ResponseField name="update_case_comment" type="tool">
  Update an existing comment on a case.
</ResponseField>

<ResponseField name="delete_case_comment" type="tool">
  Delete a comment from a case.
</ResponseField>

<ResponseField name="list_case_tasks" type="tool">
  List all tasks for a case.
</ResponseField>

<ResponseField name="get_case_task" type="tool">
  Get a specific case task by ID.
</ResponseField>

<ResponseField name="create_case_task" type="tool">
  Create a new task on a case.
</ResponseField>

<ResponseField name="update_case_task" type="tool">
  Update a case task. Only provided fields are changed.
</ResponseField>

<ResponseField name="run_case_task" type="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.
</ResponseField>

<ResponseField name="list_case_events" type="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.
</ResponseField>

<ResponseField name="list_case_tags" type="tool">
  List case tag definitions in a workspace.

  Returns a JSON array of tag objects with `id`, `name`, `ref`, and `color`.
</ResponseField>

<ResponseField name="create_case_tag" type="tool">
  Create a case tag definition.
</ResponseField>

<ResponseField name="update_case_tag" type="tool">
  Update a case tag definition.
</ResponseField>

<ResponseField name="delete_case_tag" type="tool">
  Delete a case tag definition.
</ResponseField>

<ResponseField name="list_tags_for_case" type="tool">
  List tags attached to a case.

  Returns a JSON array of tag objects with `id`, `name`, `ref`, and `color`.
</ResponseField>

<ResponseField name="add_case_tag" type="tool">
  Attach a case tag to a case.
</ResponseField>

<ResponseField name="remove_case_tag" type="tool">
  Remove a case tag association from a case.
</ResponseField>

<ResponseField name="list_case_fields" type="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`.
</ResponseField>

<ResponseField name="create_case_field" type="tool">
  Create a case field definition.

  Supports optional create-only `kind`: `LONG_TEXT` requires `type="TEXT"` and `URL` requires `type="JSONB"`.
</ResponseField>

<ResponseField name="update_case_field" type="tool">
  Update a case field definition.
</ResponseField>

<ResponseField name="list_case_dropdowns" type="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`.
</ResponseField>

<ResponseField name="create_case_dropdown" type="tool">
  Create a case dropdown definition with optional initial options. Requires the case add-ons entitlement.
</ResponseField>

<ResponseField name="update_case_dropdown" type="tool">
  Update a case dropdown definition. Only provided fields are changed. Requires the case add-ons entitlement.
</ResponseField>

<ResponseField name="delete_case_dropdown" type="tool">
  Delete a case dropdown definition along with all its options and per-case values. Requires the case add-ons entitlement.
</ResponseField>

<ResponseField name="add_case_dropdown_option" type="tool">
  Add an option to a case dropdown definition. Requires the case add-ons entitlement.
</ResponseField>

<ResponseField name="update_case_dropdown_option" type="tool">
  Update an option within a case dropdown definition. Only provided fields are changed. Requires the case add-ons entitlement.
</ResponseField>

<ResponseField name="delete_case_dropdown_option" type="tool">
  Delete an option from a case dropdown definition. Requires the case add-ons entitlement.
</ResponseField>

<ResponseField name="set_case_dropdown_value" type="tool">
  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.
</ResponseField>

<ResponseField name="list_tables" type="tool">
  List workspace tables.
</ResponseField>

<ResponseField name="create_table" type="tool">
  Create a table with optional columns.
</ResponseField>

<ResponseField name="get_table" type="tool">
  Get table definition and index metadata.
</ResponseField>

<ResponseField name="update_table" type="tool">
  Update table metadata.
</ResponseField>

<ResponseField name="insert_table_row" type="tool">
  Insert a table row.
</ResponseField>

<ResponseField name="insert_rows" type="tool">
  Insert multiple table rows.
</ResponseField>

<ResponseField name="update_table_row" type="tool">
  Update a table row.
</ResponseField>

<ResponseField name="update_rows" type="tool">
  Update multiple table rows with the same values.
</ResponseField>

<ResponseField name="search_table_rows" type="tool">
  Search rows in a table.
</ResponseField>

<ResponseField name="export_csv" type="tool">
  Export table data as a staged download URL.
</ResponseField>

<ResponseField name="create_column_index" type="tool">
  Create a unique index on a table column. Only one unique index per table is allowed.
</ResponseField>

<ResponseField name="drop_column_index" type="tool">
  Drop the unique index on a table column.
</ResponseField>

<ResponseField name="list_variables" type="tool">
  List workspace variables.
</ResponseField>

<ResponseField name="get_variable" type="tool">
  Get a workspace variable.
</ResponseField>

<ResponseField name="list_secrets_metadata" type="tool">
  List secret metadata without secret values.
</ResponseField>

<ResponseField name="get_secret_metadata" type="tool">
  Get secret metadata by name without secret values.
</ResponseField>

<ResponseField name="list_integrations" type="tool">
  List workspace integrations useful for workflow and preset authoring.
</ResponseField>

<ResponseField name="get_agent_preset_authoring_context" type="tool">
  Get models, integrations, `output_type` guidance, and other preset authoring context.
</ResponseField>

<ResponseField name="create_agent_preset" type="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`.
</ResponseField>

<ResponseField name="update_agent_preset" type="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.
</ResponseField>

<ResponseField name="list_agent_tree" type="tool">
  List agent folders and presets under a path.
</ResponseField>

<ResponseField name="create_agent_folder" type="tool">
  Create an agent folder by absolute path.
</ResponseField>

<ResponseField name="rename_agent_folder" type="tool">
  Rename an agent folder by absolute path.
</ResponseField>

<ResponseField name="move_agent_folder" type="tool">
  Move an agent folder under a new parent path.
</ResponseField>

<ResponseField name="delete_agent_folder" type="tool">
  Delete an agent folder by absolute path.
</ResponseField>

<ResponseField name="move_agent_presets" type="tool">
  Move agent presets into or out of a folder by preset slug.
</ResponseField>

<ResponseField name="list_skills" type="tool">
  List workspace skills with IDs, names, and current published versions.

  Use this before updating, publishing, or attaching skills to agent presets.
</ResponseField>

<ResponseField name="upload_skill" type="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`.
</ResponseField>

<ResponseField name="update_skill" type="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.
</ResponseField>

<ResponseField name="publish_skill" type="tool">
  Publish a skill draft into an immutable skill version.

  Only published skill versions can be attached to agent presets.
</ResponseField>

<ResponseField name="list_agent_presets" type="tool">
  List saved agent preset slugs and names.

  Use `get_agent_preset` for the full preset definition.
</ResponseField>

<ResponseField name="get_agent_preset" type="tool">
  Get the full configuration for a saved agent preset by slug.
</ResponseField>

<ResponseField name="run_agent_preset" type="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.
</ResponseField>