AI‑Powered Troubleshooting for Microsoft Purview Data Lifecycle Management

Announcing the DLM Diagnostics MCP Server!

Microsoft Purview Data Lifecycle Management (DLM) policies are critical for meeting compliance and governance requirements across Microsoft 365 workloads. However, when something goes wrong – such as retention policies not applying, archive mailboxes not expanding, or inactive mailboxes not getting purged – diagnosing the issue can be challenging and time‑consuming.

To simplify and accelerate this process, we are excited to announce the open‑source release of the DLM Diagnostics Model Context Protocol (MCP) Server, an AI‑powered diagnostic server that allows AI assistants to safely investigate Microsoft Purview DLM issues using read‑only PowerShell diagnostics.

GitHub repository:
https://github.com/microsoft/purview-dlm-mcp

The troubleshooting challenge

When you notice issues such as:

• “Retention policy shows Success, but content isn’t being deleted”
• “Archiving is enabled, but items never move to the archive mailbox”

The investigation typically involves:

• Connecting to Exchange Online and Security & Compliance PowerShell sessions
• Running 5–15 diagnostic cmdlets in a specific order
• Interpreting command output using multiple troubleshooting reference guides (TSGs)
• Correlating policy distribution, holds, archive configuration, and workload behavior
• Producing a root‑cause summary and recommended remediation steps

This workflow requires deep familiarity with DLM internals and is largely manual.

Introducing the DLM Diagnostics MCP Server

The DLM Diagnostics MCP Server automates this diagnostic workflow by allowing AI assistants – such as GitHub Copilot, Claude Desktop, and other MCP‑compatible clients – to investigate DLM issues step by step.

An administrator simply describes the symptom in natural language. The AI assistant then:

• Executes read‑only PowerShell diagnostics
• Evaluates results against known troubleshooting patterns
• Identifies likely root causes
• Presents recommended remediation steps (never executed automatically)
• Produces a complete audit trail of the investigation

All diagnostics are performed under a strict security model to ensure safety and auditability.

What is the Model Context Protocol (MCP)?

The Model Context Protocol (MCP) is an open standard that enables AI assistants to interact with external tools and data sources in a secure and structured way.

You can think of MCP as a “USB port for AI”:

• Any MCP‑compatible client can connect to an MCP server
• The server exposes well‑defined tools
• The AI can use those tools safely and deterministically

The DLM Diagnostics MCP Server exposes Purview DLM diagnostics as MCP tools, enabling AI assistants to run PowerShell diagnostics, retrieve execution logs, and surface Microsoft Learn documentation.

More information: https://modelcontextprotocol.io

Diagnostic tools exposed by the server

The server exposes four MCP tools.

1. Run read‑only PowerShell diagnostics

This tool executes PowerShell commands against Exchange Online and Security & Compliance sessions using a strict allow list.

Only read‑only cmdlets are permitted:

• Allowed verbs: Get-*, Test-*, Export-*
• Blocked verbs: Set-*, New-*, Remove-*, Enable-*, Invoke-*, and others

Every command is validated before execution.

Example: Archive mailbox not working

Admin:

“Archiving is not working for john.doe@contoso.com”

The AI follows the archive troubleshooting guide:

 

 

 

 

 

Finding
The archive mailbox is not enabled.

Recommended action (not executed automatically):

 

All remediation steps are presented as text only for administrator review.

 

 

2. Retrieve the execution log

Every diagnostic session is fully logged, including:

• Command executed
• Timestamp
• Duration
• Status
• Output

Admins can retrieve the complete investigation as a Markdown‑formatted audit trail, making it easy to attach to incident records or compliance documentation.

 

 

 

3. Microsoft Learn documentation lookup

If a question does not match a diagnostic scenario – such as “How do I create a retention policy?” – the server falls back to curated Microsoft Learn documentation. The documentation lookup covers 11 Purview areas, including:

• Retention policies and labels
• Archive and inactive mailboxes
• eDiscovery
• Audit
• Communication compliance
• Records management
• Adaptive scopes

 

 

4. Create a GitHub issue (create_issue)

create_issue lets the assistant open a feature request in the project’s GitHub repo and attach key session details (such as the commands run and any failures) to help maintainers reproduce and prioritize the request.

Example: File a feature request from a failed diagnostic

 

Security and safety model

Security is enforced at multiple layers:

• Read‑only allow list: Only approved diagnostic cmdlets can run
• No stored credentials: Authentication uses MSAL interactive sign‑in
• Session isolation: Each server instance runs in its own PowerShell process
• Full audit trail: Every command and result is logged
• No automatic remediation: Fixes are never executed by the server

This design ensures diagnostics are safe to run even in sensitive compliance environments.

Supported diagnostic scenarios

The server currently includes 12 troubleshooting reference guides, covering common DLM issues such as:

• Retention policy shows Success but content is not retained or deleted
• Policy status shows Error or PolicySyncTimeout
• Items do not move to archive mailbox
• Auto‑expanding archive not triggering
• Inactive mailbox creation failures
• SubstrateHolds and Recoverable Items growth
• Teams messages not deleting
• Conflicts between MRM and Purview retention
• Adaptive scope misconfiguration
• Auto‑apply label failures
• SharePoint site deletion blocked by retention
• Unified Audit Configuration validation

Each guide maps symptoms to diagnostic checks and remediation guidance.

Getting started

Prerequisites

• Node.js 18 or later
• PowerShell 7
• ExchangeOnlineManagement module (v3.4+)
• Exchange Online administrator permissions

Required permissions

 

• Exchange Online (Connect-ExchangeOnline): cmdlets like Get-Mailbox, Get-MailboxStatistics, Export-MailboxDiagnosticLogs, Get-OrganizationConfig
• Security & Compliance (Connect-IPPSSession): cmdlets like Get-RetentionCompliancePolicy, Get-RetentionComplianceRule, Get-AdaptiveScope, Get-ComplianceTag

Exchange cmdlets require EXO roles; compliance cmdlets require S&C roles. Without both, some diagnostics will fail with permission errors.

Why both workloads?
The server connects to two PowerShell sessions: The authenticating user (DLM_UPN) needs read access to both Exchange Online and Security & Compliance PowerShell sessions.

 

MCP client configuration

The server can be connected to IDE like Claude Desktop or Visual Studio Code (GitHub Copilot) using MCP configuration.

Include this configuration in your MCP config JSON file (for VS Code, use .vscode/mcp.json; for Claude Desktop, use claude_desktop_config.json)

 

Summary

The DLM Diagnostics MCP Server brings AI‑assisted, auditable, and safe troubleshooting to Microsoft Purview Data Lifecycle Management. By combining structured troubleshooting guides with read‑only PowerShell diagnostics and MCP, it significantly reduces the time and expertise required to diagnose complex DLM issues.

We invite you to try it out, provide feedback, and contribute to the project via GitHub.

GitHub repository:
https://github.com/microsoft/purview-dlm-mcp

Rishabh Kumar, Victor Legat & Purview Data Lifecycle Management Team