Synit AD MCP

Tools

Read-only MCP Tools für Enterprise Active Directory: Benutzer- und Gruppensuche, Schema, Lookup, Redaction, Grenzen, Rate Limits und Fehlercodes.

Tools

Synit AD MCP stellt Werkzeuge bereit, die Enterprise Active Directory (AD) lesen und strukturierte Antworten zurückgeben. Schreibende Operationen werden abgewiesen.

Query-Tools für Benutzer, Gruppen und Objekte

Tool Zweck
search_user_by_sam Benutzer über sAMAccountName suchen
search_user_by_mail Benutzer über Mailadresse suchen
search_by_attribute Objekte über ein Attribut suchen
list_group_members Gruppenmitglieder lesen, optional rekursiv
get_object einzelnes Objekt per DN lesen
get_group_membership Gruppenmitgliedschaften eines Benutzers lesen
query generischer Wrapper für die read-only Query-Operationen

Beispiel:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_user_by_sam",
    "arguments": {
      "sam_account_name": "jdoe"
    }
  }
}

Generischer Wrapper:

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "query",
    "arguments": {
      "operation": "search_user_by_sam",
      "parameters": {
        "sam_account_name": "jdoe"
      }
    }
  }
}

Suche per Mailadresse:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "search_user_by_mail",
    "arguments": {
      "mail": "jane.doe@example.test"
    }
  }
}

Suche per Attribut:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "search_by_attribute",
    "arguments": {
      "attribute_name": "department",
      "value": "Engineering"
    }
  }
}

Gruppenmitglieder rekursiv lesen:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "list_group_members",
    "arguments": {
      "group_dn": "CN=Engineering Users,OU=Groups,DC=example,DC=test",
      "recursive": true
    }
  }
}

Ein Objekt lesen und Cache umgehen:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "get_object",
    "arguments": {
      "dn": "CN=Jane Doe,OU=Users,DC=example,DC=test",
      "force_refresh": true
    }
  }
}

Gruppenmitgliedschaften eines Benutzers:

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "get_group_membership",
    "arguments": {
      "user_dn": "CN=Jane Doe,OU=Users,DC=example,DC=test"
    }
  }
}

Antworten nutzen MCP content-Einträge vom Typ text. Objektlisten und Objekte werden als JSON innerhalb des Textfelds zurückgegeben.

Schema-Tools

Tool Zweck
get_schema ADProxy HTTP API-Kontrakt abrufen
get_class Metadaten zu einer Active-Directory-Objektklasse lesen
get_attribute Attributmetadaten und Schreibklassen-Hinweise lesen

Diese Tools helfen Agenten und Integrationen, gültige Requests vorzubereiten, statt Active-Directory-Felder zu raten.

API-Kontrakt abrufen:

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "get_schema",
    "arguments": {}
  }
}

Objektklasse prüfen:

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "get_class",
    "arguments": {
      "class_name": "user"
    }
  }
}

Attribut prüfen:

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "get_attribute",
    "arguments": {
      "attribute_name": "sAMAccountName"
    }
  }
}

Lookup

lookup_object löst einen Selector zu DN, objectGUID und objectClass auf.

Beispiel:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "lookup_object",
    "arguments": {
      "selector": "sAMAccountName=jdoe",
      "object_class": "user"
    }
  }
}

Ohne object_class versucht MCP eine eindeutige classless Suche und erkennt die Objektklasse aus dem Ergebnis:

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "lookup_object",
    "arguments": {
      "selector": "sAMAccountName=jdoe"
    }
  }
}

Beispielantwort:

{
  "jsonrpc": "2.0",
  "id": 12,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"dn\":\"CN=Jane Doe,OU=Users,DC=example,DC=test\",\"object_guid\":\"00000000-0000-0000-0000-000000000000\",\"object_class\":\"user\"}"
      }
    ]
  }
}

lookup_object kann Ergebnisse kurzfristig cachen. Mit force_refresh wird der Cache umgangen.

Redaction

Antworten werden redigiert, bevor sie an den Agenten zurückgehen. Besonders sensible Attribute wie Passwortmaterial, LAPS-/BitLocker-Werte, Security Descriptors, private Schlüssel oder Secret-ähnliche Attribute werden nicht offengelegt.

Zusätzlich können erlaubte und gesperrte Attribute konfiguriert werden.

Die Redaction-Reihenfolge:

  • Harte Secret-Attribute werden immer redigiert.
  • Globale Force-Redaction sperrt zusätzliche Attribute.
  • Globale Force-Allow-Liste erlaubt bewusst ausgewählte operative Attribute.
  • Defensive Muster redigieren secret-, token-, password- oder key-ähnliche Namen.
  • MCP Allow-Liste begrenzt die verbleibenden Attribute.
  • MCP Deny-Liste redigiert zusätzliche Treffer.

Grenzen

  • Mutation-Operationen wie delete_object, modify_attributes oder set_password sind im Query Tool nicht erlaubt.
  • MCP erstellt keinen Live-Plan.
  • MCP führt keinen Apply aus.
  • MCP gibt keine ausführbaren Schreibbefehle zurück.
  • Schreibende Freigabe bleibt ADProxy HTTP vorbehalten.

Rate Limits

Streamable HTTP MCP kann pro Client begrenzt werden. Das schützt Active Directory und die MCP-Schnittstelle vor zu vielen Agenten- oder Tool-Anfragen.

Tool-Discovery

Agenten können verfügbare Tools abfragen:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Die Liste hängt von der Konfiguration ab:

  • Read-only Query Tools sind verfügbar, wenn MCP aktiv ist.
  • get_schema ist verfügbar, wenn der API-Kontrakt bereitsteht.
  • get_class und get_attribute benötigen Schema-Metadaten.
  • draft_mutation_request erscheint nur bei mcp.enable_mutation_drafts = true.

Fehler

Fehler folgen JSON-RPC 2.0:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32600,
    "message": "Invalid Request",
    "data": "missing required parameter: sam_account_name"
  }
}

Häufige Codes:

Code Bedeutung
-32700 JSON konnte nicht gelesen werden
-32600 ungültiger Request
-32601 Methode nicht bekannt
-32602 ungültige Parameter
-32603 interner Fehler
-32000 Rate Limit erreicht
United in Diversity