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

Create entity package in internal/entities/
Implement Entity interface
Define schema with field priorities
Register via init() function
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