Getting started

The recommended way to get started is to connect your coding agent — Claude Code, OpenAI Codex, GitHub Copilot, or Cursor — to the Tracecat MCP server. This works with Tracecat Cloud or your own self-hosted instance.

Connect MCP

Connecting your agent to Tracecat Cloud automatically creates an account for you. You can also sign up manually via https://platform.tracecat.com. 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: *

Complete the OAuth sign-in from an interactive copilot session. A non-interactive run (copilot -p) does not wait for sign-in — it skips the tracecat tools until you have authenticated once interactively.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}"
}

Self-host

Choose a deployment method:

Docker Compose: Run every service on a single host. This is the fastest way to self-host.
AWS ECS Fargate: Deploy to your own AWS account with Terraform.
Kubernetes: Install the Helm chart on EKS, GKE, or any conformant cluster.
Air-gapped deployment: Run on Kubernetes with no runtime internet access.

See Architecture for how the services fit together.

Docker Compose quickstart

Follow the full Docker Compose guide or run the commands below.

# Setup environment variables and secrets
curl -o env.sh https://raw.githubusercontent.com/TracecatHQ/tracecat/1.1.0/env.sh
curl -o .env.example https://raw.githubusercontent.com/TracecatHQ/tracecat/1.1.0/.env.example
chmod +x env.sh && ./env.sh

# Download Caddyfile
curl -o Caddyfile https://raw.githubusercontent.com/TracecatHQ/tracecat/1.1.0/Caddyfile

# Download Docker Compose file
curl -o docker-compose.yml https://raw.githubusercontent.com/TracecatHQ/tracecat/1.1.0/docker-compose.yml

# Start Tracecat
docker compose up -d

Set the first superadmin’s email before anyone signs in. Until it is set, nobody can register, and the first account must match it. It takes one case-sensitive email address, so use the exact casing your identity provider sends.

Deployment	Setting
Docker Compose	`TRACECAT__AUTH_SUPERADMIN_EMAIL` in `.env`
AWS ECS Fargate	`TF_VAR_auth_superadmin_email`, or `auth_superadmin_email` in your `.tfvars`
Kubernetes	`tracecat.auth.superadminEmail` in `values.yaml`

Basic auth: sign up with that email, then log in.
SSO: log in through your identity provider. Tracecat creates the account on first login.

The account becomes superadmin and owner of the default organization.

Next steps

See Environment variables to configure your deployment.
See TLS and certificates to serve Tracecat over HTTPS.
See User management to invite your team.
See SAML SSO or OIDC to sign in through your identity provider.

Overview

Building automations

Building agents

Building custom integrations

Connect MCP

Self-host

Docker Compose quickstart

Next steps

​Connect MCP

​Self-host

​Docker Compose quickstart

​First login

​Next steps

Connect MCP

Self-host

Docker Compose quickstart

First login

Next steps