Entra ID SecOps MCP Server

An MCP server that exposes Microsoft Entra ID security logs as tools executable by an AI agent (Claude Desktop, Cursor, or any other MCP client).

Goal: allow an analyst to ask a question in natural language — "why can't this account sign in anymore?" — and get an answer in seconds based on the tenant's actual data.

📖 Installation and testing guide — the three ways to launch the server, step by step. 🔍 Technical brief — market scan and secure exposure.

Design Principle

A raw Microsoft Graph response contains about sixty fields per event. The server applies aggressive truncation: only about a dozen security indicators reach the model. This is both a cost optimization (factor ~35 on tokens) and a security control, since unlisted fields — some of which are attacker-controlled — never enter the context.

Aggregates (number of failures, distinct IPs, suspicious patterns) are computed in Python, not inferred by the model.

Tools

All tools are read-only: the server never modifies the tenant.

Recommended investigation order

get_user_context     le compte est-il privilégié ? l'incident est-il grave ?
      ↓
get_user_signins     que s'est-il passé sur l'authentification ?
      ↓
get_risk_detections  qu'a détecté Identity Protection, et pourquoi ?
      ↓
get_directory_audits l'attaquant a-t-il modifié quelque chose une fois entré ?

This sequence is also described in the server's instructions, which the MCP client sends to the model.

Quick start (without an Azure tenant)

The fixture mode replays a demo incident and requires no tenant, license, or secret.

python -m venv venv
venv/Scripts/activate          # Windows ; sur Linux/macOS : source venv/bin/activate
pip install -e ".[dev]"

cp .env.example .env           # ENTRA_DATA_SOURCE=fixture est déjà la valeur par défaut
python -m entra_secops_mcp

Connecting to a real tenant

1. Create an App Registration in the Entra portal.

2. Add the application permissions from the table above, then grant admin consent.

3. Generate a client secret.

4. Fill in .env:

AZURE_TENANT_ID=...
AZURE_CLIENT_ID=...
AZURE_CLIENT_SECRET=...
ENTRA_DATA_SOURCE=graph

License required. Accessing sign-in logs via the API requires an Entra ID P1 license, and Identity Protection tools require P2. Without them, Graph returns 403. The other tools work without a paid license. Check the tenant's license before you start: this is the classic blocker that wastes several days.

Security

• No secret is present in the code or in the Docker image. They are injected at startup via --env-file.

• .env is excluded from git by .gitignore. A secret pushed to a repository must be revoked in Azure, not just deleted from the file.

• Logging goes to stderr: in stdio transport, stdout carries the JSON-RPC protocol and tolerates no stray bytes.

Configuration

All variables are documented in .env.example.

Docker

docker build -t entra-secops-mcp .
docker run -i --rm --env-file .env entra-secops-mcp

Final image: 277 MB, multi-stage build, runs as a non-root user (uid=1000), no secrets in the layers.

-i keeps standard input open — that's where the MCP protocol passes through. No -t: a pseudo-terminal injects color codes that corrupt JSON frames.

Development

pytest              # 81 tests
ruff check src tests
mypy src            # mode strict
pre-commit install  # contrôles avant chaque commit
python demo.py      # investigation de démonstration

Status

License

MIT.