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

Sign in with OAuth:

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}'

OpenAI Codex

Sign in with OAuth:

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

GitHub Copilot

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}"
}

Cursor

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

Docker Compose is the fastest way to self-host. Follow the full Docker Compose guide or the quickstart below.

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

# Download Caddyfile
curl -o Caddyfile https://raw.githubusercontent.com/TracecatHQ/tracecat/1.0.0-beta.50/Caddyfile

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

# Start Tracecat
docker compose up -d

First login

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.