entraadm MCP

entraadm-mcp

English | 日本語

MCP server for Microsoft Entra ID sign-in and audit-log triage, plus the two Azure-side questions a morning patrol asks with the same credential: are our Azure VMs backed up, and is Microsoft 365 itself degraded right now. Read-only, except for one opt-in tool that signs a compromised account out everywhere.

Why this instead of the official Microsoft MCP Server for Enterprise

Microsoft ships an official MCP Server for Enterprise for Entra ID data. It is a good fit for an interactive admin at a keyboard, and is not a fit for an unattended triage bot:

• Delegated auth only. The official server does not support app-only (client credentials) auth, so it cannot run headless behind a service account. entraadm-mcp is built for that case: app-only in production, with a delegated (az login) fallback for local development.
• A general-purpose Graph query tool, not a fixed tool set. The official server exposes one tool that lets the model construct arbitrary GET/schema-discovery calls against Microsoft Graph. That is flexible for a human, and awkward to put behind an allow-list for an automated triage profile. entraadm-mcp exposes seventeen fixed, read-only tools instead (plus one opt-in write, below).
• No AADSTS translation. Sign-in failures come back as raw error codes; triage still needs a lookup table. entraadm-mcp annotates every sign-in failure with what the code actually means.
• No cross-request aggregation. Microsoft Graph itself cannot filter sign-ins on status/errorCode server-side, and has no built-in password-spray view. signin_failure_stats aggregates client-side and flags IPs with failed sign-ins against many distinct users — the pattern Entra's per-account smart lockout does not catch on its own.

Tools

Every tool above is read-only. audit_log_search_start creates a saved audit search object (the one audit_log_search_result then reads) and changes no directory, mailbox or file data. One state-changing tool exists and is off by default:

It looks the account up by exact userPrincipalName first and refuses a guest. Every result has the same keys, including revoked and not_covered: it does not disable the account, reset the password or remove MFA methods, and access tokens already issued keep working until they expire (typically about an hour). revoked is true when Graph confirmed it, false when nothing was done (a refusal, a deadline before the request was sent, a 4xx from Graph), and null when the outcome is unknown (a response lost to a network error, a 5xx after the retries, a deadline after the request was sent, an unreadable success answer); calling again is then safe, revocation is idempotent. Leave the switch unset on any deployment that is not behind its own approval step (a shared gateway, for instance) -- the tool is then absent from tools/list. Unblocking an account and resetting a password stay out of scope.

The four Azure Resource Manager tools live in an Entra-named server on purpose: they use the same app registration and the same azure-identity credential object (a second token scope, https://management.azure.com/.default), run in the same deployment and are covered by the same health_check. A separate server for these tools would double the operational surface. They are governance reads, not resource management; a subscription the credential has no Reader role on simply does not appear in list_subscriptions.

Auth model

Two auth modes, selected by which environment variables are set:

Setting one or two of the three app-only variables is a configuration error and the server refuses to start, rather than silently falling back to a different auth mode than intended.

Required Graph permissions

Required Azure RBAC

Azure RBAC is optional: health_check reports ARM reachability and the number of visible subscriptions as an informational arm probe that never changes status, so a deployment used only for Entra triage stays healthy.

A missing permission never crashes a tool. It degrades that tool (or that one field) to {"error": "...", "missing_permission": "..."} with a human-readable explanation of what role or permission is needed, so health_check and every other tool stay usable even before full permissions are granted.

Identity Protection (Entra ID P2). compromise_suspects adds Microsoft's own risk verdicts when the tenant has them: a cheap riskyUsers?$top=1 probe classifies each tenant as licensed, not_licensed (403 "not licensed": no Entra ID P2), no_permission (other 403: no IdentityRiskyUser.Read.All) or error; licensed and not_licensed are cached for an hour (a 200 whose rows say riskLevel: hidden also means no P2). The endpoint itself is probed: /subscribedSkus can be refused and a SKU list would still have to be mapped to P2. health_check reports it per tenant without changing status, and daily_brief's summary per tenant, so the day P2 appears is noticed. Licensed: microsoft_risky_users lists open (atRisk / confirmedCompromised) high-risk users and, separately, medium, marking those also in spray_breaches / foreign_successes. counts are then distinct accounts over every finding, before the lists are cut: high is any account high here or in Microsoft's high list, medium any medium here or in Microsoft's medium list that is not high (counts.microsoft_high / microsoft_medium say how many Microsoft lists). Otherwise the section is {available: false, reason} and nothing else changes -- never read it as "no risky users".

Setup

uv tool install entraadm-mcp

or

pip install entraadm-mcp

Configuration

Set the three app-only variables for production/unattended use:

export ENTRAADM_TENANT_ID=00000000-0000-0000-0000-000000000000

export ENTRAADM_CLIENT_ID=00000000-0000-0000-0000-000000000000 export ENTRAADM_CLIENT_SECRET=your-client-secret

Or leave all three unset and run az login first for local development.

Optional:

# Default page cap for the log-scanning tools (1-50, default 50).

export ENTRAADM_MAX_PAGES_DEFAULT=50

Wall-clock budget per tool call in seconds (default 45; 0 disables). A hosted MCP

client cuts a call off at about 60 s, so a scan stops at the budget and returns

what it has with capp