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:[email protected] AND integration_name:slack

Search across multiple users:

user_email:[email protected] OR user_email:[email protected]

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.