> 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 16 specialized tools organized into four categories:

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

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

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

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

Investigate data exfiltration attempts and suspicious file activity.

| Tool Name                              | Description                                      |
| -------------------------------------- | ------------------------------------------------ |
| **search\_exfiltration\_events**       | Search exfiltration events with advanced filters |
| **list\_exfiltration\_events**         | Browse recent exfiltration events                |
| **get\_exfiltration\_event**           | Get complete event details and affected assets   |
| **get\_exfiltration\_event\_activity** | View event timeline and status changes           |

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

Monitor configuration risks and permission changes.

| Tool Name                         | Description                        |
| --------------------------------- | ---------------------------------- |
| **search\_posture\_events**       | Search for security posture issues |
| **list\_posture\_events**         | Browse recent posture events       |
| **get\_posture\_event**           | Get detailed event information     |
| **get\_posture\_event\_activity** | View event activity history        |

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

Track user and asset activity across all event types.

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

### 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.nightfall.ai/developer-api/nightfall_apis/nightfall-model-context-protocol-mcp-server/available-tools.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.