entra-scim-mcp

Model Context Protocol server for the Microsoft Entra SCIM 2.0 Provisioning API (GA April 2026). Exposes user and group lifecycle operations against https://graph.microsoft.com/rp/scim as MCP tools for agents like Claude.

What you can do with it

• Discover the tenant's SCIM capabilities (get_service_provider_config, list_resource_types, list_schemas)
• Provision, read, update, and deprovision users — including Custom Security Attributes and lifecycle attrs
• Create, update, and delete groups, and manage membership with the API's strict PATCH rules respected automatically

Prerequisites

Before this server can talk to your tenant, complete the one-time setup in the Microsoft docs:

1. Entra ID P1 (or any SKU containing P1) and an Azure subscription to link for billing.
2. Enable the SCIM Provisioning API in ID Governance → Dashboard and link a billing resource group.
3. Register an application with the Microsoft Graph application permissions you need:
   • User.ReadWrite.All, Group.ReadWrite.All (core lifecycle)
   • CustomSecAttributeAssignment.ReadWrite.All, CustomSecAttributeDefinition.Read.All (CSA tools)
   • User-LifeCycleInfo.ReadWrite.All (lifecycle tools)
   • User-Mail.ReadWrite.All, User-Phone.ReadWrite.All, User.EnableDisableAccount.All (least-privilege alternatives) Grant admin consent.
4. Create either a client secret or upload a PEM client certificate.

Every SCIM API call is billed — this server does not batch beyond what the API requires.

Try it without an Entra tenant

The package ships a local mock of the Entra SCIM API (entra-scim-mock-server) so you can drive every tool with zero Azure setup and zero API billing:

# shell 1 — start the mock (seeds a small demo tenant)
npx -y --package entra-scim-mcp entra-scim-mock-server

Then point the MCP server at it:

{
  "mcpServers": {
    "entra-scim-mock": {
      "command": "npx",
      "args": ["-y", "entra-scim-mcp"],
      "env": {
        "ENTRA_SCIM_BASE_URL": "http://127.0.0.1:8990",
        "ENTRA_SCIM_STATIC_TOKEN": "dev-token"
      }
    }
  }
}

Mock flags: --port, --token, --seed <file.json>, --no-seed, --capture <file.jsonl> (log every request/response), --validator-compat (RFC-standard behavior for the Microsoft SCIM Validator — see docs/scim-validator.md).

Install / run

The server is a stdio MCP server, designed to be launched by your MCP client (Claude Desktop, Claude Code, etc.).

npx -y entra-scim-mcp

Required environment:

Set exactly one of ENTRA_CLIENT_SECRET or ENTRA_CLIENT_CERT_PATH.

Development / testing environment variables

Dry-run results come back as a successful payload:

{
  "dryRun": true,
  "request": {
    "method": "DELETE",
    "url": "https://graph.microsoft.com/rp/scim/users/u-1",
    "headers": {}
  }
}

(DELETE carries no Accept header — the API rejects a specific JSON media type there. Every other method sends Accept: application/json.)

Multi-request tools (e.g. add_group_members beyond 20 ids) surface only their first chunked request in dry-run.

Claude Desktop config

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

{
  "mcpServers": {
    "entra-scim": {
      "command": "npx",
      "args": ["-y", "entra-scim-mcp"],
      "env": {
        "ENTRA_TENANT_ID": "00000000-0000-0000-0000-000000000000",
        "ENTRA_CLIENT_ID": "11111111-1111-1111-1111-111111111111",
        "ENTRA_CLIENT_SECRET": "..."
      }
    }
  }
}

For production, swap the secret for a certificate:

{
  "env": {
    "ENTRA_TENANT_ID": "...",
    "ENTRA_CLIENT_ID": "...",
    "ENTRA_CLIENT_CERT_PATH": "/secure/path/entra-scim-mcp.pem"
  }
}

Tools

The Kind column is the tool's MCP annotations, which is what a client reads when it decides whether a call needs your approval: read is readOnlyHint, add is a write that only creates (destructiveHint: false), overwrite is a write that discards or replaces state with no undo through this API (destructiveHint: true).

What the agent is told, and where

A model never reads this file, so everything it needs has to travel in the protocol. Three places carry it, and the split is deliberate:

• Server instructions, sent once in the handshake, hold what is true of every tool: ids rather than names, membership being readable in one direction only, CSAs being invisible to ordinary reads, the narrow filter grammar, and that every call is a billed Graph request. Repeating that in eighteen descriptions would cost more context than it bought.
• Tool descriptions hold what is specific to one tool, including the failure modes worth pre-empting — the 404 that names the group when the user simply is not a member, the mailNickname that cannot be removed once set, the second provision_user that conflicts rather than merges.
• Input descriptions hold per-argument syntax. The three PATCH tools each carry their own path example, because path syntax is the one thing here that cannot be guessed: the API accepts a narrow subset of RFC 7644, and the subset differs between ordinary attributes and CSAs.