SentinelOne API Patterns

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:

| Variable | Description | |----------|-------------| | PURPLEMCP_CONSOLE_TOKEN / SENTINELONE_TOKEN | Service User API token | | PURPLEMCP_CONSOLE_BASE_URL / SENTINELONE_BASE_URL | Console URL (e.g., https://your-console.sentinelone.net) |

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:

| Mode | Flag | Description | Use Case | |------|------|-------------|----------| | stdio | --mode stdio | Standard input/output | Claude Desktop, local usage (recommended) | | SSE | --mode sse | Server-Sent Events over HTTP | Remote/shared access | | Streamable HTTP | --mode streamable-http | HTTP with streaming | Production deployments |

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

| Tool | Description | Parameters | |------|-------------|------------| | purple_ai | Natural language cybersecurity assistant for threat investigation and PowerQuery generation | query (required) - natural language question or investigation prompt |

Alert Tools (GraphQL)

| Tool | Description | Parameters | |------|-------------|------------| | get_alert | Get a single alert by ID | alertId (required) | | list_alerts | List alerts with filters | severity, status, viewType, limit, cursor, sortBy, sortOrder | | search_alerts | Search alerts with GraphQL filters | filters (fieldId/filterType/values), limit, cursor | | get_alert_notes | Get notes/comments on an alert | alertId (required) | | get_alert_history | Get timeline of changes for an alert | alertId (required) |

Vulnerability Tools (GraphQL)

| Tool | Description | Parameters | |------|-------------|------------| | get_vulnerability | Get a single vulnerability by ID | vulnerabilityId (required) | | list_vulnerabilities | List vulnerabilities with filters | severity, status, limit, cursor, sortBy, sortOrder | | search_vulnerabilities | Search vulnerabilities with GraphQL filters | filters (fieldId/filterType/values), limit, cursor | | get_vulnerability_notes | Get notes on a vulnerability | vulnerabilityId (required) | | get_vulnerability_history | Get timeline of changes for a vulnerability | vulnerabilityId (required) |

Misconfiguration Tools (GraphQL)

| Tool | Description | Parameters | |------|-------------|------------| | get_misconfiguration | Get a single misconfiguration by ID | misconfigurationId (required) | | list_misconfigurations | List misconfigurations with filters | severity, status, viewType, limit, cursor, sortBy, sortOrder | | search_misconfigurations | Search misconfigurations with GraphQL filters | filters (fieldId/filterType/values), limit, cursor | | get_misconfiguration_notes | Get notes on a misconfiguration | misconfigurationId (required) | | get_misconfiguration_history | Get timeline of changes for a misconfiguration | misconfigurationId (required) |

Inventory Tools (REST)

| Tool | Description | Parameters | |------|-------------|------------| | get_inventory_item | Get a single inventory item by ID | itemId (required) | | list_inventory_items | List inventory items with filters | surface, limit, offset, sortBy, sortOrder | | search_inventory_items | Search inventory with REST filters | filters, surface, limit, offset |

PowerQuery / Data Lake Tools

| Tool | Description | Parameters | |------|-------------|------------| | powerquery | Execute a PowerQuery against the Singularity Data Lake | query (required), fromDate, toDate | | get_timestamp_range | Get the available time range for PowerQuery data | None | | iso_to_unix_timestamp | Convert an ISO 8601 timestamp to Unix epoch milliseconds | timestamp (required) |

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:

| Filter Type | Description | Example | |-------------|-------------|---------| | EQUALS | Exact match | {"fieldId": "severity", "filterType": "EQUALS", "values": ["CRITICAL"]} | | CONTAINS | Substring match | {"fieldId": "name", "filterType": "CONTAINS", "values": ["ransomware"]} | | IN | Match any in list | {"fieldId": "status", "filterType": "IN", "values": ["NEW", "IN_PROGRESS"]} | | NOT_EQUALS | Negation | {"fieldId": "status", "filterType": "NOT_EQUALS", "values": ["RESOLVED"]} |

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

Sorting:

| Parameter | Values | |-----------|--------| | sortBy | Varies by resource (e.g., severity, detectedAt, status) | | sortOrder | ASC, DESC |

REST API (Inventory)

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

Filter Types:

| Type | Description | Example | |------|-------------|---------| | Exact match | Direct value comparison | surface=ENDPOINT | | Contains | Substring matching | name__contains=server | | Range | Numeric/date ranges | lastSeen__gte=2026-01-01 | | ID list | Match multiple IDs | ids=id1,id2,id3 | | Negation | Exclude matches | status__ne=INACTIVE |

Pagination:

| Parameter | Description | Default | |-----------|-------------|---------| | limit | Results per page | 50 | | offset | Skip N results | 0 |

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 t