Konfiguration

Synit AD MCP stellt read-only Werkzeuge für Enterprise Active Directory (AD) über das Model Context Protocol bereit. MCP wird getrennt vom ADProxy HTTP-Service betrieben. Diese Trennung ist der Kern des Sicherheitsmodells: MCP liest und bereitet optional Request-Entwürfe vor, schreibt aber nicht in Active Directory.

Sicherheitsmodell

• ADProxy HTTP steuert Plan, Review, Apply, Verify und Audit.
• AD MCP stellt read-only Kontext für Agenten bereit.
• Optional kann MCP einen Body für POST /api/v1/mutations/plan vorbereiten.
• Der Entwurf wird außerhalb von MCP an ADProxy HTTP übergeben und dort normal geprüft.

Beispielkonfiguration

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"

  tls {
    ca_file     = "/etc/adproxy/tls/ad-ca.pem"
    server_name = "dc1.example.test"
  }
}

schema {
  cache_path = "/var/lib/adproxy/schema_cache.json"
}

cache {
  validation_enabled = true
  ttl_min     = "5s"
  ttl_default = "30s"
  ttl_max     = "5m"
}

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

redaction {
  force_allowed_attributes  = ["badPwdCount", "badPasswordTime"]
  force_redacted_attributes = ["customSecretAttribute"]
}

mcp {
  enabled                = true
  transport              = "streamable-http"
  listen_addr            = "127.0.0.1:8768"
  auth_token             = "<mcp-bearer-token>"
  enable_mutation_drafts = false
  rate_limit_rps         = 10
  rate_limit_burst       = 20
  attribute_allow_list   = ["cn", "mail", "sAMAccountName", "memberOf", "department", "title"]
  attribute_deny_list    = ["telephoneNumber"]
  max_recursive_depth    = 5

  audit {
    enabled      = true
    file_enabled = true
    file_path    = "/var/log/adproxy/mcp-audit.jsonl"
    audit_level  = "info"
  }
}

MCP starten

Starten Sie MCP getrennt vom ADProxy HTTP-Service:

export AD_MCP_BIND_PASSWORD='<ad-read-password>'
adproxy-mcp -config admcp.hcl

adproxy-server stellt kein /mcp bereit. Wenn Sie ADProxy HTTP und AD MCP gemeinsam nutzen, laufen beide Services getrennt und erhalten eigene Tokens, Logs und Betriebsfreigaben.

Transport

Transport	Einsatz
streamable-http	Agenten, Gateways oder Tools verbinden sich per HTTP auf /mcp.
stdio	Lokale Agenten starten MCP als Unterprozess.
both	Beide Varianten sind verfügbar, wenn die Umgebung das bewusst benötigt.

Für produktive Integrationen ist streamable-http meist einfacher zu betreiben, weil Auth, Proxy, TLS und Monitoring klarer angebunden werden können.

Streamable HTTP nutzt diese Endpunkte:

Methode	Pfad	Zweck
POST	/mcp	JSON-RPC Requests senden
GET	/mcp	SSE Heartbeat Stream öffnen
DELETE	/mcp	Session beenden

stdio liest JSON-RPC von stdin und schreibt Antworten nach stdout. Das passt für lokale Agenten, die den Prozess selbst starten.

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | adproxy-mcp -config admcp.hcl

Streamable-HTTP-Session

MCP nutzt JSON-RPC 2.0. Bei Streamable HTTP wird zuerst eine Session initialisiert. Die Antwort enthält einen Mcp-Session-Id Header, der bei weiteren Calls mitgegeben wird.

curl -sS -i -X POST https://admcp.example.test/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": "service-desk-agent",
        "version": "1.0"
      }
    }
  }'

Danach:

curl -sS -X POST https://admcp.example.test/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"}'

Tool-Aufruf

curl -sS -X POST https://admcp.example.test/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"
      }
    }
  }'

Mutation-Drafts aktivieren

Mutation-Drafts sind standardmäßig aus. Wenn sie aktiviert werden, erzeugt MCP nur einen Request-Body für den HTTP Plan Endpoint. Es wird kein Plan erstellt und nichts angewendet.

mcp {
  enabled                = true
  transport              = "streamable-http"
  listen_addr            = "127.0.0.1:8768"
  auth_token             = "<mcp-bearer-token>"
  enable_mutation_drafts = true
}

Sicherheitsgrenzen:

• MCP ruft keinen HTTP Endpoint auf.
• MCP erstellt keinen Live-Plan.
• MCP führt keinen Apply aus.
• MCP gibt keinen ausführbaren Schreibbefehl zurück.
• force, risk, show_secret_outputs und Passwortmaterial werden im Draft abgelehnt.
• Der zurückgegebene Body muss außerhalb von MCP über ADProxy HTTP geprüft werden.

Redaction und sichtbare Attribute

Redaction erfolgt in mehreren Schritten:

• Harte Secret-Attribute wie Passwortmaterial, LAPS, BitLocker, Fotos und Security Descriptors bleiben redigiert.
• redaction.force_redacted_attributes sperrt eigene sensible Attribute.
• redaction.force_allowed_attributes erlaubt ausgewählte operative Attribute wie badPwdCount.
• Defensive Muster redigieren secret-, token-, password- oder key-ähnliche Namen.
• mcp.attribute_allow_list begrenzt die sichtbaren Attribute.
• mcp.attribute_deny_list redigiert zusätzliche Attribute.

Die MCP Allow-Liste hebt keine harte Secret-Redaction auf.

Immer redigiert werden zum Beispiel Passwortmaterial, LAPS-/BitLocker-Werte, Fotos und Security Descriptors. Typische Attribute sind unicodePwd, ntPwdHistory, userPassword, supplementalCredentials, msDS-ManagedPassword, ms-Mcs-AdmPwd, msLAPS-EncryptedPassword, msFVE-RecoveryPassword, thumbnailPhoto, jpegPhoto, securityDescriptor und nTSecurityDescriptor.

Rate Limits

mcp {
  rate_limit_rps   = 10
  rate_limit_burst = 20
}

Bei gesetztem auth_token wird pro Token begrenzt. Ohne Auth wird nach Quell-IP begrenzt. Für produktive Umgebungen sollte Auth aktiv sein.

MCP-Audit

mcp {
  audit {
    enabled      = true
    file_enabled = true
    file_path    = "/var/log/adproxy/mcp-audit.jsonl"
    audit_level  = "info"
  }
}

MCP Audit protokolliert JSON-RPC Requests, Tool Calls, Outcome, Dauer und redigierte Antworten. Authorization wird nicht geloggt. Proxy-Header wie X-Forwarded-For sind nur Hinweise; Vertrauen muss am Proxy-Rand geregelt werden.

Syslog kann zusätzlich aktiviert werden:

mcp {
  audit {
    enabled      = true
    file_enabled = true
    file_path    = "/var/log/adproxy/mcp-audit.jsonl"
    audit_level  = "info"

    syslog {
      enabled         = true
      server          = "tls://mcp-syslog.example.test:6514"
      facility        = "local0"
      app_name        = "adproxy-mcp-audit"
      connect_timeout = "2s"
      write_timeout   = "500ms"
      ca_file         = "/etc/adproxy/syslog-ca.pem"
      server_name     = "mcp-syslog.example.test"
    }
  }
}

Praxis für produktionsnahe Nutzung

MCP mit read-only Active-Directory-Rechten betreiben. Query-Policy auf die benötigten OUs und Attribute begrenzen. Mutation-Drafts nur aktivieren, wenn der HTTP Review-Prozess klar ist. MCP Audit für produktive Agenten aktivieren. Für schreibende Änderungen immer den ADProxy HTTP Plan/Apply-Weg verwenden.