MCP-Server

Kurzantwort: Der CDMS-Hub stellt unter POST/GET /api/mcp einen Model-Context-Protocol-Server bereit. KI-Clients können damit das Meta-Modell Ihrer CDMS-Systeme lesen und Strukturänderungen über eine kontrollierte, freigabepflichtige Pipeline einbringen – ohne direkten Datenbank- oder REST-Zugriff. Authentifiziert wird über OAuth 2.1/OIDC; die Zugangsdaten für Ihren Client erhalten Sie vom Betreiber des Hubs.

Eckdaten


Endpunkt	`POST/GET {baseUrl}/api/mcp`
Transport	Streamable HTTP (MCP Java SDK)
Server-Name	`codamai-cdms-mcp`
Capabilities	`tools`
Auth	OAuth 2.1 / OIDC, Bearer-Token verpflichtend
Discovery	`GET {baseUrl}/.well-known/oauth-protected-resource/api/mcp` (RFC 9728)

Der Transport läuft durch dieselbe Filterkette wie die REST-API. Jeder Tool-Aufruf findet im echten Benutzerkontext statt; Mandanten-, Owner- und Rechteprüfungen greifen unverändert. Sie sehen über MCP also genau die Systeme und Elemente, die Ihr Zugang auch sonst sieht.

Authentifizierung

Der Server ist eine geschützte Ressource nach RFC 9728:

Das Protected-Resource-Metadata-Dokument ist ohne Token abrufbar und nennt den zuständigen Authorization Server.
Ein MCP-Request ohne Token wird mit 401 und WWW-Authenticate: Bearer resource_metadata="…" beantwortet – das löst beim Client den Authorization-Code-Flow mit PKCE aus.
Ein abgelehntes oder abgelaufenes Token führt ebenfalls zu 401, damit sich der Client neu anmeldet, statt hart zu scheitern.

Ihr Zugang

Jeder Entwickler bzw. jedes Team bekommt einen eigenen OAuth-Client. Dynamische Client-Registrierung (RFC 7591) ist abgeschaltet – ein selbstregistrierter Client wäre unkonfiguriert und käme an keine Daten. Sie erhalten stattdessen vom Betreiber:

Angabe	Bedeutung
Basis-URL	wohin der MCP-Client verbindet, z. B. `https://<host>/api/mcp`
Client-ID	Ihre Anwendungsidentität, öffentlich und unkritisch
Callback-Port	der lokale Port, der als Redirect-URI hinterlegt ist

Es gibt kein Client-Secret: Der Client ist öffentlich, die Absicherung übernimmt PKCE (S256). Ein Desktop- oder CLI-Werkzeug kann ein Secret ohnehin nicht geheim halten.

Ihr Benutzerkonto entscheidet über die Sichtbarkeit — nicht der Client. Ohne Berechtigung auf ein CDMS-System taucht es in cdms_list_targets nicht auf.

Anbindung in Claude Code

Setzen Sie die drei Angaben aus Ihrem Zugang ein:

claude mcp add --transport http --client-id <ihre-client-id> --callback-port <port> \
  codamai-cdms https://<host>/api/mcp

--transport http steht vor Name und URL
--client-id und --callback-port sind nicht optional – ohne sie versucht der Client eine dynamische Registrierung, die abgelehnt wird
kein --client-secret (öffentlicher Client mit PKCE)
Anmeldung in der Session über /mcp → Authenticate; der Browser öffnet sich, nach dem Login ist der Server verbunden

Manuelle Variante in .mcp.json:

{
  "mcpServers": {
    "codamai-cdms": {
      "type": "http",
      "url": "https://<host>/api/mcp",
      "oauth": { "clientId": "<ihre-client-id>", "callbackPort": <port> }
    }
  }
}

Kein Authorization-Header eintragen – das Token holt sich der Client über den OAuth-Flow. Die clientId ist unkritisch und darf eingecheckt werden.

Werkzeuge

Lesend

Tool	Zweck
`cdms_list_targets`	alle CDMS-Systeme, auf die der Benutzer zugreifen darf
`cdms_get_target`	Metadaten eines CDMS (ID oder eindeutiger Name)
`cdms_get_capabilities`	unterstützte Feldtypen, Beziehungstypen, Regeln, Rollen, Namensregeln – vor jedem Blueprint zu lesen
`cdms_get_structure`	Ordnerstruktur mit IDs, Eltern-Ordnern, Pfaden
`cdms_get_schema`	vollständiges Ist-Schema
`cdms_get_element`	einzelnes Element per ID, inkl. Elementtyp, Besitzer und Blueprint-Schlüssel (`/crm/Customer#name`)
`cdms_create_operation_context` / `cdms_get_operation_context`	Operation Context anlegen/lesen

Dazu Resources unter cdms://targets/{cdmsId}/… (Schema, Ordner, Enums, Modelle, Elemente) sowie cdms://operations/{id} und cdms://change-sets/{id}. Tools und Resources bedient dieselbe Schicht (CdmsReadService), damit beide identisch antworten.

Schreibend – die Pipeline

Tool	Zweck
`cdms_validate_blueprint`	Blueprint serverseitig prüfen, ohne etwas zu ändern
`cdms_plan_changes`	Blueprint gegen den Ist-Zustand diffen → unveränderlicher Change Plan mit `planId`, CREATE/UPDATE/UNCHANGED, markierten destruktiven Änderungen und `blueprintHash`
`cdms_create_change_set`	Plan als Change Set einfrieren (`PENDING_APPROVAL`)
`cdms_approve_change_set`	Freigabe – nur nach ausdrücklicher Bestätigung durch den Benutzer
`cdms_apply_change_set`	genau einmalige, transaktionale Anwendung
`cdms_get_change_set_status`	Status, Freigabe- und Ausführungsergebnis
`cdms_rollback_change_set`	Kompensation: löscht nur die selbst erzeugten Elemente in umgekehrter Reihenfolge

Ablauf einer Änderung

flowchart TB
    A[cdms_list_targets] --> B[cdms_get_capabilities]
    B --> C[cdms_get_schema]
    C --> D["cdms_create_operation_context<br/>bindet alles an ein CDMS"]
    D --> E[cdms_validate_blueprint]
    E --> F[cdms_plan_changes]
    F --> G["Plan wird dem Benutzer gezeigt"]
    G --> H[cdms_create_change_set]
    H --> I["Benutzer bestätigt"]
    I --> J[cdms_approve_change_set]
    J --> K["cdms_apply_change_set<br/>einmalig, phasenweise, transaktional"]
    K --> L["nur falls nötig, nach erneuter Bestätigung:<br/>cdms_rollback_change_set"]

Phasenreihenfolge beim Anwenden: Ordner → Enums → abstrakte Modelle → Datenmodelle → Felder → Beziehungen. Danach die Abschlussvalidierung: Der Ist-Zustand wird in derselben Transaktion neu gelesen und geprüft, ob jedes geplante Element genau einmal existiert – schlägt das fehl, wird das komplette Change Set zurückgerollt.

Ziel-CDMS und Operation Context

Das Hub verwaltet die Design-Daten mehrerer CDMS-Systeme. Der Client wählt das Ziel deshalb immer explizit – nie implizit, nie geraten. Ein mehrdeutiger Name führt zu CDMS_TARGET_AMBIGUOUS.

Für jede Änderungsabsicht entsteht ein Operation Context, der alle Folgeaufrufe unveränderlich an genau ein CDMS bindet; ein Zielwechsel innerhalb einer Operation ist ausgeschlossen (CDMS_TARGET_MISMATCH).

Sicherheitsleitplanken

kein direkter Datenbankzugriff – alles über zugriffsgeprüfte System-Layer
kein Schreiben ohne Plan und Freigabe
Change Sets sind genau einmal anwendbar und werden vor der Ausführung gegen den Ist-Zustand geprüft (SCHEMA_VERSION_CONFLICT)
destruktive Änderungen werden markiert und blockiert (DESTRUCTIVE_CHANGE_BLOCKED)
Enum-Werte werden nie gelöscht (add-only Diff)
Fehler kommen als stabile Codes zurück, Interna nur ins Log

Fehlercodes: CDMS_TARGET_NOT_FOUND, CDMS_TARGET_AMBIGUOUS, CDMS_TARGET_MISMATCH, CDMS_ACCESS_DENIED, CDMS_CAPABILITY_NOT_SUPPORTED, OPERATION_CONTEXT_NOT_FOUND, BLUEPRINT_INVALID, BLUEPRINT_REFERENCE_NOT_FOUND, BLUEPRINT_CYCLE_DETECTED, SCHEMA_VERSION_CONFLICT, CHANGE_SET_NOT_APPROVED, CHANGE_SET_ALREADY_APPLIED, DESTRUCTIVE_CHANGE_BLOCKED, RELATION_INVALID, ROLE_INVALID, EXECUTION_FAILED, ROLLBACK_FAILED.

Berechtigungen im Client

Die lesenden Tools sind unkritisch und dürfen in die Allowlist. Die schreibende Pipeline bleibt bewusst genehmigungspflichtig – cdms_approve_change_set, cdms_apply_change_set und cdms_rollback_change_set gehören nie in eine Allowlist.

Grenzen

fileUploads lassen sich im Blueprint noch nicht beschreiben; ein solcher Blueprint wird mit CDMS_CAPABILITY_NOT_SUPPORTED abgelehnt.
Change Sets sind kurzlebig: Ein Plan ist 30 Minuten gültig, ein Change Set zwei Stunden. Danach neu planen.
Claude Desktop verlangt dynamische Client-Registrierung und funktioniert deshalb nicht. Für Claude Code und andere Clients mit fester Client-ID gilt die Anleitung oben.