entra-scim-mcp

Model Context Protocol-Server für die Microsoft Entra SCIM-2.0-Provisioning-API (GA April 2026). Stellt Benutzer- und Gruppen-Lebenszyklus-Operationen über https://graph.microsoft.com/rp/scim als MCP-Tools für Agents wie Claude bereit.

Was Sie damit tun können

• Die SCIM-Fähigkeiten des Mandanten ermitteln (get_service_provider_config, list_resource_types, list_schemas)

• Benutzer bereitstellen, lesen, aktualisieren und die Bereitstellung aufheben – einschließlich Custom Security Attributes und Lebenszyklus-Attributen

• Gruppen erstellen, aktualisieren und löschen sowie Mitgliedschaften verwalten, wobei die strengen PATCH-Regeln der API automatisch eingehalten werden

Related MCP server: mcp-m365-mgmt

Voraussetzungen

Bevor dieser Server mit Ihrem Mandanten kommunizieren kann, führen Sie die einmalige Einrichtung aus der Microsoft-Dokumentation durch:

1. Entra ID P1 (oder eine beliebige SKU, die P1 enthält) sowie ein Azure-Abonnement, das für die Abrechnung verknüpft werden muss.

2. Aktivieren Sie die SCIM-Provisioning-API unter ID Governance → Dashboard und verknüpfen Sie eine Abrechnungsressourcengruppe.

3. Registrieren Sie eine Anwendung mit den Microsoft-Graph-Anwendungsberechtigungen, die Sie benötigen:

   • User.ReadWrite.All, Group.ReadWrite.All (Kernlebenszyklus)

   • CustomSecAttributeAssignment.ReadWrite.All, CustomSecAttributeDefinition.Read.All (CSA-Tools)

   • User-LifeCycleInfo.ReadWrite.All (Lebenszyklus-Tools)

   • User-Mail.ReadWrite.All, User-Phone.ReadWrite.All, User.EnableDisableAccount.All (Least-Privilege-Alternativen)

   Erteilen Sie die Admin-Zustimmung.

4. Erstellen Sie entweder einen Client-Secret oder laden Sie ein PEM-Clientzertifikat hoch.

Jeder SCIM-API-Aufruf wird abgerechnet – dieser Server nimmt kein Batching über das hinaus vor, was die API erfordert.

Ausprobieren ohne Entra-Mandanten

Das Paket enthält einen lokalen Mock der Entra-SCIM-API (entra-scim-mock-server), mit dem Sie jedes Tool ohne Azure-Einrichtung und ganz ohne API-Kosten nutzen können:

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

Richten Sie dann den MCP-Server darauf aus:

{
  "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> (jede Anforderung/Antwort protokollieren), --validator-compat (RFC-konformes Verhalten für den Microsoft SCIM Validator – siehe docs/scim-validator.md).

Installation / Ausführung

Der Server ist ein Stdio-MCP-Server und wird von Ihrem MCP-Client (Claude Desktop, Claude Code usw.) gestartet.

npx -y entra-scim-mcp

Erforderliche Umgebungsvariablen:

Setzen Sie entweder ENTRA_CLIENT_SECRET oder ENTRA_CLIENT_CERT_PATH.

Umgebungsvariablen für Entwicklung / Tests

Dry-Run-Ergebnisse werden als Erfolgs-Payload zurückgegeben:

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

(DELETE sendet keinen Accept-Header – die API lehnt einen bestimmten JSON-Medientyp hier ab. Jede andere Methode sendet Accept: application/json.)

Tools, die mehrere Anfragen senden (z. B. add_group_members mit mehr als 20 IDs), zeigen im Dry-Run nur ihre erste in Blöcke aufgeteilte Anfrage.

Claude-Desktop-Konfiguration

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) oder %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": "..."
      }
    }
  }
}

Für die Produktion ersetzen Sie das Secret durch ein Zertifikat:

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

Tools

Was dieser Server für Sie erzwingt

Die Entra-SCIM-API hat Einschrän,rän, die leicht übersehen werden. Die Tool-Schicht weist ungültige Eingaben ab, bevor eine Anfrage gesendet wird:

• Filter-Allow-Liste: nur die dokumentierten Attribute und Operatoren pro Ressource; or wird abgelehnt; externalId kann nicht mit einer anderen Klausel kombiniert werden.

• Query-Strings: Keine Leerzeichen um = herum (die API antwortet bei jeder einzelnen mit 400).

• User-PATCH: Das remove von mailNickname ist blockiert; der Pfad-Filter für Adressen muss exakt [type eq "work"] sein.

• Group-PATCH: Mitgliedschaftsoperationen laufen über für didizierte Tools, damit das Limit von 20 Mitgliedern pro Hinzufügen und die Einzel-Entfernungsregel garantiert sind.

• Idempotentes Mitglieder-Hinzufügen: Erneutes Hinzufügen behandelt die API als Erfolg; add_group_members entfernt doppelte Eingaben.

Fehler werden als ein strukturiertes Payload mit status, scimType und detail an den Agenten zurückgegeben.

API-Verhaltensweisen, die man kennen sollte

Verhaltensweisen der Live-API, die in der Dokumentation entweder mehrdeutig oder überhaupt nicht beschrieben sind. Sie wurden jeweils durch Tests gegen einen realen Mandanten oder den Microsoft-SCIM-Verodifizierungen ermittelt und werden bereits für Sie abgedeckt – sie werden hier aufgeführt, weil sie die Interpretation einer Antwort verändern.

DELETE darf keinen Accept-Header mitführen. Die API antwortet mit 400 Accept header application/json is invalid. Alle vier Varianten wurden live geprüft: kein Header → 204, */* → 204, application/json → 400, application/scim+json → 400. Nur DELETE kehrt die Regel um — jede andere Methode verlangt einen JSON-Accept, und das Weglassen ist ein dokumentierter 400-Fehler. Genau das hat deprovision_user und delete_group bis zum ersten Live-Lauf stillschweigend kaputt gemacht.

Custom Security Attributes werden bei einem normalen Lesevorgang nie zurückgegeben. In /Schemas steht das Attribut auf der Attribute-Set-Ebene auf returned: "request", daher wird get_user CSAs egal, wonach man fragt, nicht enthalten. Sie erscheinen nur, wenn sie explizit benannt werden, und die Projektion ist set-granular: urn:...:CustomSecurityAttributes:<Set>. Die nackte Erweiterungs-URN wird rundweg abgelehnt (400 ... not supported in the "attributes" or "excludedAttributes" query parameter); deshalb ist attributeSets eine Pflichteingabe und keine optionale.

CSA-Werte sind typisiert, und der Typ wird auch erzwungen. Boolesche Werte, Integer, String und mehrwertige Strings bleiben bei passendem JSON-Typ verlustfrei erhalten, und eine einzelne PATCH-Anfrage kann mehrere Attribute gleichzeitig tragen. Zwei Entfernungsverhalten, beide von Microsoft nicht dokumentiert:

• op: "remove" auf einem CSA-Pfad löscht genau diese eine Zuweisung und lässt die anderen intakt.

• replace mit [] bei einem mehrwertigen Attribut entfernt die Zuweisung — ein späterer Lesevorgang lässt das Attribut ganz aus, statt ein leeres Array zu liefern.

password ist beim Anlegen erforderlich, aber nie lesbar. Es ist writeOnly / returned: never, und keine Antwort gibt es je wieder. Der vollständige Pflichtsatz beim Anlegen ist userName, password, displayName, name.givenName, name.familyName und mailNickname — deutlich strenger als RFC 7643, das nur userName verlangt.

Ein Gruppen-displayName ist nicht eindeutig. Entra akzeptiert einen doppelten Gruppennamen und liefert 201. RFC-orientierte Werkzeuge rechnen hier oft mit 409; man sollte sich also nicht darauf verlassen, dass das Anlegen einer vorhandenen Gruppe fehlschlägt — lieber zuerst filtern.

Das Entfernened eines Gruppenmitglieds betrifft die Mitgliedschaft, nicht den Benutzer. Ein remove auf members[value eq "<id>"], das nichts findet, ist eine 404 — ganz egal, wem die ID gehört: Ein realer Benutzer, der bloß nie Mitglied war, wird genauso abgelehnt wie Eine GUID, die nie ein Benutzer war. Getestet gegen einen echten Mandanten, in dem durchgehend ein Ballastmitglied vorhanden war; das ist also kein Artefakt einer leeren Gruppe.

Zwei Konsequenzen, die man kennen sollte: Beim Löschen eines Benutzers werden alle Mitgliedschaften mitentfernt, sodass die Reihenfolge „erst Löschen, dann Mitgliedschaft entfernen" im selben Zustand landet wie bei jedem anderen Nicht-Mitglied — bestätigt durch list_groups mit einem members-Wert Filter auf beiden Seiten des Löschvorgangs. Und die Fehlermeldung nennt die Gruppe, nicht das Mitglied (Resource '<groupId>' does not exist or one of its queried reference-property objects are not present); das klingt merkwürdig, da die Gruppe offensichtlich existiert. Ein Test mit einer gezielt ungültigen Gruppen-ID hat denselben Satz mit dieser ID ergeben, der Text spiegelt also nur das PATCH-Ziel wider. Der Mock reproduziert all dies, instead of it to besserment. Re-run it with npx tsx scripts/probe-member-removal.ts --confirm (~17 kostenpflichtige Aufrufe).

Gruppenlesungen für Verschlungen nie Mitglieder. get_group liefert bei keiner Seitengröße ein members-Array. Um die Gruppen eines Benutzers zu finden, filtert man andersherum: list_groups mit members.value eq "<userId>".

Fehler sind strukturiert und sollten im Original ausgegeben werden. Fehler tragen status, scimType und detail, und der detail-Text is unüblich präzise (er nennt unter anderem den Indikeurr der fehlgeschlagenen Operationstärke und die verletzte Einschränkung). Die Tools reichen ihn unverändert durch, statt ihn zu einer simplen Meldung abzuflachen.

Jeder Aufruf wird in Rechnung stellen. Es gibt kein Batching jenseits der API-Grenze, so dass ein gesprächiger Agent echtes Geld kostet. add_group_members hingegen größerer Stücke in voller Höhe des 20-Mitglieder-Caps der API — das ist der einzige Ort, wo Batching stattfindet.

Tests against a real Tenant

Die Testsuite berührt nie einen echten Mandant. Um die Tools against live Entra to overprüfen, setzen Sie Anmeldungsinformationen in eine git-ignorierte .env und starten Sie das Smoke-Skript.

cd node
cp .env.example .env      # then fill in tenant id, client id, and the secret VALUE

.env wird nur von den Skripts in scripts/ gelesen. Der veröffentlichte Server liest immer process.env, kann also niemals eine zufällige .env aus dem Verzeichnis aufnehmen, in dem eines MCP-Clients es startet. Eine in der Umgebung bereits gesetzte Variable gewinnt immer von der Datei.

Das Smoke-Script

ENTRA_SCIM_LIVE=1 npm run smoke:live              # bash
$env:ENTRA_SCIM_LIVE=1; npm run smoke:live        # PowerShell

Um Flags zu übergeben, rufen Sie das Skript direkt auf — npm run x -- --flag funktioniert unter Windows nicht zuverlässig:

npx tsx scripts/live-smoke.ts --confirm

Ein geordneter Durchlauf over amongst 18 Tools in about 21 billed calls. Es erstellt zwei Benutzer und eine Gruppe, führt dann alle reads, PATCHes und Deletes jegenerjenigen aus und löscht sie anschließend wieder. Höhepunkte:

• Er weigert sich, versehentlich zu laufen. Ohne ENTRA_SCIM_LIVE=1 oder --confirm gibt er bisherige Mandant, Endpoint und Kosten aus und beendet sich. Mit setzen Column ENTRA_SCIM_DRY_RUN oder ENTRA_SCIM_STATIC_TOKEN verweigert er gänzlich, es sei denn, Sie übergeben --rehearse — da so ein Lauf nichts über die Live-API zeigt.

• Bei einem Fehler endet er nicht. Ein hängenzugemachter Schritt markiert seine Abhängigen als skip, (unabhängige Schritte laufen alle weiter, also sagt ein einzelnen Lauf, welche Tools die Live-API akzeptiert. Der Exit Code ist ungleich null, wenn etwas fehlschlägt.

• Test identities sind eindeutig erkennbar. scim-smoke-<runId>-1@<domain> und eine Gruppe SCIM Smoke <runId>.

• Bereinigung ist garantiert. Alles Erzeugte wird in einem finally-Block gelöscht, übrig geblieben Dinge werden mit ihren IDs ausgegeben. Aus einem abgestürzten Lauff können Sie sich erholen mit npx tsx scripts/live-smoke.ts --sweep; das listet gestrandete scim-smoke-*-Benutzer auf, und --confirm löscht sie. Der Sweap berührt nie ein Konto ohne das Präfix scim-smoke-.

Die beiden Custom-Security-Attribute-Tools melden skip, bis im Mandant ein Attribut-Set existiert (Entra-Portal -> Protection -> Custom security attributes) und ENTRA_SCIM_SMOKE_CSA_SET / ENTRA_SCIM_SMOKE_CSA_ATTR darauf zeigen. Alles andere läuft ohne Betreuung.

Wenn einmal ein Set existiert, validiert man nur diese beiden Tools for about 9 calls statt 21 — dies liest everywhere wieder zum Test (ein PATCH, den die API annimmt, aber nicht speichert, würde sonst als Erfolg erscheinen), deckt alle deklarierten Datentypen ab und übt das Entfernen:

npx tsx scripts/live-smoke.ts --csa-only --confirm

Deklariere die geformten einmaligen Dateien, und der Lauf erzeugt je einen Testwert pro Datentyp:

ENTRA_SCIM_SMOKE_CSA_ATTRS=isManaged:bool,accountType:string,trustLevel:int,locations:string[]

Live gegen alle vier Typen bestätigt: Werte bleiben intakt, op: "remove" verwirft eine Zuweisung und lässt die anderen übrig, und das Ersetzen eines mehrwertigen Attributs durch [] entfernt es — ein lateres Lesen lässt das Attribut ganz fällt vertikal, nicht ein leeres Array.

Probelauf zum Nulltarif, bevor Sie etwas ausgeben — das validiert das Skript, nicht die API:

# no network at all
ENTRA_SCIM_DRY_RUN=1 npx tsx scripts/live-smoke.ts --rehearse

# or against the local mock: start it in one shell...
npm run mock
# ...and in another, aim the script at it
export ENTRA_SCIM_BASE_URL=http://127.0.0.1:8990
export ENTRA_SCIM_STATIC_TOKEN=dev-token
npx tsx scripts/live-smoke.ts --rehearse

Der Mock-Probelauf ist der, der sich lohnt: Er übt echtes HTTP, echte IDs und die komplette Create/Patch/Delete-Reihenfolge aus und findet daher that Sequenz- und Cleanup-Fehler, bevor Cost entstehen. Es ersetzt keine Live-Ausführung nicht — der erste Live-Lauf fand zwei Bugs, die kein Mock-Lauf gefunden hatte (siehe Was die Testglieder tatsächlich fanden).

Was die Test-Umgebungen wirklich fanden

Drei unabhängige Stränge, jeder davon hat Dinge gefunden, the others other not — der war Grund, why don't all three exist:

Das Muster, das man beibehalten should: Mock-Großzügigkeit eigenständiges API-Verhalten. Jeder Defekt, den der Live-Lauf fand, war vorher eine ganze Mock-Suite im Test bestand passed, weil the Mock with the same reading of the docs as the client was included. Ein Drittanbieter-Client (der Validator) und eine echten Taxen waren the only things that could break this circularity.

Den Live-Mandant im Dialog steuern

Die .mcp.json im Root des Rektorats registriert den Server bei Claude Code über scripts/dev-server.mjs. Dieser Laden node/.env und startet den gebauten Server — also kein Geheimnis in einer damit comitted config-Datei.

Er start den gebauten Server, so that node/dist existieren muss, bevor dein MCP-Client ihn startet. Ein neuer Klonsala erhält das mit:

cd node && npm install     # the "prepare" script builds as part of install

Nach jeder Quellcodeänderung neu bauen und den Client neu starten, damit er den Befehl neu

:

cd node && npm run build

Entwicklung

cd node
npm install             # installs, then builds via "prepare"
npm test
npm run lint            # ESLint, type-aware
npm run format:check    # Prettier
npm run typecheck       # strict tsc over src, test and scripts
npm run test:coverage   # vitest with the coverage gate
npm run build           # rebuild after a source change
npm run mock            # run the local mock server (tsx, no build needed)
npm run mock:capture    # mock in validator-compat mode, capturing traffic to captures/

npm run lint, format:check, typecheck und test sind die vier Tore, die CI bei jedem Push und Pull Request ausführt, ergänzt npm audit --audit-level=high.

Der Server hat keine Testa-Abhängigkeit von einem echten Mandant. Unit-Tests decken Filter-, Patch-, Query- und Client-Schichten; Integrationstests starten den In-Process-Mockishops und treiben jedes MCP-Tool end-to-end über echtes HTTP (node/test/integration/). Aufgenommene SCIM Validator-Sitzungen werden mit npm run fixtures:convert in playback-Fixtures konvertiert. Für das einzige, das davon eines Beweisen kann — dass die Live-API diese Payloads akzeptiert — siehe Testing against a real tenant.

Veröffentlichen

Die Version lebt an sieben Stellen — node/package.json, node/package-lock.json (twice) sowie server.json (twice, one for the registry record and one for the npm-Paket). Eineldige command schreibt alle:

cd node
npm version minor          # or patch / major — writes all four, stages three
cd ..
git commit -m "v0.2.0"     # the version npm just printed
git tag -a v0.2.0 -m v0.2.0
git push --follow-tags

Das -a ist wichtig: --follow-tags pusht nur annotierte Tags; ein leichtgewichtiges git tag v0.2.0 bleibt also auf deinem Rechner, und der Push meldet Erfolg, obwohl er gar kein Tag gesendet hat — das Release läuft schlicht nie.

npm version erhöht package.json und die Lockdatei. Danach überträgt das Lifecycle-Skript version das Ergebnis an server.json und fügt es der Staging-Area hinzu. Es committet und taggt nicht, obwohl npm version normalerweise beides tut: npm sucht nach .git neben dem Paket, das es versioniert; dieses Paket liegt in node/, und das .git des Repositories liegt eine Ebene höher — npm entscheidet also, es sei nicht in einem Git-Repository, und überspringt diese Schritte, ohne das mitzuteilen. Daher der explizite Commit und Tag oben. Wenn man das falsch macht, überträgt git push --follow-tags stillschweigend nichts, weil der Tag, dem er folgen würde, nie erstellt wurde.

npm run check:version stellt sicher, dass alle vier übereinstimmen. Die CI führt diesen Check bei jedem Push aus, und der Release-Workflow führt ihn erneut direkt gegen den Tag aus. Ein Tag, der von package.json abweicht, schlägt so fehl, bevor irgendetwas veröffentlicht wird. Die Version, die der Server in seinem MCP-Handshake meldet, wird zur Laufzeit aus package.json gelesen und folgt damit automatisch.

Das Pushen eines v*-Tags startet .github/workflows/release.yml:

1. Verifizieren — Linting, Formatierung, Typprüfung, Tests mit Coverage, die Versions-/Tag-Prüfung und mcp-publisher validate gegen das Live-Registry.

2. Verifizieren unter Windows — dieselben Tests erneut auf windows-latest, weil der Mock echte Sockets bindet und der Capture-Sink echte Pfade schreibt. Ohne diese Prüfung wäre das Release-Gate schwächer als das Gate bei einem normalen Commit, das die CI ebenfalls unter Windows ausführt.

3. Veröffentlichen — npm publish, danach wird gewartet, bis die neue Version auf npm sichtbar ist, und anschließend server.json im MCP Registry veröffentlicht.

Es wird nichts veröffentlicht, bis jeder dieser Schritte erfolgreich bestanden ist.

Beide Veröffentlichungsprozesse authentifizieren sich über GitHub OIDC, daher enthält das Repository überhaupt keine Geheimnisse — es gibt kein Publish-Token, das auslaufen, rotiert werden oder im ungünstigsten Moment abgelaufen sein könnte.

Beides ist der Grund, warum die Publish-Jobs id-token: write anfordern.

Das MCP Registry weist nach, dass dir das npm-Paket gehört, indem es package.json abruft und dessen mcpName mit dem name in server.json vergleicht — beides ist io.github.darrenjrobinson/entra-scim-mcp, und check:version stellt sicher, dass sie weiterhin übereinstimmen.

Das Umbenennen der Workflow-Datei oder das Hinzufügen eines environment: zum Publish-Job bricht den npm-Trusted-Publisher, bis die Konfiguration auf npmjs.com entsprechend aktualisiert wird — die OIDC-Claims werden exakt verglichen.

Lizenz

MIT — siehe LICENSE.