MDI MCP Server

A Model Context Protocol (MCP) server that integrates with Microsoft Defender for Identity (MDI) via the Microsoft Graph API. Use it with VS Code + GitHub Copilot to query MDI data and generate styled HTML reports — all from natural language.

Features

Related MCP server: LegacyMCP

Prerequisites

1. Python 3.10+

2. Azure AD App Registration with the following Application permissions:

   • SecurityAlert.Read.All

   • SecurityIncident.Read.All

   • SecurityEvents.Read.All

   • IdentityRiskyUser.Read.All

   • IdentityRiskEvent.Read.All

   • ThreatHunting.Read.All

   Grant admin consent after adding the permissions.

3. VS Code with GitHub Copilot extension installed.

Quick Start

1. Clone and install

git clone https://github.com/TigerToker/mdi-mcp-server.git
cd mdi-mcp-server
pip install -e .

2. Configure credentials

Copy .env.example to .env and fill in your Azure AD app registration details:

cp .env.example .env
# Edit .env with your AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET

3. Connect to VS Code + Copilot

The repo includes .vscode/mcp.json which auto-registers the server. Open the project folder in VS Code and Copilot will detect the MCP server.

Alternatively, add this to your User settings.json for global access:

"mcp": {
    "servers": {
        "mdi-mcp-server": {
            "type": "stdio",
            "command": "python",
            "args": ["-m", "mdi_mcp_server.server"],
            "cwd": "/path/to/mdi-mcp-server/src",
            "env": {
                "AZURE_TENANT_ID": "your-tenant-id",
                "AZURE_CLIENT_ID": "your-client-id",
                "AZURE_CLIENT_SECRET": "your-client-secret"
            }
        }
    }
}

4. Start asking questions

In Copilot Chat, try:

• "Show me all high-severity MDI alerts from the last week"

• "Generate a comprehensive MDI report for the past 30 days"

• "Are there any risky users in my tenant?"

• "What's the health status of our MDI sensors?"

• "Run an Advanced Hunting query for failed logon attempts"

Project Structure

mdi-mcp-server/
├── src/mdi_mcp_server/
│   ├── server.py              # MCP server entry point & tool definitions
│   ├── graph_client.py        # Microsoft Graph API client
│   ├── report_generator.py    # Jinja2-based HTML report builder
│   └── templates/
│       └── report.html        # Dark-themed HTML report template
├── .vscode/mcp.json           # VS Code MCP server configuration
├── .github/copilot-instructions.md
├── pyproject.toml
├── requirements.txt
└── .env.example

Available MCP Tools

Query Tools

Report Generation Tools

Required Graph API Permissions

GitHub Copilot Extension

This project also ships as a GitHub Copilot Extension — a standalone agent that responds to natural-language queries about MDI directly inside GitHub Copilot Chat.

How It Works

The extension runs a FastAPI server that implements the GitHub Copilot Extensions agent protocol. When you @mention the extension in Copilot Chat, your message is routed to the /agent endpoint, which parses your intent, queries the Graph API, and streams back a markdown response.

Running Locally

# Install dependencies
pip install -e .

# Set environment variables
export AZURE_TENANT_ID="your-tenant-id"
export AZURE_CLIENT_ID="your-client-id"
export AZURE_CLIENT_SECRET="your-client-secret"
export GITHUB_WEBHOOK_SECRET="your-webhook-secret"

# Start the server
uvicorn mdi_mcp_server.copilot_extension:app --host 0.0.0.0 --port 8080 --app-dir src

Docker

docker build -t mdi-copilot-extension .
docker run -p 8080:8080 \
  -e AZURE_TENANT_ID="..." \
  -e AZURE_CLIENT_ID="..." \
  -e AZURE_CLIENT_SECRET="..." \
  -e GITHUB_WEBHOOK_SECRET="..." \
  mdi-copilot-extension

Deploy to Azure Container Apps

Use the provided deployment script:

.\deploy.ps1 -ResourceGroup "mdi-copilot-rg" -AcrName "myacr"

Or deploy manually via Bicep:

az deployment group create \
  --resource-group mdi-copilot-rg \
  --template-file infra/main.bicep \
  --parameters containerImage="myacr.azurecr.io/mdi-copilot-extension:latest" \
               azureTenantId="..." azureClientId="..." \
               azureClientSecret="..." githubWebhookSecret="..."

Register the Extension

1. Go to GitHub Settings → Developer Settings → GitHub Apps → Copilot Extensions

2. Create a new Copilot Extension (or GitHub App with Copilot agent)

3. Set the Agent URL to your deployed endpoint: https://<your-app>.azurecontainerapps.io/agent

4. Set the Webhook Secret to match GITHUB_WEBHOOK_SECRET

5. Install the app on your organization or account

Extension Commands

Once installed, use @mdi (or your extension name) in Copilot Chat:

• @mdi show me high severity alerts from the last 7 days

• @mdi generate a full MDI report for the past 30 days

• @mdi are there any risky users?

• @mdi what's our secure score?

• @mdi check MDI sensor health

License

MIT