Nightfall MCP Documentation

Overview

The Nightfall MCP (Model Context Protocol) server enables AI assistants like Claude, ChatGPT, and Cursor to interact directly with your Nightfall security data. Instead of navigating dashboards or running API queries manually, you can use natural language to investigate violations, search for exfiltration events, review security posture, and take remediation actions.

Key Benefits

• Natural Language Interface: Ask questions in plain English instead of learning complex query syntax

• Faster Investigations: Get instant answers to security questions without switching between tools

• Workflow Integration: Access Nightfall data directly in your development and collaboration environments

• Automated Analysis: Let AI help you identify patterns, summarize findings, and recommend actions

Technical Specifications

Property	Value
Endpoint	https://api.nightfall.ai/mcp
Protocol	MCP Streamable HTTP (JSON-RPC 2.0)
Authentication	Bearer token (Nightfall API key)
Available Tools	16 integrated security operations tools

---

Getting Started

Prerequisites

Before connecting to the Nightfall MCP server, ensure you have:

• An active Nightfall subscription with appropriate permissions

• A Nightfall API key from the Developer Platform

• An MCP-compatible AI client (Claude Desktop, Cursor, Windsurf, or custom)

Generating Your API Key

1

Create or open your Nightfall account

Log in to the Nightfall Dashboard at https://app.nightfall.ai

2

Navigate to API keys

Go to Developer Platform > API Keys in the dashboard.

3

Generate a new key

Click Generate New Key and provide a descriptive name (e.g., "Claude MCP Integration").

4

Copy the key

Copy the generated key immediately—it will only be shown once.

5

Store the key securely

Store the key securely (password manager recommended).

Security Note: Your API key provides full access to your Nightfall data. Never commit it to version control or share it publicly.

---

Connecting Your AI Client

The Nightfall MCP server supports any MCP-compatible client. Below are configuration examples for popular AI tools.

Claude Desktop

Add the following configuration to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "nightfall": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://api.nightfall.ai/mcp",
        "--header",
        "Authorization: Bearer YOUR_NIGHTFALL_API_KEY"
      ]
    }
  }
}

Replace YOUR_NIGHTFALL_API_KEY with your actual API key, then restart Claude Desktop.

Cursor

Open Cursor Settings > MCP and add:

cursor_mcp_config.json

{
  "mcpServers": {
    "nightfall": {
      "url": "https://api.nightfall.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_NIGHTFALL_API_KEY"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

windsurf_mcp_config.json

{
  "mcpServers": {
    "nightfall": {
      "serverUrl": "https://api.nightfall.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_NIGHTFALL_API_KEY"
      }
    }
  }
}

Custom Integration

For custom MCP clients, connect using Streamable HTTP transport:

HTTP Request Example

POST https://api.nightfall.ai/mcp
Authorization: Bearer YOUR_NIGHTFALL_API_KEY
Content-Type: application/json

The server operates in stateless mode and returns application/json responses.

---

Available Tools

The Nightfall MCP server provides 16 specialized tools organized into four categories.

DLP Violations (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.)

Exfiltration Events (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

Security Posture Events (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

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

---

Common Use Cases

Here are real-world scenarios where the Nightfall MCP server delivers immediate value.

Security Investigations

Example: "Show me all active high-risk violations from GitHub in the last week"

The AI automatically uses search_violations with appropriate filters and returns results in seconds. You can then ask follow-up questions like "Which repository has the most violations?" or "Show me the sensitive data found in violation abc-123" without manually constructing queries.

Insider Threat Response

Example: "What has user [email protected] been doing in the last 30 days?"

Get a complete timeline of user activity including file downloads, permission changes, and policy violations. The AI summarizes patterns and flags anomalies automatically.

Bulk Remediation

Example: "Resolve all pending Slack violations from the #general channel"

Instead of manually processing violations one by one, describe the action in natural language. The AI finds matching violations and executes the appropriate remediation action.

Compliance Reporting

Example: "Generate a summary of all HIPAA violations this quarter grouped by department"

The AI retrieves relevant data, performs grouping and aggregation, and creates a formatted report—all from a single request.

Data Exfiltration Detection

Example: "Are there any exfiltration events involving bulk downloads from Google Drive?"

Quickly identify potential data theft attempts by searching for specific event patterns across your cloud storage integrations.

Permission Audits

Example: "List all posture events with permission changes this month"

Monitor access control changes across your environment to identify security configuration drift or policy violations.

---

Query Examples

These examples demonstrate the flexibility of natural language queries. You don't need to memorize syntax—just describe what you need.

Basic Searches

• "Show me today's violations"

• "List high-risk violations in the last 7 days"

• "Find violations in the engineering-team Slack channel"

• "What GitHub repositories have violations?"

User-Specific Queries

• "Show violations by [email protected]"

• "What files has [email protected] accessed this week?"

• "Track user activity for [email protected]"

Integration-Specific

• "Find all Salesforce violations in the Sales org"

• "Show Google Drive files shared externally"

• "List Confluence pages with public links"

• "Check Microsoft Teams for sensitive data sharing"

Advanced Analysis

• "Compare violation trends month over month"

• "Identify users with the most violations"

• "What types of sensitive data are most commonly exposed?"

• "Summarize security posture improvements over the last quarter"

Remediation Actions

• "Mark these violations as resolved"

• "Block access to this file"

• "Delete violations in test channels"

• "Quarantine all high-risk violations from last month"

---

Best Practices

Security

• Store API keys in secure credential managers, never in code or configuration files committed to version control

• Rotate API keys quarterly or immediately if compromise is suspected

• Use dedicated API keys for each integration rather than sharing across systems

• Review API key permissions regularly and follow least-privilege principles

• Enable audit logging in your AI client to track MCP queries for compliance

Query Optimization

• Start with broader queries and refine based on results rather than trying to construct perfect queries immediately

• Use date ranges to limit result sets when investigating recent incidents

• Ask for pagination when dealing with large result sets to avoid overwhelming responses

• Combine filters naturally: "high-risk GitHub violations from last week" is more efficient than multiple separate queries

Effective Communication with AI

• Be specific about time ranges: "last 7 days" is clearer than "recently"

• Use exact usernames or email addresses when investigating specific actors

• Ask follow-up questions to drill deeper: "Show me the findings" after reviewing a violation

• Request summaries for complex data: "Summarize these violations by severity"

• Clarify formatting preferences: "Show as a table" or "Give me a bullet list"

Workflow Integration

• Set up dedicated Slack/Teams channels for security alerts and use MCP to investigate directly from your collaboration tool

• Create saved prompts for common investigations to maintain consistency across your security team

• Document investigation procedures that leverage MCP for faster onboarding of new analysts

• Use MCP in conjunction with the Nightfall dashboard for comprehensive security operations

---

Troubleshooting

Connection Issues

Problem: "Unauthorized" or 401 errors

Solutions:

• Verify your API key is correctly pasted in the configuration file (no extra spaces)

• Check that the API key hasn't expired or been revoked in the Nightfall dashboard

• Ensure you're using "Bearer YOUR_KEY" format, not just "YOUR_KEY"

• Restart your AI client after updating the configuration

Problem: MCP server not appearing in client

Solutions:

• Verify the configuration file is in the correct location for your operating system

• Check JSON syntax is valid (use a JSON validator if needed)

• For Claude Desktop: ensure npx is installed (requires Node.js)

• Review client logs for specific error messages

Query Issues

Problem: No results returned

Solutions:

• Broaden your time range (data may be older than expected)

• Check filter criteria aren't too restrictive

• Verify the integration or resource name is spelled correctly

• Confirm you have violations/events matching your criteria in the Nightfall dashboard

Problem: Rate limit errors (429)

Solutions:

• Wait for the duration specified in the Retry-After header

• Reduce query frequency or batch similar requests

• Contact Nightfall support if hitting limits during normal usage

Performance

Problem: Slow query responses

Solutions:

• Use more specific filters to reduce result set size

• Limit date ranges to recent periods when possible

• Request paginated results for large datasets

• Complex aggregations may take longer—this is expected behavior

---

Support and Resources

Getting Help

If you encounter issues not covered in this guide:

• Email Support: [email protected]

• Documentation: https://docs.nightfall.ai

• Dashboard: https://app.nightfall.ai

• Status Page: https://status.nightfall.ai

Providing Feedback

We continuously improve the MCP server based on customer feedback. Please share:

• Feature requests for new query capabilities

• Use cases we should highlight in documentation

• Integration challenges or configuration pain points

• Success stories of how MCP improves your security operations

Additional Learning Resources

• Model Context Protocol Specification: https://modelcontextprotocol.io

• Nightfall API Documentation: https://docs.nightfall.ai/reference

• Security Best Practices Guide: Available in Nightfall Dashboard > Resources

• Video Tutorials: https://nightfall.ai/resources/videos

---

Appendix: Query Field Reference

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

DLP Violation 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

Exfiltration Event 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

Security Posture Event 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.

---

© 2025 Nightfall AI, Inc. All rights reserved.

For questions or support: [email protected]