Article

    Nightfall MCP Documentation | Developer APIs | Nightfall Documentation

    11 min read
    Last updated 1 month ago

    Nightfall MCP Documentation | Developer APIs

    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

    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

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

    Cursor

    Open Cursor Settings > MCP and add:

    Windsurf

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

    Custom Integration

    For custom MCP clients, connect using Streamable HTTP transport:

    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.

    Exfiltration Events (4 tools)

    Investigate data exfiltration attempts and suspicious file activity.

    Security Posture Events (4 tools)

    Monitor configuration risks and permission changes.

    Activity Tools (2 tools)

    Track user and asset activity across all event types.

    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 jane@example.com 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

    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:

    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

    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:

    Common Query Patterns

    Find violations by user and integration:

    Search across multiple users:

    Filter by channel and state:

    Time-based queries:

    Error Handling

    The MCP server returns structured errors in tool responses:

    HTTP-level errors from the API gateway:

    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: support@nightfall.ai