entra-scim-mcp

# 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](https://learn.microsoft.com/entra/identity/app-provisioning/enable-scim-api):

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:

```bash
# 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:

```json
{
  "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](https://scimvalidator.microsoft.com) — see [docs/scim-validator.md](node/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.).

```bash
npx -y entra-scim-mcp
```

Required environment:

| Var | Required | Description |
| --- | --- | --- |
| `ENTRA_TENANT_ID` | yes | Directory (tenant) GUID |
| `ENTRA_CLIENT_ID` | yes | App registration (client) GUID |
| `ENTRA_CLIENT_SECRET` | one of | Client secret value (dev) |
| `ENTRA_CLIENT_CERT_PATH` | one of | Path to a PEM containing the certificate **and** private key |
| `ENTRA_CLIENT_CERT_PASSWORD` | optional | Password if the PEM is encrypted |

Set exactly one of `ENTRA_CLIENT_SECRET` or `ENTRA_CLIENT_CERT_PATH`.

### Development / testing environment variables

| Var | Description |
| --- | --- |
| `ENTRA_SCIM_BASE_URL` | Override the SCIM base URL (default `https://graph.microsoft.com/rp/scim`). Point it at the local mock. |
| `ENTRA_SCIM_STATIC_TOKEN` | Use a fixed bearer token instead of Azure AD. **Guardrails:** requires `ENTRA_SCIM_BASE_URL`, refuses any `*.microsoft.com` / `*.microsoft.us` host, warns on non-loopback hosts, and cannot be combined with a real credential. Tenant/client IDs are not required in this mode. |
| `ENTRA_SCIM_DRY_RUN` | Set to `1`: tools run all client-side validation, then return the exact request that would have been sent instead of sending it. No token is acquired — works with zero credential config. |

Dry-run results come back as a successful payload:

```json
{
  "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):

```json
{
  "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:

```json
{
  "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`).

| Tool | Kind | Purpose |
| --- | --- | --- |
| `get_service_provider_config` | read | One-shot capability discovery. Static per API version — fetch once and reuse. |
| `list_resource_types` | read | Enumerate SCIM resource types (User, Group). |
| `list_schemas` | read | Enumerate SCIM schemas and Entra extensions, with each attribute's type, mutability and default-return. Check a patch path here before building it. |
| `list_users` | read | List users; supports the API's restricted filter (eq/ew, and-only) and cursor pagination. Also how you resolve a `userName` to the object id every other user tool wants. |
| `get_user` | read | Read a single user by id with optional attribute projection. Neither CSAs nor group membership are ever included. |
| `provision_user` | add | Create a user with the required attribute set enforced (userName, password, displayName, name.givenName, name.familyName, mailNickname). |
| `update_user` | overwrite | PATCH a user; blocks `remove` of mailNickname and enforces `[type eq "work"]` on address paths. |
| `deprovision_user` | overwrite | DELETE a user. Soft-deleted for 30 days, restorable only via Graph; also strips every group membership. |
| `update_user_lifecycle` | overwrite | Set lifecycle attrs (e.g. `employeeLeaveDateTime`) — which Lifecycle Workflows can fire off. Requires `User-LifeCycleInfo.ReadWrite.All`. |
| `get_user_custom_security_attributes` | read | Read a user's CSAs, projected by attribute set. `attributeSets` is **required** — the API rejects the bare extension URN, and CSAs never come back from a plain `get_user`. |
| `update_user_custom_security_attributes` | overwrite | PATCH CSAs on a user. `remove`, or `replace` with an empty array, deletes an assignment. |
| `list_groups` | read | List groups with the API's restricted filter set. A `members.value` filter is the only way to read membership. |
| `get_group` | read | Read a single group (members are NOT returned — use `list_groups` with a `members.value` filter). |
| `create_group` | add | POST a group. Sets `mailEnabled`, `securityEnabled`, `mailNickname`, `description` via the Entra extension. `displayName` is not unique. |
| `update_group` | overwrite | PATCH group attributes only (membership ops are rejected here; type flags are fixed at creation). |
| `add_group_members` | add | Add ≥1 users to a group — auto-chunks at 20 ids per PATCH (API cap), one Operation per PATCH. Idempotent. On a mid-sequence failure it reports `addedMemberIds` / `failedMemberIds` / `notAttemptedMemberIds` so partial writes are never silent. |
| `remove_group_member` | overwrite | Remove a single user from a group (the API allows only one removal per PATCH, with no other ops). A 404 here usually means *not a member*, not *no such group*. |
| `delete_group` | overwrite | DELETE a group. Unified groups are recoverable for 30 days via Graph; security groups are not. |

### 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.

With `ENTRA_SCIM_DRY_RUN=1` the instructions gain a paragraph saying so, since
a dry-run result is shaped like a success and would otherwise be reported as a
change that landed.

`test/tool-metadata.test.ts` enforces all of this: every tool carries
annotations, read-only and write sets are pinned by name, every input has a
description, and the PATCH tools must show a URN. A new tool that defaults to
looking read-only fails the suite.

## What this server enforces for you

The Entra SCIM API has constraints that are