Synit AD MCP

Einführung

Einstieg in Synit AD MCP: sichere read-only AD-Abfragen, Schema-Kontext, Service-Desk-Use-Cases und optionale Drafts für ADProxy-Pläne.

Einführung

Synit AD MCP stellt Kontext aus Enterprise Active Directory (AD) für AI-Agenten, Service-Desk-Tools und Automationen bereit. Die Schnittstelle ist bewusst read-only. Sie kann Active Directory lesen, Schema verstehen und optional Request-Entwürfe vorbereiten, aber keine Active-Directory-Änderungen ausführen.

Schreibende Änderungen bleiben im ADProxy HTTP-Kontrollpfad mit Plan, Review, Apply, Verifikation und Audit.

Wofür AD MCP eingesetzt wird

Benutzer oder Gruppen strukturiert suchen.
Gruppenmitgliedschaften analysieren.
Einzelne Active-Directory-Objekte lesen.
Active-Directory-Schema und Attribute verstehen.
Objektidentitäten für spätere ADProxy-Pläne auflösen.
Optional Request-Entwürfe für den HTTP-Plan-Endpunkt vorbereiten.

Verfügbarkeit und sicherer Start

Synit AD MCP ist als separate Container-Laufzeit geplant. Eine freie Container-Variante ist für Evaluation, Laborumgebungen und kleine Piloten vorgesehen. Die konkrete Registry-URL, Funktionsgrenzen und Lizenzbedingungen werden in den Lizenzhinweisen ergänzt, sobald der öffentliche Lieferweg final ist.

MCP bleibt im Standardpfad read-only. Ohne Testlauf in einer passenden Test- oder Pilotumgebung gibt synit.io keine Zusicherung, dass Query-Policy, Redaction oder Agenten-Integration für eine konkrete Active-Directory-Umgebung geeignet sind.

Warum die Schnittstelle read-only bleibt

Active Directory ist ein kritischer Identitätskern.
Agenten können hilfreich sein, wenn sie Kontext sammeln und Vorschläge vorbereiten.
Sie sollten aber nicht direkt schreiben.

AD MCP trennt deshalb:

Recherche: über MCP, read-only und redigiert.
Änderung: über ADProxy HTTP, geprüft und auditierbar.

Geeignete erste Anwendungsfälle

Service-Desk-Recherche

Ein Tool fragt Benutzerstatus, Gruppenmitgliedschaften oder Objektinformationen ab, damit Tickets schneller eingeordnet werden können.

IAM-Vorbereitung

Ein Agent sammelt Active-Directory-Kontext für ein Onboarding, Offboarding oder eine Gruppenänderung, bevor ein ADProxy-Plan erstellt wird.

Schema Discovery

Integrationen prüfen, welche Objektklassen, Attribute und Operationen gültig sind.

Request-Draft für ADProxy

Wenn aktiviert, kann MCP einen strukturierten Body für POST /api/v1/mutations/plan vorbereiten. Dieser Body muss außerhalb von MCP an ADProxy HTTP übergeben und dort geprüft werden.

Use-Case: Agenten-Dialog im Service Desk

Das folgende Beispiel ist fiktiv und nutzt .example.test Werte. Es zeigt, wie ein AI-Agent mit read-only MCP-Zugriff Active-Directory-Kontext sammelt, Folgefragen beantwortet und am Ende einen ADProxy-Entwurf vorbereitet. MCP schreibt dabei nicht in Active Directory.

Service Desk:
Prüfe bitte den Benutzer jane.doe@example.test. Ich brauche Name, Account-Status und die wichtigsten Gruppen.

AI-Agent:
Ich suche den Benutzer über die Mailadresse und lese danach das Objekt sowie die Gruppenmitgliedschaften.

Verwendete MCP-Werkzeuge:

search_user_by_mail
get_object
get_group_membership

Ergebnis:

Benutzer: Jane Doe
sAMAccountName: jdoe
DN: CN=Jane Doe,OU=Users,DC=example,DC=test
Mail: jane.doe@example.test
Account wirkt aktiv, soweit die freigegebenen Attribute das zeigen.
Sichtbare Gruppen:
- CN=Engineering Users,OU=Groups,DC=example,DC=test
- CN=VPN Users,OU=Groups,DC=example,DC=test
- CN=Project Atlas,OU=Groups,DC=example,DC=test

Redigierte oder gesperrte Attribute wurden nicht ausgegeben.

Service Desk:
Wann war der letzte bekannte Logon? Und ist sie in einer Admin-Gruppe?

AI-Agent:
Ich lese die freigegebenen Logon-Attribute und prüfe die Gruppen rekursiv.

Verwendete MCP-Werkzeuge:

get_object
get_group_membership
optional list_group_members für konkrete Gruppen

Ergebnis:

lastLogonTimestamp: 2026-07-01T07:42:18Z
lastLogon: nicht freigegeben oder nicht sichtbar im aktuellen Attributsatz
Keine sichtbare Mitgliedschaft in Domain Admins, Enterprise Admins oder einer freigegebenen Admin-Gruppe.
Hinweis: lastLogonTimestamp ist repliziert und kann verzögert sein. Für forensische Prüfungen sollte ein AD-Admin die Domain-Controller-spezifischen Werte prüfen.

Service Desk:
Der Benutzer soll aus VPN Users entfernt werden. Kannst du das vorbereiten?

AI-Agent:
Ich kann keinen Schreibvorgang ausführen. Ich kann aber einen ADProxy Mutation-Draft vorbereiten, der außerhalb von MCP geprüft und manuell an den ADProxy Plan-Endpunkt übergeben wird.

Verwendete MCP-Werkzeuge:

lookup_object
draft_mutation_request

Entwurf:

{
  "method": "POST",
  "path": "/api/v1/mutations/plan",
  "executes": false,
  "plan_created": false,
  "requires_user_submission": true,
  "body": {
    "source": "mcp-draft",
    "response_detail": "standard",
    "operations": [
      {
        "id": "remove_vpn_membership",
        "operation_type": "remove_group_member",
        "target": {
          "dn": "CN=VPN Users,OU=Groups,DC=example,DC=test"
        },
        "object_class": "group",
        "member_dn": "CN=Jane Doe,OU=Users,DC=example,DC=test"
      }
    ]
  },
  "next_step": "Submit body to ADProxy POST /api/v1/mutations/plan outside MCP, review the plan, then apply only through the approved ADProxy HTTP flow."
}

Service Desk:
Warum nicht direkt anwenden?

AI-Agent:
MCP ist read-only. Der Entwurf ist nur Vorbereitung. Ein Mensch oder eine freigegebene Automation muss den Body an ADProxy HTTP übergeben, den Plan prüfen und danach bewusst Apply auslösen. So bleiben Review, Verifikation, Journal und Audit im ADProxy-Kontrollpfad.

Schnellstart für einen read-only Pilot

Dieser Ablauf startet MCP read-only für eine erste kontrollierte Abfrage. Schreibende Vorgänge bleiben außerhalb von MCP.

1. Werte vorbereiten

AD-Domain, zum Beispiel example.test
Domain Controller, zum Beispiel dc1.example.test
read-only Servicekonto
Pilot-OU, zum Beispiel OU=Users,DC=example,DC=test
MCP Bearer Token

2. Minimale Konfiguration anlegen

directory {
  domain            = "example.test"
  bind_url          = "ldaps://dc1.example.test"
  bind_dn           = "CN=svc-adproxy-read,OU=Service Accounts,DC=example,DC=test"
  bind_password_ref = "env:AD_MCP_BIND_PASSWORD"
  hosts             = ["dc1.example.test"]
  timeout           = "30s"
}

query_policy {
  allowed_base_dns  = ["OU=Users,DC=example,DC=test"]
  allowed_attrs     = ["cn", "mail", "sAMAccountName", "memberOf"]
  denied_attrs      = ["unicodePwd", "ntSecurityDescriptor"]
  allow_raw_filters = false
}

mcp {
  enabled      = true
  transport    = "streamable-http"
  listen_addr  = "0.0.0.0:8768"
  auth_token   = "<mcp-bearer-token>"
  rate_limit_rps   = 10
  rate_limit_burst = 20
}

3. Starten

export AD_MCP_BIND_PASSWORD='<ad-read-password>'
docker run --rm \
  -p 8768:8768 \
  -e AD_MCP_BIND_PASSWORD \
  -v "$(pwd)/admcp.hcl:/etc/adproxy/admcp.hcl:ro" \
  --name synit-ad-mcp \
  <container-image> \
  adproxy-mcp -config /etc/adproxy/admcp.hcl

4. Session initialisieren

curl -sS -i -X POST http://127.0.0.1:8768/mcp \
  -H "Authorization: Bearer <mcp-bearer-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {
        "name": "pilot-client",
        "version": "1.0"
      }
    }
  }'

Merken Sie sich den Header Mcp-Session-Id.

5. Session bereit melden

curl -sS -X POST http://127.0.0.1:8768/mcp \
  -H "Authorization: Bearer <mcp-bearer-token>" \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <session-id>" \
  -d '{
    "jsonrpc": "2.0",
    "method": "notifications/initialized"
  }'

6. Erstes Tool aufrufen

curl -sS -X POST http://127.0.0.1:8768/mcp \
  -H "Authorization: Bearer <mcp-bearer-token>" \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <session-id>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "search_user_by_sam",
      "arguments": {
        "sam_account_name": "jdoe"
      }
    }
  }'

Wenn dieser Call funktioniert, prüfen Sie Audit, Redaction und Query-Policy, bevor Sie weitere Tools oder Agenten anbinden.

Einführung

Wofür AD MCP eingesetzt wird

Verfügbarkeit und sicherer Start

Warum die Schnittstelle read-only bleibt

Geeignete erste Anwendungsfälle

Service-Desk-Recherche

IAM-Vorbereitung

Schema Discovery

Request-Draft für ADProxy

Use-Case: Agenten-Dialog im Service Desk

Schnellstart für einen read-only Pilot

1. Werte vorbereiten

2. Minimale Konfiguration anlegen

3. Starten

4. Session initialisieren

5. Session bereit melden

6. Erstes Tool aufrufen

Nächste Schritte in der Dokumentation