# SentinelOne MCP Server

Read-only MCP server for the SentinelOne management API (v2.1). Exposes sites, endpoint agents, threats and the activity log to Claude (Claude Desktop / Cowork, Claude Code, or any MCP client), with aggregation tools built for MSP/MSSP reporting across a site-segmented client base.

## Tools

| Tool | Purpose |
|---|---|
| `s1_list_sites` | Sites (how clients are segmented in an MSP console) with licence counts, SKU, expiry and health |
| `s1_estate_overview` | Estate-wide endpoint health by site: agents, online/offline, infected, needs-update, reboot-required, stale, OS mix — the health reporting tool |
| `s1_agents` | Endpoint drill-down: per-machine status, version, last active, last user (filterable by site, health flags, OS) |
| `s1_threats` | Threat drill-down: name, classification, verdict, incident/mitigation status, affected machine (filterable by site, status, date range) |
| `s1_threat_summary` | Aggregated threat counts by site, verdict, classification, top threats and machines — the periodic reporting tool |
| `s1_activities` | Console activity/audit log: mitigations, installs, policy changes, logins |
| `s1_api_call` | Raw GET to any other SentinelOne endpoint — disabled unless `S1_ENABLE_RAW_API=true` |

The tool set is deliberately lean, focused on endpoint health and threat reporting across clients. The raw API tool covers anything else (groups, exclusions, installed applications, STAR alerts, system info) but is off by default so shared deployments stay strictly read-only.

## Quick start (Claude Desktop / Cowork)

Add to `mcpServers` in your `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
"sentinelone": {
  "command": "npx",
  "args": ["-y", "sentinelone-mcp"],
  "env": {
    "S1_API_TOKEN": "your-api-token",
    "S1_BASE_URL": "https://your-console.sentinelone.net"
  }
}
```

For Claude Code:

```bash
claude mcp add-json sentinelone --scope user '{"type":"stdio","command":"npx","args":["-y","sentinelone-mcp"],"env":{"S1_API_TOKEN":"your-api-token","S1_BASE_URL":"https://your-console.sentinelone.net"}}'
```

Requires Node.js 18+.

## Configuration

| Variable | Value |
|---|---|
| `S1_API_TOKEN` | API token — generate in the console under **My User → Actions → API Token Operations** |
| `S1_BASE_URL` | Your management console URL, e.g. `https://your-console.sentinelone.net` |
| `S1_ENABLE_RAW_API` | Optional — set to `true` to expose `s1_api_call` for arbitrary endpoints. Leave unset for team deployments. |

Notes on tokens:

- API tokens **expire** on a schedule set in the console (commonly 30 days, extendable under Settings → Users, or use a service user for longer-lived tokens). A 401 from this server almost always means the token has expired — regenerate it.
- The token inherits the scope and role of the user who generated it. A **Viewer**-role user scoped to the account is ideal: the server only ever issues GET requests, but a least-privilege token means mistakes elsewhere can't mutate anything.
- Each team member should generate their own token so console audit logs attribute API reads correctly.

## Reporting across a client base

Sites are how clients are segmented in an MSP/MSSP console. The intended flow for "state of our clients' endpoints" reporting:

1. `s1_list_sites` — the client list, with licence usage and expiry per site.
2. `s1_estate_overview` — one call sweeps every agent and returns a site-by-site health table: agent count, online/offline, infected, agents needing an update, reboot-required, stale agents (default: not seen in 30 days) and OS mix. Aggregation happens inside the server, so thousands of agents come back as a few KB of counts.
3. `s1_threat_summary` with `created_after` — threats for the reporting period, grouped by site with verdict/classification breakdowns, top threat names and noisiest machines.
4. `s1_agents` / `s1_threats` — drill into the individual machines or detections behind any number, then `s1_activities` for the audit trail of what was done about them.

## Development

```bash
git clone https://github.com/jamescash1976/sentinelone-mcp.git
cd sentinelone-mcp
npm install
cp .env.example .env   # fill in token + console URL
npm run dev            # watch mode
npm run inspector      # MCP Inspector UI
npm run build          # compile to dist/
```

## Notes

- Strictly read-only: every tool issues GET requests only. Mitigation, policy and agent actions are deliberately not implemented.
- Pagination is cursor-based throughout: responses include `nextCursor` — pass it back as `cursor` to continue. The sweep tools (`s1_estate_overview`, `s1_threat_summary`) page automatically up to their safety caps and say so when truncated.
- Rate limits (HTTP 429) are retried automatically using the `Retry-After` header, up to 3 times.
- Compact projections drop the (many) null fields SentinelOne returns and exclude site registration tokens from output. Use `full_details: true` on `s1_agents`/`s1_threats` when you need the complete raw records.
- Dates in filters are ISO 8601, e.g. `2026-07-01T00:00:00Z`.