# 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 {% stepper %} {% step %} ### Create or open your Nightfall account Log in to the Nightfall Dashboard at {% endstep %} {% step %} ### Navigate to API keys Go to **Developer Platform > API Keys** in the dashboard. {% endstep %} {% step %} ### Generate a new key Click **Generate New Key** and provide a descriptive name (e.g., "Claude MCP Integration"). {% endstep %} {% step %} ### Copy the key Copy the generated key immediately—it will only be shown once. {% endstep %} {% step %} ### Store the key securely Store the key securely (password manager recommended). {% endstep %} {% endstepper %} {% hint style="warning" %} Security Note: Your API key provides full access to your Nightfall data. Never commit it to version control or share it publicly. {% endhint %} *** ## 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` {% code title="claude\_desktop\_config.json" %} ```json { "mcpServers": { "nightfall": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "https://api.nightfall.ai/mcp", "--header", "Authorization: Bearer YOUR_NIGHTFALL_API_KEY" ] } } } ``` {% endcode %} Replace `YOUR_NIGHTFALL_API_KEY` with your actual API key, then restart Claude Desktop. ### Cursor Open **Cursor Settings > MCP** and add: {% code title="cursor\_mcp\_config.json" %} ```json { "mcpServers": { "nightfall": { "url": "https://api.nightfall.ai/mcp", "headers": { "Authorization": "Bearer YOUR_NIGHTFALL_API_KEY" } } } } ``` {% endcode %} ### Windsurf Add to `~/.codeium/windsurf/mcp_config.json`: {% code title="windsurf\_mcp\_config.json" %} ```json { "mcpServers": { "nightfall": { "serverUrl": "https://api.nightfall.ai/mcp", "headers": { "Authorization": "Bearer YOUR_NIGHTFALL_API_KEY" } } } } ``` {% endcode %} ### Custom Integration For custom MCP clients, connect using Streamable HTTP transport: {% code title="HTTP Request Example" %} ``` POST https://api.nightfall.ai/mcp Authorization: Bearer YOUR_NIGHTFALL_API_KEY Content-Type: application/json ``` {% endcode %} 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 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 " * "What files has accessed this week?" * "Track user activity for " ### 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: * Documentation: * Dashboard: * Status Page: ### 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: * Nightfall API Documentation: * Security Best Practices Guide: Available in Nightfall Dashboard > Resources * Video Tutorials: *** ## 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: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= 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: --- # Agent Instructions: 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: ``` GET https://help.nightfall.ai/developer-api/nightfall-mcp-documentation.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.