SentinelOne Purple MCP Tools & API Patterns

Overview

SentinelOne provides the Purple MCP server for AI tool integration with the Singularity XDR platform. The MCP server is a Python package installed via uvx from GitHub. It exposes 23 tools covering Purple AI, alerts, vulnerabilities, misconfigurations, asset inventory, and PowerQuery threat hunting. All tools are read-only -- they support investigation and reporting but cannot modify, remediate, or take action on any resources.

The Purple MCP server has a dual API architecture:

• GraphQL API - Used for Purple AI, alerts, vulnerabilities, and misconfigurations
• REST API - Used for asset inventory

Connection & Authentication

Service User Token

Authentication requires a Service User token from the SentinelOne Management Console:

1. Navigate to Policy & Settings > User Management > Service Users
2. Create a Service User with appropriate Account or Site scope
3. Generate an API token

CRITICAL: The token must be Account or Site level. Global-level tokens are rejected by the Purple MCP server and will return authentication errors.

Environment Variables:

export SENTINELONE_TOKEN="your-service-user-token"
export SENTINELONE_BASE_URL="https://your-console.sentinelone.net"

Transport Modes

The Purple MCP server supports three transport modes:

Claude Desktop Configuration

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

Installation Requirements

The Purple MCP server requires Python and uv/uvx:

# Install uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify installation
uvx --version

# Test the MCP server
uvx --from git+https://github.com/Sentinel-One/purple-mcp.git purple-mcp --help

Note: This is a Python package, not Node.js. Use uvx, not npx.

Complete MCP Tool Reference

Purple AI Tools

Alert Tools (GraphQL)

Vulnerability Tools (GraphQL)

Misconfiguration Tools (GraphQL)

Inventory Tools (REST)

PowerQuery / Data Lake Tools

Dual API Architecture

GraphQL API (Alerts, Vulnerabilities, Misconfigurations, Purple AI)

The GraphQL API uses a filter-based query model:

Filter Structure:

{
  "fieldId": "severity",
  "filterType": "EQUALS",
  "values": ["CRITICAL"]
}

Filter Types:

Pagination: Cursor-based. Use the cursor value from the response to fetch the next page.

Sorting:

REST API (Inventory)

The REST API uses offset-based pagination with filter parameters:

Filter Types:

Pagination:

PowerQuery Language

IMPORTANT: PowerQuery is SentinelOne's Scalyr-based pipeline query language. It is NOT Splunk SPL, SQL, KQL, or Elasticsearch Query DSL.

PowerQuery uses a pipeline syntax with filters and aggregations:

EventType = "Process Creation" AND TgtProcName = "powershell.exe"
| columns SrcProcName, TgtProcName, TgtProcCmdLine, EndpointName
| limit 100

Best practice: Use the purple_ai tool with a natural language description of what you want to find, and it will generate the correct PowerQuery syntax. Then execute the generated query with the powerquery tool.

Rate Limiting

SentinelOne enforces rate limits on API calls. The Purple MCP server does not expose specific rate limit headers, but:

• Space out requests when iterating over large datasets
• Use pagination to limit result sizes
• If you receive rate limit errors, wait 30-60 seconds before retrying
• Filter server-side to reduce total API calls

Error Handling

Common Errors

Troubleshooting MCP Connection

1. Verify uvx - Ensure uvx --version returns a version
2. Check Python - Ensure python3 --version is available
3. Test manually - Run uvx --from git+https://github.com/Sentinel-One/purple-mcp.git purple-mcp --help
4. Verify token - Ensure the token is Account or Site level, not Global
5. Check console URL - Must include https:// and the full domain
6. Test with a simple call - Try list_alerts with limit=1 to verify connectivity

Best Practices

1. Use Account/Site tokens - Never use Global-level tokens; they will be rejected
2. Start with Purple AI - Use purple_ai for investigation before diving into specific tools
3. Filter server-side - Always use tool parameters to narrow results rather than fetching everything
4. Use cursor pagination - For GraphQL tools, use the cursor from each response to fetch subsequent pages
5. Scope to clients - When reviewing a specific client's security, filter by site or account
6. Generate PowerQuery via Purple AI - Do not write PowerQuery manually; describe what you want in natural language
7. Time-bound queries - Always set time ranges for PowerQuery to avoid scanning the entire Data Lake
8. Cache inventory data - Endpoint and asset data changes less frequently than alerts
9. Triage by severity - Always start with CRITICAL and HIGH severity items
10. Document findings - Use alert notes and history to build investigation timelines

Related Skills

• Purple AI - Natural language threat investigation
• Alerts - Unified alert management
• Vulnerabilities - Vulnerability tracking and remediation
• Misconfigurations - Cloud security posture management
• Inventory - Asset inventory
• Threat Hunting - PowerQuery and Data Lake queries