> For the complete documentation index, see [llms.txt](https://help.nightfall.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.nightfall.ai/developer-api/nightfall_apis/nightfall-model-context-protocol-mcp-server/available-tools.md).

# Available Tools

The Nightfall MCP server provides 33 tools organized into seven categories.

### Tool safety annotations

Every tool the server advertises carries the standard MCP annotations, so an agent harness can decide what to run unattended and what to confirm with a person first. All four fields are always present — none is left to its default.

| Annotation          | Meaning                                                                            |
| ------------------- | ---------------------------------------------------------------------------------- |
| **readOnlyHint**    | The tool does not modify anything. True for all 26 read tools.                     |
| **destructiveHint** | The tool may make changes that Nightfall cannot undo.                              |
| **idempotentHint**  | Repeating the call with identical arguments has no further effect.                 |
| **openWorldHint**   | The effect lands in a connected third-party system rather than in Nightfall alone. |

Tools fall into exactly three profiles:

| Profile      | Tools                      | readOnly | destructive | idempotent | openWorld |
| ------------ | -------------------------- | -------- | ----------- | ---------- | --------- |
| Read         | 26                         | `true`   | `false`     | `true`     | `false`   |
| Remediation  | 3 × **take\_action\_\***   | `false`  | `true`      | `false`    | `true`    |
| Policy scope | 4 × **update\_policy\_\*** | `false`  | `true`      | `true`     | `false`   |

Remediation tools are open-world because the action executes in Google Drive, Slack, GitHub, Jira or Teams, and non-idempotent because a repeated call sends another notification or files another ticket. Policy-scope tools stay inside Nightfall, but count as destructive because a call can remove entries from a policy's scope, which silently ends DLP coverage for those users or domains. They are idempotent: the payload is a target state, not a delta, so retrying a call that timed out is safe.

{% hint style="warning" %}
**Annotations are advisory metadata for the calling harness, not an access control.** The server does not scope tools per key: any enabled API key can call all 33 tools, including the seven that modify data. Your key determines which tenant's data is reachable, not which tools may be used.

So the annotations are what a well-behaved harness uses to decide when to ask a person first — they are not what stops an unauthorized call. Control access by controlling who holds the key, and by running a harness that honours the hints.
{% endhint %}

#### 1. Detection & Response Incidents (6 tools)

Work with Data Loss Prevention policy violations detected across your integrations.

| Tool Name                        | Description                                                     | Safety          |
| -------------------------------- | --------------------------------------------------------------- | --------------- |
| **search\_violations**           | Search violations using structured queries (field:value syntax) | Read-only       |
| **list\_violations**             | Browse recent violations with date range filters                | Read-only       |
| **get\_violation**               | Get full details for a specific violation                       | Read-only       |
| **get\_violation\_findings**     | View sensitive data findings within a violation                 | Read-only       |
| **get\_violation\_activity**     | Review activity timeline and remediation history                | Read-only       |
| **take\_action\_on\_violations** | Execute remediation actions (resolve, block, delete, etc.)      | **Destructive** |

#### 2. Data Exfiltration Incidents (5 tools)

Investigate data exfiltration attempts and suspicious file activity.

| Tool Name                                  | Description                                        | Safety          |
| ------------------------------------------ | -------------------------------------------------- | --------------- |
| **search\_exfiltration\_events**           | Search exfiltration events with advanced filters   | Read-only       |
| **list\_exfiltration\_events**             | Browse recent exfiltration events                  | Read-only       |
| **get\_exfiltration\_event**               | Get complete event details and affected assets     | Read-only       |
| **get\_exfiltration\_event\_activity**     | View event timeline and status changes             | Read-only       |
| **take\_action\_on\_exfiltration\_events** | Execute remediation actions on exfiltration events | **Destructive** |

#### 3. Posture Management Incidents (5 tools)

Monitor configuration risks and permission changes.

| Tool Name                             | Description                                   | Safety          |
| ------------------------------------- | --------------------------------------------- | --------------- |
| **search\_posture\_events**           | Search for security posture issues            | Read-only       |
| **list\_posture\_events**             | Browse recent posture events                  | Read-only       |
| **get\_posture\_event**               | Get detailed event information                | Read-only       |
| **get\_posture\_event\_activity**     | View event activity history                   | Read-only       |
| **take\_action\_on\_posture\_events** | Execute remediation actions on posture events | **Destructive** |

#### 4. Activity Tools (2 tools)

Track user and asset activity across all event types.

| Tool Name                | Description                          | Safety    |
| ------------------------ | ------------------------------------ | --------- |
| **get\_actor\_activity** | Get complete user activity history   | Read-only |
| **get\_asset\_activity** | Track file/document activity history | Read-only |

#### 5. Policy Configuration (4 tools)

Adjust which users and domains a policy applies to. Only supported for Google Drive policies.

| Tool Name                                  | Description                                                         | Safety          |
| ------------------------------------------ | ------------------------------------------------------------------- | --------------- |
| **update\_policy\_user\_scope**            | Add or remove users in a DLP policy's user scope, by email          | **Destructive** |
| **update\_policy\_domain\_scope**          | Add or remove domains in a DLP policy's domain scope                | **Destructive** |
| **update\_policy\_trigger\_user\_scope**   | Add or remove trigger-scoped users on a posture management policy   | **Destructive** |
| **update\_policy\_trigger\_domain\_scope** | Add or remove trigger-scoped domains on a posture management policy | **Destructive** |

{% hint style="warning" %}
Removing an entry from a policy's scope ends DLP coverage for it. These tools take an `add` and a `delete` payload in one call and return the full resulting include and exclude lists, so the response is the place to confirm what the policy now covers.
{% endhint %}

#### 6. AI Governance (6 tools)

Inventory of AI tooling discovered across managed endpoints: MCP servers, agent plugins, agent hooks and IDE extensions.

| Tool Name                      | Description                                                                                                                   | Safety    |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | --------- |
| **list\_ai\_inventory**        | List any AI inventory — set `type` to `mcp_server`, `plugin`, `hook` or `ide_extension`, and `scope` to `company` or `device` | Read-only |
| **list\_mcp\_servers**         | Browse discovered MCP servers with device counts, usage and risk                                                              | Read-only |
| **get\_mcp\_server**           | Get one MCP server, including public registry metadata when matched                                                           | Read-only |
| **list\_mcp\_server\_devices** | List the devices using a given MCP server, with a per-client breakdown                                                        | Read-only |
| **list\_mcp\_devices**         | List devices that have any MCP server installed                                                                               | Read-only |
| **get\_device\_mcp\_servers**  | Get one device and every MCP server running on it                                                                             | Read-only |

{% hint style="info" %}
Ids returned by these tools are opaque. Pass an `id` back exactly as returned — it encodes the full identity of the row it came from, and for plugins that includes the version, so two versions of one plugin are two different ids. Editing or reconstructing an id will not resolve.
{% endhint %}

#### 7. App Intelligence (5 tools)

SaaS and AI application usage discovered across the tenant.

| Tool Name                                     | Description                                                                                | Safety    |
| --------------------------------------------- | ------------------------------------------------------------------------------------------ | --------- |
| **app\_intelligence\_list\_apps**             | List discovered applications, with filtering and sorting                                   | Read-only |
| **app\_intelligence\_get\_app\_details**      | Get details for one application                                                            | Read-only |
| **app\_intelligence\_get\_app\_destinations** | Get the destinations an application sends data to                                          | Read-only |
| **app\_intelligence\_get\_summary\_stats**    | Summary statistics for a date range (`fromDate` and `toDate`, both required, Unix seconds) | Read-only |
| **app\_intelligence\_list\_categories**       | List available application categories                                                      | Read-only |

### Tools that modify data

Seven of the 33 tools change state. Each is annotated `readOnlyHint: false` and `destructiveHint: true`, and a harness that honours annotations will ask before running them. The other 26 only read.

| Tool Name                                  | What it changes                                                                                                     |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| **take\_action\_on\_violations**           | Remediates in the connected SaaS tenant — including HARD\_DELETE, DELETE\_FILE, REVOKE\_ACCESS and SUSPEND\_ACCOUNT |
| **take\_action\_on\_exfiltration\_events** | Remediates exfiltration events — access control and notification actions                                            |
| **take\_action\_on\_posture\_events**      | Remediates posture events — access control and notification actions                                                 |
| **update\_policy\_user\_scope**            | Adds or removes users from a DLP policy's scope                                                                     |
| **update\_policy\_domain\_scope**          | Adds or removes domains from a DLP policy's scope                                                                   |
| **update\_policy\_trigger\_user\_scope**   | Adds or removes users from a posture policy's trigger scope                                                         |
| **update\_policy\_trigger\_domain\_scope** | Adds or removes domains from a posture policy's trigger scope                                                       |

### Query Field Reference

This section provides a comprehensive reference of searchable fields across different event types. Use these when constructing advanced queries.

#### Detection & Response Incidents Fields

**Core Fields**

* `state`: ACTIVE, PENDING, RESOLVED, EXPIRED
* `integration_name`: github, gdrive, slack, confluence, jira, salesforce, teams, onedrive, etc.
* `risk_label`: HIGH, MEDIUM, LOW
* `user_email`, `user_name`: Filter by specific users
* `last_actioned_by`: NIGHTFALL, ADMIN, END\_USER
* `confidence`: Detection confidence level
* `policy_id`, `detection_rule_id`, `detector_id`: Policy and rule identifiers

**Integration-Specific Fields**

**Slack**

* `slack.channel_name`, `slack.channel_id`, `slack.workspace`

**GitHub**

* `github.org`, `github.repository`, `github.repository_owner`, `github.branch`, `github.commit`, `github.author_email`

**Google Drive**

* `gdrive.drive`

**Confluence**

* `confluence.space_name`, `confluence.parent_page_name`

**Jira**

* `jira.project_name`, `jira.ticket_number`

**Salesforce**

* `salesforce.org_name`, `salesforce.object`, `salesforce.record_id`

**Microsoft Teams**

* `teams.team_name`, `teams.channel_name`, `teams.channel_type`, `teams.team_sensitivity`, `teams.sender`, `teams.msg_importance`, `teams.msg_attachment`, `teams.chat_id`, `teams.chat_type`, `teams.chat_topic`, `teams.chat_participant`

**OneDrive**

* `onedrive.drive_owner`, `onedrive.drive_owner_email`, `onedrive.file_name`, `onedrive.created_by`, `onedrive.created_by_email`, `onedrive.modified_by`, `onedrive.modified_by_email`

**Zendesk**

* `zendesk.ticket_status`, `zendesk.ticket_title`, `zendesk.ticket_group_assignee`, `zendesk.current_user_role`

**Notion**

* `notion.created_by`, `notion.last_edited_by`, `notion.page_title`, `notion.workspace_name`

**Gmail**

* `gmail.user_name`, `gmail.from`, `gmail.to`, `gmail.cc`, `gmail.bcc`, `gmail.thread_id`, `gmail.subject`, `gmail.attachment_name`, `gmail.attachment_type`

#### Data Exfiltration Prevention Incidents Fields

**Core Fields**

* `event_type`: file\_download, file\_upload, permission\_change, etc.
* `state`: ACTIVE, PENDING, RESOLVED, EXPIRED
* `last_actioned_by`: NIGHTFALL, ADMIN, END\_USER

**Actor Fields**

* `actor_name`, `actor_email`
* `user_name`, `user_email` (backward compatible aliases)

**Resource Fields**

* `resource_id`, `resource_name`, `resource_owner_name`, `resource_owner_email`, `resource_content_type`, `notes`

**Endpoint Fields**

* `endpoint.device_id`, `endpoint.machine_name`

**Google Drive**

* `gdrive.permission`, `gdrive.shared_internal_email`, `gdrive.shared_external_email`, `gdrive.drive`, `gdrive.file_owner`, `gdrive.label_name`

**Salesforce**

* `salesforce.report.scope`, `salesforce.report.event_source`, `salesforce.report.source_ip`, `salesforce.report.session_level`, `salesforce.report.operation`, `salesforce.report.description`
* `salesforce.file.source_ip`, `salesforce.file.session_level`

#### Posture Management Incidents Fields

Security posture events support the same query fields as exfiltration events.

#### Query Operators

* **AND**: Combine multiple conditions (both must match)
* **OR**: Alternative conditions (either can match)
* **field:value** syntax for exact matches

**Example:**

```
integration_name:github AND risk_label:HIGH AND state:ACTIVE
```

#### Common Query Patterns

**Find violations by user and integration:**

```
user_email:jane@example.com AND integration_name:slack
```

**Search across multiple users:**

```
user_email:jane@example.com OR user_email:john@example.com
```

**Filter by channel and state:**

```
slack.channel_name:general AND state:PENDING
```

**Time-based queries:**

```
createdAfter=<unix_timestamp> AND risk_label:HIGH
```

***

### Error Handling

The MCP server returns structured errors in tool responses:

| Error Code       | Description                                     |
| ---------------- | ----------------------------------------------- |
| `UNAUTHORIZED`   | Missing or invalid API key                      |
| `INVALID_INPUT`  | Malformed parameters or invalid values          |
| `NOT_FOUND`      | The requested violation or event does not exist |
| `SERVICE_ERROR`  | Backend service failure—retry after a moment    |
| `INTERNAL_ERROR` | Unexpected system error                         |

HTTP-level errors from the API gateway:

| Status                  | Description                                             |
| ----------------------- | ------------------------------------------------------- |
| `401 Unauthorized`      | Invalid or missing API key                              |
| `429 Too Many Requests` | Rate limit or quota exceeded—check `Retry-After` header |

***

### Pagination

Tools that return lists support cursor-based pagination. When more results are available, the response includes a `nextPageToken` field. Pass this value as `pageToken` in your next request to fetch the next page.

Simply ask: "Show me the next page of results"

The AI client handles this automatically when you ask for more results.

***

### Rate Limits

MCP requests share the same rate limits and quotas as the Nightfall REST API. If you receive a `429` response, wait for the duration indicated in the `Retry-After` header before retrying.