Purple AI MCP Server

Purple AI MCP Server allows you to access SentinelOne Services with any MCP client.

Features

This server exposes SentinelOne's platform through the Model Context Protocol:

Purple AI: Ask security questions, investigate threats
Events: Run PowerQueries on events in your SentinelOne data lake
Alerts: Query, search, and investigate alerts
Vulnerabilities: Track CVEs and security findings
Misconfigurations: Analyze security posture issues
Inventory: Ask questions about endpoints, cloud resources, identities, and network devices
CVE Search: Query public CVE databases for vulnerability details
Threat Intelligence: Get file, URL, domain, and IP analysis from VirusTotal

Purple AI MCP is a read-only service - you cannot make changes to your account or any objects within your account from this MCP.

Quick Start

Using uv (Recommended for Local Development or Deployment)

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Set credentials
export PURPLEMCP_CONSOLE_TOKEN="your_token"
export PURPLEMCP_CONSOLE_BASE_URL="https://your-console.sentinelone.net"

# Run
uvx --from git+https://github.com/Sentinel-One/purple-mcp.git purple-mcp --mode=stdio

⚠️ Security note ⚠️

For production or security-sensitive environments, pin to a specific commit hash instead of using the default branch to reduce supply chain risk from the our releases or our verified commits in main branch.

# Run with pinned hash
uvx --from git+https://github.com/Sentinel-One/purple-mcp.git@<commit-hash> purple-mcp --mode=stdio

Using Docker

Follow instructions for Docker Deployment here

Using Amazon Bedrock AgentCore

Follow instructions for Amazon Bedrock AgentCore Deployment here

Using Amazon Elastic Container Service (ECS)

Follow instructions for Amazon Elastic Container Service Deployment here

Using a Cloud Provider

For cloud deployments, see Deployment Guide.

Note: Purple AI MCP does not include built-in authentication. For network-exposed deployments, place it behind a reverse proxy or load balancer. See cloud Setup for cloud load balancer configurations (AWS ALB, GCP Cloud Load Balancing, Azure Application Gateway) or nginx examples for self-hosted deployments.

Your token needs Account or Site level permissions (not Global). Get one from Policy & Settings → User Management → Service Users in your console. Currently, this server only supports tokens that have access to a single Account or Site. If you need to access multiple sites, you will need to run multiple MCP servers with Account-specific or Site-specific tokens.

Authentication

Purple MCP uses a SentinelOne Console token configured at startup via environment variables. The server authenticates with your SentinelOne Console using the provided token and base URL.

# Configure authentication credentials
PURPLEMCP_CONSOLE_TOKEN=YOUR_CONSOLE_TOKEN
PURPLEMCP_CONSOLE_BASE_URL=https://console.sentinelone.net

In addition you may define a console scope for Purple AI query operations:

PURPLEMCP_PURPLE_AI_CONSOLE_ACCOUNT_ID=1234567890123456789

This will scope Purple AI queries to account-scope with id 1234567890123456789.

Health Check Endpoints:

The following endpoints bypass authentication to support container orchestration systems (Kubernetes, Docker, etc.):

/health, /ready, /ping

These endpoints return only basic status ({"status": "ok"}) and do not expose sensitive information. See SECURITY.md for details.

Clients

Purple AI MCP supports stdio, sse, and streamable-http protocols and should work in any client that supports MCP. Some sample configurations are listed below.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "purple-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Sentinel-One/purple-mcp.git",
        "purple-mcp",
        "--mode",
        "stdio"
      ],
      "env": {
        "PURPLEMCP_CONSOLE_TOKEN": "your_token",
        "PURPLEMCP_CONSOLE_BASE_URL": "https://your-console.sentinelone.net"
      }
    }
  }
}

Claude Code

Run this command in a terminal:

claude mcp add --transport stdio purple-mcp --env PURPLEMCP_CONSOLE_TOKEN=your_token --env PURPLEMCP_CONSOLE_BASE_URL=https://your-console.sentinelone.net -- uvx --from git+https://github.com/Sentinel-One/purple-mcp.git purple-mcp --mode stdio

OpenAI Codex

Run this command in a terminal:

codex mcp add purple-mcp --env PURPLEMCP_CONSOLE_TOKEN=your_token --env PURPLEMCP_CONSOLE_BASE_URL=https://your-console.sentinelone.net -- uvx --from git+https://github.com/Sentinel-One/purple-mcp.git purple-mcp --mode stdio

Pydantic AI

Here is some example Python code to use Purple MCP with a Pydantic AI Agent.

from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStdio

server = MCPServerStdio(
    'uvx', args=["--from", "git+https://github.com/Sentinel-One/purple-mcp.git", "purple-mcp", "--mode", "stdio"], timeout=10
)
agent = Agent('anthropic:claude-haiku-4-5', toolsets=[server])

Zed

Edit ~/.zed/mcp.json:

{
  "mcpServers": {
    "purple-mcp": {
      "enabled": true,
      "source": "custom",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Sentinel-One/purple-mcp.git",
        "purple-mcp",
        "--mode",
        "stdio"
      ],
      "env": {
        "PURPLEMCP_CONSOLE_TOKEN": "your_token",
        "PURPLEMCP_CONSOLE_BASE_URL": "https://your-console.sentinelone.net"
      }
    }
  }
}

Other Clients

For debugging or to host server for multiple clients, run in streamable-http mode and connect via mcp-remote:

# Terminal 1: Start server
export PURPLEMCP_CONSOLE_TOKEN="your_token"
export PURPLEMCP_CONSOLE_BASE_URL="https://your-console.sentinelone.net"
uvx --from git+https://github.com/Sentinel-One/purple-mcp.git purple-mcp --mode streamable-http --host localhost --port 8000

# Terminal 2: Connect with any client
npx -y mcp-remote http://127.0.0.1:8000/mcp

We suggest you do not expose Purple AI MCP on a network at this time, as there is no authentication enforced and anyone could access a configured SentinelOne account.

Available Tools

Purple AI

purple_ai(query) - Ask security questions

Data Lake

powerquery(query, start_time, end_time) - Run PowerQuery analytics

Alerts

get_alert(alert_id) - Get alert details
list_alerts(first, after, view_type) - List recent alerts
search_alerts(filters, first) - Search with filters
get_alert_notes(alert_id) - Get alert comments
get_alert_history(alert_id) - View alert timeline

Vulnerabilities

get_vulnerability(id) - Get vulnerability details
list_vulnerabilities(first, after) - List recent vulnerabilities
search_vulnerabilities(filters, first) - Search CVEs and findings
get_vulnerability_notes(id) - Get comments
get_vulnerability_history(id) - View timeline

Misconfigurations

get_misconfiguration(id) - Get misconfiguration details
list_misconfigurations(first, after) - List recent issues
search_misconfigurations(filters, first) - Search by criteria
get_misconfiguration_notes(id) - Get comments
get_misconfiguration_history(id) - View timeline

Asset Inventory

get_inventory_item(item_id, fetch_fields) - Get asset details with field filtering
list_inventory_items(limit, skip, surface, fetch_fields) - List assets by surface type
search_inventory_items(filters, limit, skip, fetch_fields) - Search with advanced filters

Field Filtering: All inventory tools support fetch_fields parameter to control returned data:

Presets: MINIMAL (7 fields), STANDARD (13 fields), ALL (~200+ fields)
Custom lists: Specify exact fields in camelCase, e.g., ["id", "name", "resourceType"]
Use get_inventory_item(item_id, fetch_fields="ALL") on a single item to discover available field names

CVE Search (External)

Query public CVE databases (cve-search.org) for vulnerability information:

cve_search_by_id(cve_id) - Get detailed CVE information by ID
cve_search_by_vendor(vendor, product) - Search CVEs by vendor/product
cve_database_status() - Get database update information

Note: No API key required. Data sourced from CIRCL.LU's cve-search.org.

Threat Intelligence (External)

Query VirusTotal/Google Threat Intelligence for file, URL, domain, and IP analysis:

threat_intel_by_hash(hash_value) - Get threat intel for file hash (MD5/SHA1/SHA256)
threat_intel_by_url(url) - Get URL reputation and analysis
threat_intel_by_domain(domain) - Get domain threat intelligence
threat_intel_by_ip(ip_address) - Get IP address threat intelligence
threat_intel_get_file_relationships(hash_value, relationship_type) - Get file relationships (contacted domains/IPs, similar files)
threat_intel_search(query) - Search VirusTotal Intelligence (Premium API required)
threat_intel_get_file_behavior(hash_value, sandbox) - Get sandbox behavioral analysis

Note: Requires PURPLEMCP_VT_API_KEY environment variable with a valid VirusTotal API key.

Environment Variables

Required

PURPLEMCP_CONSOLE_TOKEN - Authentication token (Service User token or Console API token)
PURPLEMCP_CONSOLE_BASE_URL - Console URL (e.g., https://console.sentinelone.net)

Optional

PURPLEMCP_SDL_BASE_URL - Dedicated base URL for the SDL API
- When set, this URL is used directly instead of PURPLEMCP_CONSOLE_BASE_URL + /sdl
- Example: https://your-dedicated-sdl-endpoint.sentinelone.net
- When not set, the SDL API is accessed at {PURPLEMCP_CONSOLE_BASE_URL}/sdl (default behavior)
PURPLEMCP_VT_API_KEY - VirusTotal API key for threat intelligence tools (get one from https://www.virustotal.com/gui/my-apikey)
PURPLEMCP_SDL_CONSOLE_ACCOUNT_IDS - Account IDs for SDL query scoping (comma-separated or JSON array)
- When specified: queries are scoped to the provided account(s)
- When not specified: queries all accounts accessible to the token
- Example: "426418030212073761" or "123,456,789" or ["123", "456"]
PURPLEMCP_SDL_CONSOLE_SITE_IDS - Site IDs for SDL query scoping
- When specified: queries are scoped to the provided site
- Requires PURPLEMCP_SDL_CONSOLE_ACCOUNT_IDS to also be set with exactly one account ID
- Example: "1234567890123456789" or "123,456,789" or "[123, 456]"
- Note: Currently, only the first site ID is used.
PURPLEMCP_TRANSPORT_MODE - MCP transport mode: stdio, http, streamable-http, or sse (default: stdio)
PURPLEMCP_STATELESS_HTTP - Enable stateless HTTP mode for serverless deployments (e.g., Amazon Bedrock AgentCore) - see deployment guide

Development

We welcome your pull requests or issue submissions.

Setup

# Install all dependencies
uv sync --all-groups

# Format and lint
uv run ruff format
uv run ruff check .
uv run mypy src tests

Testing

# Run unit tests
uv run pytest tests/unit/ -v

# Run integration tests (requires .env.test with real credentials)
uv run pytest tests/integration/ -v

# All tests with coverage
uv run pytest --cov=src/purple_mcp --cov-report=html

Env-vars for integration-testing of Account Scopes

There are some integration tests that require additional configuration to run (if left unconfigured they will be skipped). If you want to run test_sdl_scope_integration.py you will need to define the following env-vars in your .env.test file (with the dummy values replaced for your test scenario):

# An accessible account for your console token:
PURPLEMCP_SDL_CONSOLE_ACCOUNT_IDS=123456789012345678
# Another account from your console
PURPLEMCP_SDL_INT_TEST_SECOND_ACCOUNT_ID=222333444555666
# An Agent UUID accessible in your primary account:
PURPLEMCP_SDL_INT_TEST_AGENT_UUID=aaabbb-1234-5678-ccdd-678e89100bb1
# A timestamp at the middle of a 10-minute window where you expect to see events from the Agent UUID:
PURPLEMCP_SDL_INT_TEST_AGENT_EVENT_TIMESTAMP=2025-11-18T05:25:00+00:00

Troubleshooting

Authentication errors: Check your token has Account/Site level permissions (not Global), and your token has not expired
PowerQuery does not return expected results: Check your token has Account/Site level permissions (not Global)
Connection failures: Verify your console URL and network access; use --verbose for debug logs

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

This project is open source and community-driven. Although it is not an official SentinelOne product, it is maintained by SentinelOne in partnership with the broader open source developer community. See our LICENSE file for further information.

For SentinelOne platform support, use the appropriate support channel.

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
.github		.github
deploy		deploy
src/purple_mcp		src/purple_mcp
tests		tests
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.python-version		.python-version
AGENTS.md		AGENTS.md
AUTHORS.md		AUTHORS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
docker-entrypoint.sh		docker-entrypoint.sh
pyproject.toml		pyproject.toml
ruff.toml		ruff.toml
uv.lock		uv.lock

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Purple AI MCP Server

Features

Quick Start

Using uv (Recommended for Local Development or Deployment)

⚠️ Security note ⚠️

Using Docker

Using Amazon Bedrock AgentCore

Using Amazon Elastic Container Service (ECS)

Using a Cloud Provider

Authentication

Clients

Claude Desktop

Claude Code

OpenAI Codex

Pydantic AI

Zed

Other Clients

Available Tools

Purple AI

Data Lake

Alerts

Vulnerabilities

Misconfigurations

Asset Inventory

CVE Search (External)

Threat Intelligence (External)

Environment Variables

Required

Optional

Development

Setup

Testing

Env-vars for integration-testing of Account Scopes

Troubleshooting

License

Support

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 4

Uh oh!

Contributors

Uh oh!

Languages