D365 F&O Security & Licence Intelligence MCP Server

Exposes security analysis, licence intelligence, and SoD detection as MCP tools consumable by AI agents and copilots.

Quick Start

Prerequisites

• Python 3.10+
• A D365 F&O environment with OData access
• An Azure AD / Entra ID app registration with Dynamics ERP → CustomService.FullAccess permission

1. Install

git clone https://github.com/yuriirask-bit/d365fo-security-mcp.git
cd d365fo-security-mcp
pip install -e ".[dev]"

2. Configure

cp env.example .env
# Edit .env with your D365 environment URL and Azure AD credentials

3. Run

d365fo-security-mcp

The server starts on stdio transport (standard MCP protocol).

4. Connect

MCP clients (Claude Desktop, Claude Code, GitHub Copilot, Cursor, etc.) launch the server as a subprocess. Environment variables must be passed in the client's MCP configuration — the server does not inherit your shell environment or read .env when launched this way.

Claude Desktop — edit %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "d365fo-security": {
      "command": "d365fo-security-mcp",
      "env": {
        "D365FO_BASE_URL": "https://your-env.operations.dynamics.com",
        "D365FO_TENANT_ID": "your-tenant-id",
        "D365FO_CLIENT_ID": "your-client-id",
        "D365FO_CLIENT_SECRET": "your-client-secret",
        "LICENCE_SOURCE": "graph"
      }
    }
  }
}

Claude Code — edit .claude/mcp.json in your project root:

{
  "mcpServers": {
    "d365fo-security": {
      "command": "d365fo-security-mcp",
      "env": {
        "D365FO_BASE_URL": "https://your-env.operations.dynamics.com",
        "D365FO_TENANT_ID": "your-tenant-id",
        "D365FO_CLIENT_ID": "your-client-id",
        "D365FO_CLIENT_SECRET": "your-client-secret",
        "LICENCE_SOURCE": "graph"
      }
    }
  }
}

GitHub Copilot (VS Code) — add to github.copilot.chat.mcp.servers in your VS Code settings.json, or create a .vscode/mcp.json file in the project root:

{
  "servers": {
    "d365fo-security": {
      "command": "d365fo-security-mcp",
      "env": {
        "D365FO_BASE_URL": "https://your-env.operations.dynamics.com",
        "D365FO_TENANT_ID": "your-tenant-id",
        "D365FO_CLIENT_ID": "your-client-id",
        "D365FO_CLIENT_SECRET": "your-client-secret",
        "LICENCE_SOURCE": "graph"
      }
    }
  }
}

Cursor — edit .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global configuration):

{
  "mcpServers": {
    "d365fo-security": {
      "command": "d365fo-security-mcp",
      "env": {
        "D365FO_BASE_URL": "https://your-env.operations.dynamics.com",
        "D365FO_TENANT_ID": "your-tenant-id",
        "D365FO_CLIENT_ID": "your-client-id",
        "D365FO_CLIENT_SECRET": "your-client-secret",
        "LICENCE_SOURCE": "graph"
      }
    }
  }
}

Important: After changing env values in MCP config, you must fully restart the client (not just reconnect the server) for the new values to take effect.

MCP Inspector (for local testing — reads .env automatically):

npx @modelcontextprotocol/inspector d365fo-security-mcp

5. First Tool Call

Ask your AI agent:

"What licence does each user in our D365 environment need?"

Available Tools

SoD Conflict Detection & Security Analysis

Tip: Most user-scanning tools accept an exclude_service_accounts parameter that uses Provider-based native detection to filter out service and system accounts from results.

Configuration

App Insights Setup (Optional — Login Activity)

Tools like find_dormant_privileged_accounts, run_user_access_review, and get_security_health_score use login activity data to detect dormant accounts. The primary source for D365 login sessions is Azure Application Insights.

1. Enable Application Insights in D365 F&O

1. In the D365 F&O environment, go to System administration → Setup → Monitoring and telemetry parameters
2. Enable Custom Telemetry + Application Insights
3. Paste your App Insights Instrumentation Key into the configuration field
4. Save and allow a few minutes for telemetry to start flowing

2. Get the Connection String

1. In the Azure Portal, navigate to your Application Insights resource
2. On the Overview page, copy the Connection String (not just the instrumentation key — the full string starting with InstrumentationKey=...;IngestionEndpoint=...;ApplicationId=...)

3. Grant the Service Principal Read Access

The MCP server's service principal (the same app registration used for D365 OData access) needs the Monitoring Reader role on the App Insights resource.

Why not API keys? App Insights API keys were deprecated by Microsoft and retired in March 2026. Azure AD authentication with RBAC is the only supported method going forward.

Option A — Azure Portal (UI):

1. Navigate to your Application Insights resource
2. Go to Access control (IAM) → Add → Add role assignment
3. Role: search for and select Monitoring Reader
4. Members: select User, group, or service principal, click + Select members
5. Search for your app registration name (e.g., ICU-DEV1) and select it
6. Click Review + assign

Option B — Azure CLI:

# Get the service principal object ID
SP_ID=$(az ad sp show --id <your-D365FO_CLIENT_ID> --query id -o tsv)

# Get the App Insights resource ID
AI_SCOPE=$(az monitor app-insights component show \
  -g <resource-group> --app <app-insights-name> --query id -o tsv)

# Assign Monitoring Reader role
az rest --method put \
  --url "${AI_SCOPE}/providers/Microsoft.Authorization/roleAssignments/$(uuidgen)?api-version=2022-04-01" \
  --body "{
    \"properties\": {
      \"roleDefinitionId\": \"/subscriptions/<subscription-id>/providers/Microsoft.Authorization/roleDefinitions/43d0d8ad-25c7-4714-9337-8ba259a9fe05\",
      \"principalId\": \"${SP_ID}\",
      \"principalType\": \"ServicePrincipal\"
    }
  }"

Note: 43d0d8ad-25c7-4714-9337-8ba259a9fe05 is the built-in role definition ID for Monitoring Reader — it is the same across all Azure subscriptions.

4. Configure the MCP Server

Add the connection string to your environment configuration:

APP_INSIGHTS_CONNECTION_STRING=InstrumentationKey=xxxxx;IngestionEndpoint=https://...;ApplicationId=xxxxx

Or in your MCP client config (claude_desktop_config.json / .claude/mcp.json):

{
  "env": {
    "APP_INSIGHTS_CONNECTION_STRING": "InstrumentationKey=xxxxx;IngestionEndpoint=https://...;ApplicationId=xxxxx"
  }
}

4. Verify

After a user logs into D365 and navigates a few pages, run:

pageViews
| summarize LoginTime=min(timestamp) by user_Id, session_Id
| order by LoginTime desc

in the App Insights Logs blade to confirm telemetry is arriving.

How It Works

D365 F&O emits pageView events to Application Insights for every interactive session. The MCP server queries these via the App Insights API to derive login sessions — summarising the first page view per user/session as the login timestamp. No custom X++ entities are required.

Note: App Insights is one of three login data sources. The server also queries D365 Database Logging (SysUserLog via DatabaseLogs entity) and Microsoft Graph signInActivity in parallel. The most recent timestamp from any source wins. All sources are optional — the tools degrade gracefully with warnings when sources are unavailable. Graph signInActivity requires an Entra ID P1/P2 (Premium) licence on the tenant — see Step 5b.

How It Works

MCP Client (Claude, Copilot) → MCP Server → OData API → D365 F&O
                                    ↓
                             Licence Source
                        (assess-only | file | graph)

The server queries D365 F&O security metadata via OData, calculates licence requirements per user, and exposes the results as MCP tools.

Licence Source Options

Common Agent Prompts

Licence Intelligence

• "What licence does each user in our D365 environment need?"
• "Which users are over-licensed and how much could we save?"
• "Are any users under-licensed and at risk of enforcement?"
• "What happens to licence costs if I remove the Finance Controller role from user jsmith?"
• "Give me an executive summary of our D365 licence spend"
• "Why does the Accountant role require a Finance licence?"

SoD & Security Analysis

• "Are there any segregation of duties violations in our environment?"
• "What SoD rules are you checking against?"
• "Show me everything about user jsmith's security access"
• "Who are our highest-risk users?"
• "Are there any dormant privileged accounts?"
• "Give me a full access review list for our quarterly audit"
• "How healthy is our D365 security overall?"

Limitations

• The PPAC licence provider is not yet implemented (stub only)
• The Graph provider covers common Microsoft 365 SKU GUIDs; uncommon SKUs are logged as warnings
• Duty/privilege breakdown uses flat lists matching the D365 OData data model structure
• Single-environment operation — multi-environment comparison is a future capability

Development

pip install -e ".[dev]"
ruff check src/ tests/
pytest --cov=src/d365fo_security_mcp/tools

Licence

MIT