ms-sentinel-mcp-server

# System Flow Document ## Microsoft Sentinel MCP Server The Microsoft Sentinel MCP Server transforms how security operations teams interact with their Sentinel data by creating a bridge between AI assistants and the wealth of security information stored in Azure. When the server first initializes, it loads its configuration from environment variables, attempting to authenticate with Azure services using the DefaultAzureCredential method. This versatile approach tries multiple authentication methods including environment variables, managed identities, and interactive browser authentication, making the server adaptable to various deployment scenarios. Once authentication succeeds, the server establishes connections to several Azure services simultaneously: the Log Analytics client for querying data, the Security Insights client for managing incidents, and optionally the Log Analytics Management client for workspace configuration. During this initialization phase, the server also dynamically discovers and loads its components from predefined directories. It scans the resources directory, automatically registering any KQL reference materials, examples, and documentation. Similarly, it searches the tools directory to register operational tools like query execution and validation functions, and it checks the prompts directory for conversation templates. This dynamic loading system ensures the server remains extensible, allowing developers to add new capabilities simply by dropping compatible files into the appropriate directories. After initializing all components and establishing Azure connections, the server starts listening for incoming MCP protocol messages. This communication follows the standardized MCP protocol, which defines specific message types for discovering server capabilities, listing available resources and tools, and making requests. The MCP transport layer handles serialization, message routing, and connection management, freeing the server implementation to focus on the actual security functionality. When an AI assistant needs information about available server capabilities, it sends a capabilities request. The server responds with a comprehensive list of its features, indicating support for resources, tools, and prompts. It also communicates which optional features are supported, such as live resource updates or logging. This capabilities exchange forms the foundation for all subsequent interactions, ensuring the client and server understand each other's abilities. For exploration, the AI assistant typically begins by discovering what the server offers. It might request a list of available resources, which would include KQL reference documentation, example security queries, and information about Sentinel tables. Alternatively, it could request a list of available tools or prompts. The server processes these discovery requests by gathering metadata about all registered components and formatting structured responses according to the MCP protocol specification. This discovery phase is crucial for the AI assistant to understand what functionality is available and how to access it. When an actual security investigation begins, the AI often accesses reference materials first. It might request a KQL cheatsheet to understand query syntax or examples of security hunting queries. When the assistant makes such a request, the server looks up the appropriate resource by URI, retrieves its content, and returns it in the specified format (typically Markdown text). These resources are typically static and don't require Azure connectivity, making them reliable even in environments with connectivity issues. The real power becomes evident when security analysts need to explore actual security data. When the analyst asks about recent security incidents, the AI assistant determines it needs to call the incident listing tool. The assistant sends a tool call request specifying the tool name ("sentinel_incidents_list") and parameters like the maximum number of incidents to return or severity filters. The server receives this request, validates the parameters, and then executes the appropriate function. This function authenticates with Azure using the previously established credentials, constructs the appropriate API call to the Security Insights client, and retrieves incident data. If the Azure API call succeeds, the server formats the results and returns them to the assistant. If any errors occur—connection timeouts, authentication failures, permission issues—the server catches these exceptions and returns meaningful error messages that explain the problem. This comprehensive error handling ensures the AI assistant receives actionable information even when operations fail. Query execution follows a similar pattern but introduces additional complexity. When a security analyst wants to search for suspicious login attempts, the AI might determine it needs to run a KQL query. Before executing the query, the assistant may first validate it using the KQL validation tool. This validation tool leverages the Kusto Language library through Python.NET bindings to analyze the query syntax without executing it. The library parses the query, checks for syntax errors, validates references to tables and columns, and returns detailed diagnostic information. If validation succeeds, the assistant proceeds to execute the query. Query execution is one of the most complex operations. When the assistant calls the query execution tool, the server first validates that all required parameters are present. It then converts any time-related parameters from human-readable formats like "7d" (7 days) to the appropriate datetime objects. Next, it establishes the connection to the Log Analytics workspace using the workspace ID from configuration and credentials from initialization. The query executes asynchronously within a task management system that handles timeouts and retries. For long-running queries, the server provides progress updates. When results return, they're processed into a structured format before being sent back to the assistant. Throughout all these operations, the server maintains careful security boundaries. It never returns raw exception traces that might contain sensitive information. It validates all input parameters before using them in Azure API calls. And it carefully manages authentication state to ensure credentials aren't misused or leaked. The server also handles complex operational patterns like paginated results. When retrieving large datasets like incident lists, the server implements pagination logic, making multiple API calls and combining results before returning them to the client. Similarly, for resource-intensive operations, the server implements rate limiting to prevent overloading Azure services. For visualization creation, the server supports a unique workflow. When analysts need to understand their workspace configuration, the assistant calls a workspace visualization prompt. This prompt takes raw workspace information and transforms it into a comprehensive dashboard with explanations of settings, security recommendations, and potential configuration issues. The prompt processing happens within the server, allowing it to apply specialized formatting and domain knowledge before returning the enhanced content to the assistant. In situations where direct Azure connectivity isn't available—perhaps during development or testing—the server gracefully degrades functionality. Core reference materials remain accessible, and some tools implement fallback behaviors that return simulated or cached data. This allows the assistant to maintain a consistent interaction pattern even when backend services are unavailable. When the server needs to shut down—perhaps due to a deployment update or system maintenance—it initiates a graceful shutdown sequence. It cancels any running tasks, closes Azure connections, and releases system resources. This clean shutdown ensures no operations are left hanging and no resources are leaked. Throughout its operation, the server maintains clear boundaries between its components. Resources provide static information, tools perform operations with potential side effects, and prompts define structured conversation patterns. This separation of concerns ensures the server remains maintainable and testable, with each component focused on a specific responsibility. This architectural approach creates a powerful bridge between the structured world of security data and the natural language capabilities of AI assistants, allowing security teams to leverage both simultaneously for more efficient and effective security operations.