Microsoft Graph Security MCP Server

A Model Context Protocol (MCP) server implementation for Microsoft Graph Security APIs, providing intelligent field selection and token optimisation for AI assistant interactions.

Overview

This server implements the Model Context Protocol to expose Microsoft Graph Security APIs (alerts, incidents) to MCP-compatible AI assistants. It includes intelligent field selection using native Graph API $select parameters to reduce response sizes and token usage.

Key Features

• Universal Tools: 10 tools that work consistently across security entity types
• Field Selection: Automatic optimization using Microsoft Graph $select parameters
• Intent Detection: Query analysis to determine appropriate response detail level
• TTL Context Caching: Reduces redundant context provision
• Authentication: Support for Azure AD app credentials and managed identity
• Thread Safety: Concurrent request handling with proper synchronization

Architecture

┌─────────────────┐    ┌──────────────┐    ┌─────────────────┐    ┌─────────────────┐
│ MCP Client      │    │ MCP Server   │    │ Universal       │    │ Microsoft       │
│ (AI Assistant)  │◄──►│ (This Tool)  │◄──►│ Graph Client    │◄──►│ Graph Security  │
└─────────────────┘    └──────────────┘    └─────────────────┘    └─────────────────┘

Core Components

• MCP Server (internal/mcp): Handles JSON-RPC 2.0 protocol communication
• Universal Client (internal/graph/framework): Graph API abstraction with field selection
• Entity System (internal/entities): Schema definitions with field priority metadata
• Context Management (internal/context): TTL-based context optimization
• Authentication (internal/auth): Azure AD credential handling

Installation

Prerequisites

• Go 1.21 or later
• Azure AD application with Graph Security permissions
• Microsoft Graph Security data (Defender for Endpoint, etc.)

Build from Source

git clone https://github.com/LaurieRhodes/MCP-GraphSecurityIncidents.git
cd MCP-GraphSecurityIncidents
go build -o graph-security-incidents.exe ./cmd/server

Configuration

Required Azure Permissions

Grant these Microsoft Graph permissions to your Azure AD application:

SecurityAlert.Read.All
SecurityAlert.ReadWrite.All  
SecurityIncident.Read.All
SecurityIncident.ReadWrite.All

Configuration File

Create config.json:

{
  "auth": {
    "type": "app",
    "tenant": "your-tenant-id",
    "clientId": "your-client-id", 
    "clientSecret": "your-client-secret"
  },
  "graph": {
    "apiVersion": "beta",
    "endpoint": "https://graph.microsoft.com",
    "requestTimeout": 30,
    "security": {
      "alertsApiVersion": "v2",
      "incidentsApiVersion": "v1"
    }
  },
  "server": {
    "name": "mcp-graph-security-incidents",
    "version": "1.0.0"
  }
}

MCP Client Configuration

Add to your MCP client configuration:

{
  "mcpServers": {
    "graph-security": {
      "command": "/path/to/graph-security-incidents",
      "args": []
    }
  }
}

Note that Claude is a poor LLM for management of Security data due to its safety protocols preventing sensitive data to be divulged. LLM Testing Results: Provides detailed analysis of current LLM with tool using capabilities against this MCP server.

Available Tools

Universal Entity Tools

Tool	Description	Parameters
graph_entity_list	List security entities	entityType, filter, top, orderBy, intent
graph_entity_get	Get specific entity	entityType, entityId, expand
graph_entity_update	Update entity properties	entityType, entityId, properties
graph_entity_comment	Add comment to entity	entityType, entityId, comment
graph_entity_navigate	Navigate entity relationships	sourceEntityType, sourceEntityId, targetEntityType
graph_entity_list_next	Get next page of results	nextLink
graph_entity_schema	Get entity schema info	entityType, operation

Context Management Tools

Tool	Description	Parameters
context_discover	Discover entity capabilities	entityType, focusArea
context_stats	Get context usage statistics	None
context_configure	Configure context behavior	action, level, seconds, toolName

Supported Entity Types

• alert: Microsoft Graph Security alerts
• incident: Microsoft Graph Security incidents

Field Selection System

Query Intents

The server automatically detects query intent and selects appropriate fields:

type QueryIntent string

const (
    IntentOverview  QueryIntent = "overview"  // Essential fields only
    IntentStandard  QueryIntent = "standard"  // Essential + operational fields  
    IntentComplete  QueryIntent = "complete"  // All fields
)

Field Priorities

Fields are categorized by priority for selection optimization:

• Essential: Core identification fields (id, displayName, severity, status)
• Standard: Operational fields (dates, assignment, classification)
• Complete: All remaining fields (descriptions, evidence, comments)

Context Management

TTL-Based Optimization

Context is provided based on time-to-live (TTL) settings:

• Default TTL: 1 hour
• Context Levels: none, minimal, standard, complete
• Per-Tool Tracking: Independent TTL for each tool

## Development

Project Structure

├── cmd/server/           # Main server entry point
├── internal/
│   ├── auth/            # Authentication implementations
│   ├── config/          # Configuration management
│   ├── context/         # Smart context management
│   ├── entities/        # Entity system and schemas
│   ├── graph/           # Microsoft Graph client
│   ├── mcp/             # MCP protocol implementation
│   ├── schemas/         # Legacy schema definitions
│   ├── tools/           # Tool registration and schemas
│   └── utils/           # Utility functions
├── docs/                # Documentation
└── config.example.json  # Example configuration

Adding New Entity Types

1. Create entity package in internal/entities/
2. Implement Entity interface
3. Define schema with field priorities
4. Register via init() function
5. Add context providers and validators

Building

go build -o graph-security-incidents ./cmd/server

Documentation

• Architecture: Technical design and implementation details
• Configuration: Complete configuration reference
• API Reference: Detailed tool documentation
• Getting Started: Setup and usage guide

Contributing

This is a personal development and I doubt there is much interest in extending this framework to a full community development project.

License

This project is licensed under the MIT License - see LICENSE file for details.

Related Projects

• Model Context Protocol: Protocol specification
• MCP CLI: Command-line MCP client