Use Cases

May 22, 2026 · View on GitHub

Typical scenarios for using ms-365-admin-mcp-server through an LLM client (Claude Desktop, Claude Code, custom agent, etc.).

Each use case includes:

Context — when to use it
Startup command — recommended preset and flags
Sample prompt — natural-language request to give the LLM
Key tools — MCP tools the LLM will invoke
Risk — relevant for write scenarios

Read-only is the default. Write operations require --allow-writes and are annotated with a risk level (low, medium, high, critical). Use --max-risk-level <level> to cap the exposed tools by risk level (implies --allow-writes) — for example --max-risk-level medium enables low- and medium-risk writes but hides critical operations like wipe-managed-device.

For end-to-end security incident response scenarios with multi-phase procedures, see the playbooks catalogue.

1. Daily security monitoring

Context. Start-of-day triage: review open alerts, incidents, attack simulations in progress, and Secure Score trend.

Startup command.

node dist/index.js --preset security,compliance

Sample prompt.

"Summarize all security alerts from the last 24 hours grouped by severity, list open incidents assigned to my team, and compare today's Secure Score against last week's."

Key tools. list-security-alerts, list-security-incidents, get-security-incident, list-secure-scores, list-secure-score-controls, list-attack-simulations.

2. Incident response — compromised account

Context. A user is suspected compromised (phishing, stolen session, impossible travel). Contain the account, revoke sessions, and confirm the risk state.

Startup command.

node dist/index.js --preset identity,response --allow-writes

Sample prompt.

"User jdoe@contoso.com is compromised. Disable the account, revoke all active sessions, mark the user as confirmed compromised in Identity Protection, and add a note to the related security alert."

Key tools. get-user, disable-user-account (critical), revoke-user-sessions (high), confirm-compromised-users (high), delete-user-phone-auth-method (high), add-security-alert-comment (low).

Context. Investigate unusual authentications: legacy protocols, unknown locations, risky sign-ins, risk detections not yet triaged.

Startup command.

node dist/index.js --preset audit,identity

Sample prompt.

"List sign-ins from the last 7 days where the location is outside Canada or the US, the client is a legacy protocol, or the risk level is medium or higher. Cross-reference with open risk detections and identify the top 5 most exposed users."

Key tools. list-sign-ins, list-risk-detections, list-risky-users, get-risky-user, list-risky-user-history, list-user-auth-methods.

4. Privileged identity hygiene

Context. Quarterly review of Entra privileged roles: who is permanently assigned, who is eligible via PIM, whether each assignment is justified.

Startup command.

node dist/index.js --preset identity,governance

Sample prompt.

"For each Entra ID privileged role (Global Admin, Privileged Role Admin, Security Admin, Exchange Admin, SharePoint Admin), list permanent members and PIM-eligible members. Flag accounts that are not MFA-enrolled or have not signed in for 30+ days."

Key tools. list-directory-roles, list-role-members, list-pim-eligible-assignments, list-pim-active-assignments, list-pim-role-assignment-schedules, list-user-auth-methods, list-sign-ins.

5. Application and credential audit

Context. Detect expiring application secrets, undocumented federated credentials, applications without owners, or OAuth2 grants with excessive scopes.

Startup command.

node dist/index.js --preset identity

Sample prompt.

"List all application registrations with a client secret or certificate expiring in the next 60 days. For each one, provide the owners, federated credentials, and OAuth2 delegated grants. Flag apps without an owner or with privileged Graph API permissions."

Key tools. list-applications, get-application, list-application-owners, list-app-federated-credentials, list-service-principals, list-oauth2-grants, list-sp-delegated-permissions.

6. Guest user governance

Context. Review B2B invitations, inactive guests, and external identity providers.

Startup command.

node dist/index.js --preset identity,governance

Sample prompt.

"List all guest users (userType eq 'Guest'), filter those who have not signed in for 90+ days, and group them by invitation source domain. Also summarize the configured B2X user flows and API connectors."

Key tools. list-users, list-invitations, list-identity-providers, list-b2x-user-flows, list-api-connectors, list-sign-ins.

7. Intune compliance review

Context. Regular review of device fleet: non-compliant devices, policy deviations, outdated configurations.

Startup command.

node dist/index.js --preset intune --max-risk-level low

Intune reports (non-compliance, per-setting, per-policy) use POST endpoints even in read mode, so --allow-writes (or equivalently --max-risk-level low) is required. --max-risk-level low keeps destructive Intune actions (wipe-managed-device, retire-managed-device) out of the tool surface while allowing the reports.

Sample prompt.

"Generate a non-compliance report: list devices that fail at least one compliance policy, group them by OS platform and failing policy, and identify the top 10 most frequently non-compliant settings across the fleet."

Key tools. list-managed-devices, list-compliance-policies, intune-device-noncompliance-report, intune-policy-noncompliance-summary, intune-compliance-setting-noncompliance-report, get-compliance-state-summary.

8. Intune remote actions — lost or compromised device

Context. A user reports a lost mobile device. Locate it, lock it, and if needed retire or wipe it.

Startup command.

node dist/index.js --preset intune,identity --allow-writes

Sample prompt.

"User jdoe@contoso.com lost their iPhone. Find their enrolled devices, locate the iPhone, activate remote lock, and prepare (do not execute) a retire command if the device is not recovered within 24 hours."

Key tools. list-user-devices, get-managed-device, locate-managed-device (low), remote-lock-device (medium), retire-managed-device (high), wipe-managed-device (critical).

Warning: wipe-managed-device and clean-windows-device are critical operations and destroy user data. Always confirm with the user before executing.

9. Service health monitoring

Context. Incident in progress or proactive check: Microsoft service status, active issues, Message Center announcements.

Startup command.

node dist/index.js --preset health

Sample prompt.

"List all active Microsoft service issues affecting Exchange Online, Teams, or SharePoint. Summarize Message Center communications from the last 7 days tagged as action-required."

Key tools. list-service-health, list-service-issues, list-service-messages.

10. Usage reports and license optimization

Context. Monthly governance: adoption rate per service, inactive users, inactive paid licenses.

Startup command.

node dist/index.js --preset reports,identity

Sample prompt.

"Produce a consolidated usage report over 30 days for Teams, Exchange, SharePoint, and OneDrive. Cross-reference with assigned licenses and identify users holding an E5 or Business Premium license who have been inactive on all services for 30+ days."

Key tools. get-teams-activity-report, get-email-activity-report, get-sharepoint-usage-report, get-onedrive-usage-report, get-m365-apps-usage-report, list-subscribed-skus, list-users.

11. eDiscovery — legal investigation

Context. Formal request from Legal or HR: create a Purview eDiscovery case, identify custodians, apply a hold, scope searches.

Startup command.

node dist/index.js --preset ediscovery --allow-writes

Sample prompt.

"Create an eDiscovery case named HR-INV-2026-014. Add users alice@contoso.com and bob@contoso.com as custodians, apply a hold on their mailbox and OneDrive, and create an initial search for messages from 2025-01-01 to 2025-12-31 containing the keyword project-atlas."

Key tools. create-ediscovery-case (medium), create-ediscovery-custodian (medium), apply-hold-ediscovery-custodian (high), create-ediscovery-search (medium), list-ediscovery-searches.

Note: check internal legal authorization before applying a hold. A hold blocks deletion and retention of the user's content.

12. SharePoint administration

Context. Audit sites with excessive external permissions, unused sites, or risky tenant-level settings.

Startup command.

node dist/index.js --preset sharepointadmin

Sample prompt.

"List the top 20 SharePoint sites by storage, and for each list external permissions (guest users, anonymous links). Also pull tenant settings related to external sharing and flag those that do not follow least-privilege."

Key tools. get-sharepoint-settings, list-sharepoint-sites, get-sharepoint-site, list-site-permissions, get-site-permission, get-site-analytics.

13. Advanced threat hunting

Context. Investigate an IOC (indicator of compromise), IP address, suspicious domain, or behavioral pattern across Defender signals.

Startup command.

node dist/index.js --preset security,response --allow-writes

run-hunting-query is an execution tool (POST) but classified low because it is read-only in practice (executes a KQL query, does not modify state).

Sample prompt.

"Run an advanced hunting query to identify all sign-ins or executions originating from the IP 203.0.113.42 in the last 14 days. Cross-reference with threat intelligence articles mentioning this IP and enrich with WHOIS and passive DNS records."

Key tools. run-hunting-query (low), list-threat-intel-articles, list-threat-intel-hosts, get-threat-intel-host-whois, list-passive-dns-records, list-threat-intel-ssl-certs.

14. Access reviews and lifecycle workflows

Context. Entra ID governance: audit ongoing access reviews, apply decisions, check automated join/mover/leaver workflows.

Startup command.

node dist/index.js --preset governance --allow-writes

Sample prompt.

"List all ongoing access review instances, summarize decisions already recorded (approved / denied / not reviewed), and send reminders for reviews closing in the next 3 days. Also list configured lifecycle workflows and their most recent run status."

Key tools. list-access-review-instances, list-access-review-decisions, send-reminder-access-review (low), apply-access-review-decisions (high), list-lifecycle-workflows, get-lifecycle-workflow.

15. Conditional Access — audit and deployment

Context. Review existing Conditional Access policies, detect coverage gaps (users/apps not covered), deploy a new policy from a template.

Startup command.

# Read-only audit
node dist/index.js --preset identity

# Write (policy creation/update)
node dist/index.js --preset identity --allow-writes

Sample prompt (audit).

"List all Conditional Access policies, identify those in report-only mode for 30+ days, and detect applications (service principals) not covered by any policy requiring MFA."

Sample prompt (deploy).

"Create a Conditional Access policy named CA-Block-Legacy-Auth that blocks legacy authentication (ActiveSync, IMAP, POP, SMTP) for all users except the break-glass group. Deploy it in report-only mode initially."

Key tools. list-conditional-access-policies, get-conditional-access-policy, list-named-locations, list-conditional-access-templates, create-conditional-access-policy (high), update-conditional-access-policy (high), create-named-location (medium).

Always deploy a new CA policy in enabledForReportingButNotEnforced first. A misconfigured policy can lock out all users, including admins. Keep a break-glass account excluded from every policy.

16. Intune macOS Platform Scripts — automated deployment

Context. Deploying shell scripts to managed Macs via Intune: wallpaper segmentation, CIS hardening, agent install (Zabbix, BeyondTrust), troubleshooting helpers. Previously required manual portal operations because deviceShellScripts is beta-only and not exposed by most Graph clients.

Startup command.

node dist/index.js --preset intune --allow-writes --max-risk-level high

delete-device-shell-script is high risk. If you only need to push and assign new scripts, run with --max-risk-level medium and elevate only when intentionally removing.

Sample prompt (deploy).

"Create a Platform Script named download-wallpaper-staff-fr that runs as the user, executes once (PT0S), retries 3 times, with blockExecutionNotifications: true. The script body is in ./scripts/wallpaper-fr-staff.sh — base64-encode it before submitting. Once created, assign it to the Entra group Gr-Sec-AAD-INTUNE-MAC-STAFF-FR."

Sample prompt (audit).

"List all macOS Platform Scripts in the tenant. For each, fetch the script content ($select=id,displayName,scriptContent,fileName,runAsAccount), decode the base64, and flag any that contain sudo, curl | bash, or hardcoded credentials."

Sample prompt (rotate).

"The script download-wallpaper-staff-fr needs an updated payload. Read the new version from ./scripts/wallpaper-fr-staff-v2.sh, base64-encode it, and PATCH the existing script via update-device-shell-script. Do not touch the assignments — they stay as-is."

Key tools. list-device-shell-scripts, get-device-shell-script, create-device-shell-script (medium), update-device-shell-script (medium), delete-device-shell-script (high), assign-device-shell-script (medium).

Gotcha — assign is REPLACE, not ADD. assign-device-shell-script overwrites all existing assignments with the body's list. To add a group without removing others, first GET the current assignments (via the script's groupAssignments navigation property), append your new target, then POST the merged list.

Gotcha — base64 + LF. scriptContent is strict base64 of a script with LF line endings. CRLF will break execution on the Mac. Encode with Buffer.from(fs.readFileSync(path,'utf8').replace(/\r\n/g,'\n')).toString('base64').

Gotcha — beta endpoint. This family lives in /beta/deviceManagement/.... Microsoft documents the beta endpoint as "not intended for production" but the Intune portal itself calls it under the hood. Treat as production-validated; track Microsoft's API changelog for surprises.

17. Intune Remediations (Windows detect-and-fix)

Context. Deploying paired detection + remediation PowerShell scripts to Windows 10/11 Azure AD joined devices: CIS hardening verification, agent install verification, service state checks, BitLocker / TPM checks, registry hardening. Modern replacement for deviceManagementScripts (one-shot Windows PS) when the desired pattern is "verify state, fix if broken".

Startup command.

node dist/index.js --preset intune --allow-writes --max-risk-level high

Sample prompt (deploy).

"Create a Remediation named Verify-Zabbix-Agent-Running (publisher LCI). Detection script in ./detect-zabbix.ps1 returns 0 if service is Running, 1 otherwise. Remediation script in ./remediate-zabbix.ps1 (re)starts and re-enables the service. Both base64-encode before submitting. runAsAccount=system. Assign to Gr-Sec-AAD-INTUNE-WIN-STAFF with a daily 03:00 schedule, runRemediationScript=true."

Sample prompt (audit).

"List all Remediations in the tenant. For each, fetch detectionScriptContent and remediationScriptContent, decode the base64, and flag any with hardcoded credentials, plaintext URLs to S3/blob storage, or Set-ExecutionPolicy Bypass."

Sample prompt (detect-only).

"Create a detection-only Remediation named Verify-FileVault-Enabled — empty remediation script, runRemediationScript=false in the assignment. Use it as a reporting probe across Gr-Sec-AAD-INTUNE-MAC-ALL. Then query getRemediationSummary after 48h to see how many devices reported non-compliance."

Key tools. list-device-health-scripts, get-device-health-script, create-device-health-script (medium), update-device-health-script (medium), delete-device-health-script (high), assign-device-health-script (medium).

Gotcha — base64 each side. detectionScriptContent AND remediationScriptContent are each strict base64 of UTF-8 PowerShell. Both must be valid even if remediation is a no-op (use a single-line Exit 0).

Gotcha — runRemediationScript flag. Set in the assignment, not the script. Same script can be deployed as detect-only to one group and detect-and-remediate to another.

Gotcha — schedule kinds. deviceHealthScriptDailySchedule, deviceHealthScriptHourlySchedule, deviceHealthScriptRunOnceSchedule. Daily is the default Intune portal experience.

Gotcha — Windows only. macOS uses deviceShellScripts (one-shot, no detect-fix pair). Don't try to deploy a Remediation to a Mac group — Intune will silently ignore it.

18. Intune assignment filters — scope without group sprawl

Context. A policy or app needs to target only a sub-set of a group: "Macs Sonoma+ only", "iPhones supervised only", "Windows 11 23H2+ only", "corporate-owned only". Without filters, you'd create a new Entra group for every variant, leading to dozens of overlapping memberships and sync lag from Aquera/Entra. Filters let one group + one filter rule cover the same scope, evaluated at assignment time by Intune.

Startup command.

node dist/index.js --preset intune --allow-writes --max-risk-level medium

Deleting a filter currently referenced by an assignment is high risk (silently broadens the assignment to "all members") — keep that out of routine runs.

Sample prompt (create + use).

"Create an assignment filter named macOS-Sonoma-Plus with platform=macOS and rule (device.osVersion -startsWith \"14\") -or (device.osVersion -startsWith \"15\"), assignmentFilterManagementType=devices. Then update the configuration profile Wallpaper-Staff-FR to add this filter to its assignment to Gr-Sec-AAD-INTUNE-MAC-STAFF-FR."

Sample prompt (audit).

"List all assignment filters. For each, list the policies/apps that currently reference it (search across deviceConfigurations, configurationPolicies, mobileApps assignments). Flag any filter with zero references — those are dead and safe to delete."

Sample prompt (refactor).

"We have 8 groups named Gr-AAD-MAC-Sonoma, Gr-AAD-MAC-Sequoia, etc. — one per macOS version. Audit which Intune policies use them, then propose a refactor: replace each version-specific group with the parent Gr-AAD-MAC-ALL + an assignment filter using device.osVersion. Don't apply changes — just produce a migration plan."

Key tools. list-assignment-filters, get-assignment-filter, create-assignment-filter (medium), update-assignment-filter (medium), delete-assignment-filter (high).

Gotcha — rule syntax. KQL-like, but quoting differs. Single quotes inside the rule must be escaped or use \". Test rules in the Intune portal "Preview filter" UI before automating large rollouts.

Gotcha — silent broadening on delete. Deleting a filter referenced by an assignment doesn't reject the delete or update the assignment — it just removes the filter, so the assignment now targets the whole group. Audit references first.

Gotcha — assignmentFilterManagementType is fixed. Once created with devices or apps, you can't switch. Pick based on what the filter will scope (device-scoped policies vs. app-scoped policies have slightly different property sets).

Gotcha — beta endpoint. Like other Intune resources, lives in /beta/. See §16 disclaimer.

General recommendations

Least-privilege preset

Do not load --preset all by default. Each preset loads fewer tools in the LLM context, which:

reduces the risk of unintended invocations,
improves LLM tool-selection accuracy,
lowers cost (context tokens).

Read-only by default

Always start read-only. When mutations are required, prefer --max-risk-level <level> over --allow-writes to cap at the lowest level that unlocks the scenario (e.g. medium for most incident-response flows; reserve critical for deliberate retire/wipe/delete work). Combine with ENABLED_TOOLS (regex) for even finer filtering.

Validate before writing

For any high or critical tool, instruct the LLM to:

dry-run (list affected entities),
confirm with the operator,
then execute.

Example prompt pattern:

"Before disabling the account, show me the user's details, their last 5 sign-ins, and their group memberships. Wait for my confirmation before calling disable-user-account."

Traceability

All writes are logged by Graph API (directory audits, Intune audit events, CA policy audits, Cloud PC audit events). After an incident response, always produce a report by querying list-directory-audits or list-intune-audit-events filtered on the operation window.

Automate tenant-specific limits

Use MS365_ADMIN_MCP_MAX_TOP to cap paging and avoid scan timeouts on large tenants (>10k users or >50k devices).