How do I use Defender Hunt MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Defender Hunt MCP Hunt for suspicious PowerShell activity in last 24 hours" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Defender Hunt MCP

by Soucheff

Overview Schema Related Servers Score Discussions

Python

Remote

Defender Hunt MCP

A Model Context Protocol (MCP) server for Microsoft Defender Advanced Hunting and Microsoft Entra ID identity investigation. It exposes 59 read-oriented atomic/workflow tools and eight resources over stateless Streamable HTTP with Microsoft Entra authentication.

IMPORTANT

This project is currently intended for analyst-assisted investigation in a controlled environment. ReviewSecurity and known functional limitations before production deployment or use as an unattended detection control.

Capabilities

Area	Description
KQL Hunting	Execute Advanced Hunting KQL and perform a basic known-table reference check.
Alert Management	List, filter, and inspect Microsoft Defender security alerts with severity/status filtering and statistical summaries.
Threat Intelligence	Query Defender Threat Intelligence profiles, enrich Indicators of Compromise (IoCs), and hunt for IoCs in Defender telemetry.
Identity Investigation	Consolidate identity context, authentication posture, sign-ins, Conditional Access results, privileges, PIM, risk, and Defender alerts.
Security Posture	Generate environment summaries, device lookups, Secure Score control recommendations, and user logon investigations.
Agent Governance (beta)	Inventory Entra Agent Identities and review bounded application-role assignments.
Advanced Threat Hunting	Pre-built detection modules covering ransomware indicators, suspicious PowerShell, LOLBIN abuse, lateral movement, credential access/dumping, persistence mechanisms, suspicious child processes, remote access tools/RATs, defense evasion, threat intel feed matching, data exfiltration, and ASR rule events.

Related MCP server: Response MCP Server

Tools (59)

Core Hunting

Tool	Description
`run_hunting_query`	Execute a KQL query against Microsoft Defender Advanced Hunting (up to 10,000 rows / 30 days).
`validate_kql_query`	Check locally whether a query references a known hunting table; this is not syntax validation.

Alerts

Tool	Description
`get_security_alerts`	Retrieve security alerts with optional severity and status filters.
`get_alert_details`	Get full details for a specific alert by ID.
`get_alert_statistics`	Statistical summary of alerts over a configurable time range.

Threat Intelligence

Tool	Description
`get_threat_indicators`	List Defender Threat Intelligence profile indicators (IoCs).
`enrich_ioc`	Enrich an IoC (IP, domain, URL, hash) with Defender telemetry.
`hunt_by_ioc`	Hunt for an IoC across all relevant Defender tables.

Security Posture

Tool	Description
`get_security_recommendations`	Retrieve Microsoft Secure Score control profiles and remediation guidance.
`get_device_info`	Get detailed information about a device by name or ID.
`investigate_user_logon`	Entra sign-in investigation from Defender `EntraIdSignInEvents`, with Graph fallback.
`get_environment_dashboard`	Full security dashboard: alerts, auth, devices, and network overview.
`analyze_security_posture`	Analyse security posture with insights on identity, devices, network, and applications.

Microsoft Entra ID

Tool	Description
`get_identity_context`	Consolidate profile, organization, groups, roles, app roles, licenses, manager, reports, and ownerships.
`get_authentication_posture`	Assess registered authentication methods, MFA registration, FIDO2/passkeys, WHfB, and passwordless readiness.
`get_signin_activity`	Return bounded sign-in evidence plus applications, devices, locations, IPs, and risk indicators.
`analyze_signin_risk`	Produce an explainable score from Identity Protection, risky sign-ins, and failures.
`get_applied_conditional_access`	Inspect actual Conditional Access policy results for one sign-in.
`get_identity_alerts`	Match Defender XDR alert user evidence to an identity ID or UPN.
`get_privileged_access`	List active/eligible directory roles and role-assignable group membership.
`get_pim_eligibility`	Return active and eligible directory-role assignments with scope and expiration.
`get_pim_activations`	Return bounded PIM self-activation request history and justification.
`get_user_app_role_assignments`	List enterprise application (app role) assignments granted to a user.
`list_privileged_role_assignments`	Tenant-wide snapshot of active directory-role assignments with principals.
`get_authentication_methods_policy`	Report tenant authentication methods policy and flag weak enabled methods.
`find_user_oauth_grants`	List a user's delegated OAuth2 grants and flag high-risk scopes.
`summarize_signin_failures`	Aggregate failed sign-ins by error code, user, and IP to surface spray/lockout.
`get_users_by_directory_role`	Resolve active or PIM-eligible directory-role principals, including users inherited through role-assignable groups.
`list_identity_groups`	Inventory security, Microsoft 365, or role-assignable groups.
`analyze_identity_group`	Inspect group properties, owners, and bounded direct or transitive membership.
`get_signin_logs`	Retrieve Entra ID sign-in logs with UPN, app, status, and risk filters.
`get_audit_logs`	Retrieve Entra ID audit/directory logs filtered by category, activity, or target.
`get_risky_users`	List users flagged by Entra ID Identity Protection.
`get_risky_signins`	Retrieve risky sign-in events from Identity Protection.
`get_conditional_access_policies`	List and inspect Conditional Access policies.
`analyze_user_risk_profile`	Comprehensive risk profile combining sign-in, risk, and audit data for a user.

Advanced Threat Hunting

Tool	Description
`hunt_ransomware_indicators`	Detect ransomware file extensions, ransom notes, shadow copy deletion, double extensions.
`hunt_suspicious_powershell`	Detect encoded commands, web requests, Defender tampering, AMSI detections.
`hunt_lolbin_activity`	Detect LOLBIN abuse: certutil, mshta, regsvr32, rundll32, wmic, bitsadmin.
`hunt_lateral_movement`	Detect lateral movement: PsExec, SMB, WMI, RDP, DCOM.
`hunt_credential_access`	Detect credential dumping: LSASS, NTDS.dit, SAM, mimikatz, DCSync.
`hunt_persistence_mechanisms`	Detect persistence: registry run keys, scheduled tasks, services, startup folder, WMI subscriptions.
`hunt_suspicious_child_processes`	Detect suspicious child processes spawned by browsers, Office, explorer, Outlook.
`hunt_remote_access_tools`	Detect RATs, commercial RMM tools, and tunnelling utilities.
`hunt_defense_evasion`	Detect evasion: security tool tampering, log clearing, timestomping, process injection.
`hunt_threat_intel_feeds`	Match activity against public threat intel feeds (malicious domains, IPs, hashes).
`hunt_data_exfiltration`	Hunt for high-volume connection patterns, cloud storage, DNS tunnelling, and archives using documented schema columns.
`get_asr_events`	Retrieve Attack Surface Reduction (ASR) rule events (blocked/audited).

Token-efficient workflows

Tool	Description
`investigate_identity`	Combine context, authentication, risk, alerts, and privileged access with bounded evidence.
`recommend_next_investigation_steps`	Deterministically route structured findings to the next evidence-gathering tools.
`investigate_user`	Combine sign-ins, risky sign-ins, and audit activity with bounded evidence.
`investigate_alert`	Combine one alert with alert statistics and bounded context.
`hunt_iocs_batch`	Deduplicate and enrich up to 20 typed IoCs with bounded concurrency.
`run_threat_hunt_suite`	Run selected threat modules with quota-aware concurrency and explicit partial failures.

Agent governance (beta)

Tool	Description
`list_agent_identities`	List Entra Agent Identity service principals through a feature-flagged Graph beta adapter.
`get_agent_identity_profile`	Retrieve one Agent Identity and bounded application-role analysis.
`analyze_agent_permissions`	Produce explainable heuristic review of an agent's app-role assignments.
`evaluate_agent_risk`	Score one beta Agent Identity using bounded assignment heuristics.
`list_agents_with_excessive_permissions`	List beta Agent Identities meeting a configurable heuristic risk threshold.

Resources

URI	Description
`defender://hunting/examples`	Example KQL queries for Advanced Hunting.
`defender://hunting/tables`	Reference of available Advanced Hunting tables.
`defender://hunting/ioc-queries`	IoC-based threat hunting query guide.
`defender://soc/playbooks`	SOC incident response playbooks and workflows.
`entra://identity/signin-investigation`	Sign-in investigation guide.
`entra://identity/risk-investigation`	Risky user/sign-in investigation guide.
`entra://identity/conditional-access`	Conditional Access policy reference.
`defender://capabilities`	Contract, auth, cache, workflow, beta capability, and limit metadata.

The complete behavioral reference, inputs, caveats, and result semantics are documented in MCP tools and resources.

Documentation

Guide	Contents
Configuration	Environment variables, Graph permissions, authentication boundaries, and health semantics.
Development	`uv` workflow, quality checks, project layout, MCP smoke test, and KQL development rules.
Deployment	Docker Compose, direct Docker, Azure Container Apps scripts, verification, and production hardening.
Security	Trust model, secrets, query/input risks, third-party feeds, and known limitations.
Tools and resources	Current 59-tool and eight-resource reference derived from the live registry.
Contributing	Development workflow, required checks, and pull request guidance.
Security policy	Private vulnerability reporting and supported-version policy.

Architecture

┌──────────────────────┐        ┌──────────────────────────┐
│   MCP Client         │  HTTP  │  server_http.py          │
│  (Copilot, etc.)     │◄──────►│  Starlette + Uvicorn     │
│                      │        │  • Entra JWT auth        │
└──────────────────────┘        │  • CORS                  │
                                │  • /health, /info        │
                                │  • /mcp (streamable-http)│
                                └─────────┬────────────────┘
                                          │
                                ┌─────────▼────────────────┐
                                │  server.py               │
                                │  FastMCP server          │
                                │ 59 tools · 8 resources   │
                                └─────────┬────────────────┘
                                          │
                                ┌─────────▼────────────────┐
                                │  Microsoft Graph API     │
                                │ (Entra app credentials) │
                                └──────────────────────────┘

Configuration

Variable	Required	Description
`AZURE_TENANT_ID`	Yes	Microsoft Entra tenant ID.
`AZURE_CLIENT_ID`	Yes	App registration client ID.
`ENTRA_MCP_AUDIENCE`	Yes	Audience of access tokens issued for the MCP resource API.
`ENTRA_MCP_ISSUER`	Yes	Single-tenant Entra v2 issuer.
`AZURE_CLIENT_SECRET` or certificate	OBO only	Confidential credential for delegated OBO; use a Key Vault-backed certificate in Azure.
`ENTRA_AGENT_CLIENT_IDS`	Agent ID	Comma-separated allowlist of approved Microsoft Entra Agent Identity client IDs.
`AZURE_MANAGED_IDENTITY_CLIENT_ID`	Azure	User-assigned infrastructure identity for Redis, ACR/Key Vault, and temporary legacy Graph access.
`LOG_LEVEL`	No	Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`). Defaults to `INFO`.
`PORT`	No	HTTP listen port inside the container. Defaults to `8000`.
`HOST`	No	HTTP bind address. Defaults to `0.0.0.0`.
`DEBUG`	No	Starlette debug mode. Defaults to `false`; never enable in production.
`ALLOWED_ORIGINS`	No	Comma-separated browser origins allowed by CORS. CORS is disabled when empty.

See Configuration for MCP_PORT, authentication boundaries, health behavior, and secret handling.

Required Microsoft Graph Permissions (Application)

SecurityEvents.Read.All — Security alerts
ThreatHunting.Read.All — Advanced Hunting queries
ThreatIntelligence.Read.All — Defender Threat Intelligence profiles/indicators (license/add-on also required)
AuditLog.Read.All — Sign-in and audit logs
IdentityRiskyUser.Read.All — Risky users
Policy.Read.All — Conditional Access policies
RoleManagement.Read.Directory — Active directory-role definitions and assignments
RoleEligibilitySchedule.Read.Directory — PIM-eligible role assignments when assignment_state is eligible or all
GroupMember.Read.All — Group owners and direct/transitive membership
Group.Read.All — Full group inventory and properties
Member.Read.Hidden — Hidden group membership, only when that tenant data must be analyzed
User.Read.All — Identity profile and organizational relationships
LicenseAssignment.Read.All — License details when not covered by an approved broader directory permission
UserAuthenticationMethod.Read.All — Authentication methods for other users
RoleAssignmentSchedule.Read.Directory — PIM activation request history
SecurityAlert.Read.All — Defender XDR identity-alert correlation
Application.Read.All — App-role assignment resource resolution and OAuth grant review
DelegatedPermissionGrant.Read.All — Delegated OAuth2 permission grants per user
Policy.Read.All — Authentication methods policy (also covers Conditional Access)

Grant application permissions with tenant-wide admin consent and apply least privilege. SecurityEvents.Read.All also covers the Secure Score endpoint currently used by get_security_recommendations.

Quick start

Prerequisites: Python 3.12 and uv. Docker is optional for local Python execution.

# Create the environment and install exactly the locked dependencies
uv sync --frozen

# Configure Entra resource API/OBO settings and local Redis
cp .env.example .env

# Run the server
uv run server_http.py

Dependency versions are declared in pyproject.toml and reproducibly pinned in uv.lock. Use uv add <package> for runtime dependencies and uv add --dev <package> for development tools.

Development checks

# Verify that the lockfile matches pyproject.toml
uv lock --check

# Lint and compile the Python sources
uv run ruff check config.py server.py server_http.py
uv run python -m py_compile config.py server.py server_http.py

# Run the unit and contract test suite
uv run pytest

The server listens on http://0.0.0.0:8000 by default. The MCP endpoint is /mcp; /health and /info are public utility endpoints.

Running in a container

Create the runtime environment file and replace every placeholder:

cp .env.example .env

Build and start with Docker Compose:

docker compose up --build -d
docker compose ps
curl --fail http://localhost:8000/health

Or use Docker directly:

docker build -t defender-hunt-mcp:local .
docker run --rm --name defender-hunt-mcp \
    --env-file .env \
    --read-only \
    --tmpfs /tmp:size=16m,mode=1777 \
    --cap-drop ALL \
    --security-opt no-new-privileges \
    -p 8000:8000 \
    defender-hunt-mcp:local

The health endpoint returns HTTP 503 until all required Graph credential variables are present. It does not test Graph connectivity, consent, or licensing. Do not bake .env or secrets into the image; .dockerignore excludes the local environment file from the build context.

To stop the Compose deployment:

docker compose down

Transport

The FastMCP server uses stateless Streamable HTTP, allowing horizontal scaling without session affinity. /mcp accepts only Microsoft Entra bearer access tokens for the configured audience and tenant. Any Agent ID sidecar runs with the calling agent and obtains this inbound token. Delegated users and delegated Agent IDs use MCP OBO for Graph; autonomous Agent IDs use the Container App Managed Identity for downstream Graph access.

Example initialize request:

curl --fail --silent \
    -X POST http://localhost:8000/mcp \
    -H 'Authorization: Bearer <entra-access-token-for-mcp>' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, text/event-stream' \
    --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"smoke-test","version":"1.0"}}}'

Deployment

The repository includes a hardened local container configuration and two Azure Container Apps deployment scripts:

deploy-full.ps1 provisions infrastructure and deploys the service.
deploy.ps1 updates an existing registry and Container App.

The current Azure scripts use ACR administrative credentials and plain Container App environment values for application secrets. Follow the production-hardening checklist in Deployment before production use.

License

Defender Hunt MCP is available under the MIT License.

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Soucheff/DefenderHuntMCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server