Schema change through the MCP server

What this is about

You can maintain models in the hub by hand. But you can also let an AI client change them, for example Claude. For this, the hub has an MCP server. MCP (Model Context Protocol) is a standard that lets an AI client call the tools of a server.

The AI client does not simply start writing. Every change goes through the same gate: describe, check, plan, get your approval, apply once.

Three terms come up again and again on this page:

The tools

The MCP server offers 15 tools. Most of them only read.

In the hub, a CDMS is a module. Its ID is the cdmsId that all tools work with. The same information is also available as readable MCP resources under cdms://targets/{cdmsId}/….

The path of a change

This is what it looks like as a conversation between the parties:

sequenceDiagram
    actor B as User
    participant K as AI client
    participant M as MCP server (hub)
    participant DB as Hub database
    K->>M: cdms_list_targets, cdms_get_capabilities, cdms_get_schema
    M-->>K: targets, rules, current schema
    K->>M: cdms_create_operation_context(cdmsId)
    M-->>K: operationId (valid for 30 min)
    K->>M: cdms_validate_blueprint(operationId, blueprint)
    M-->>K: valid, errors, warnings
    K->>M: cdms_plan_changes(operationId, blueprint)
    M-->>K: planId, summary, changes, destructiveChanges
    K->>M: cdms_create_change_set(operationId, planId)
    M-->>K: changeSetId, PENDING_APPROVAL
    K->>B: shows the plan
    B-->>K: "Yes, apply"
    K->>M: cdms_approve_change_set(operationId, changeSetId, confirmDestructive)
    M-->>K: APPROVED
    K->>M: cdms_apply_change_set(operationId, changeSetId, idempotencyKey)
    M->>DB: read the current schema again and compare
    M->>DB: all changes in one transaction
    M-->>K: APPLIED + result per element

The blueprint

The blueprint is a JSON document. It describes folders, enums, models, fields, relations and access filters the way they should exist after the change.

{
  "operationId": "4c2b…",
  "blueprint": {
    "blueprintVersion": "1",
    "target": { "cdmsId": "a7f5…", "expectedCdmsName": "CVC Backend" },
    "folders": [
      { "ref": "folder.crm", "name": "CRM",
        "existingFolderId": "2a7f…" }            ← existing folder
    ],
    "enums": [
      { "ref": "enum.status", "folderRef": "folder.crm",
        "name": "CUSTOMER_STATUS",
        "values": [ { "key": "ACTIVE" }, { "key": "BLOCKED" } ] }
    ],
    "models": [
      { "ref": "model.customer", "folderRef": "folder.crm",
        "name": "Customer",                      ← already exists
        "fields": [
          { "ref": "field.customer.status", "name": "status",
            "type": "ENUM", "enumRef": "enum.status",
            "required": true }
        ] }
    ]
  }
}

{
  "valid": true,
  "errors": [],
  "warnings": [
    { "code": "BLUEPRINT_INVALID", "element": "model.customer",
      "message": "Das Modell '/crm/Customer' existiert bereits … wird wiederverwendet …" }
  ],
  "models": [ { "ref": "model.customer", "existingId": "9b1…" } ], …
}

You should know four rules:

1. Symbolic names instead of IDs. Elements refer to each other through their ref, for example enumRef: "enum.status". The hub assigns the IDs.
2. Add, never delete silently. The hub recognizes what already exists by its path (/crm/Customer) and reuses it. What is missing from the blueprint stays unchanged. Changing or deleting existing things only works explicitly through the migrations section.
3. What you use, you declare too. If you want to reference an existing model or enum, it must be in the blueprint, otherwise you get BLUEPRINT_REFERENCE_NOT_FOUND. For existing folders you set existingFolderId.
4. A relation is a pair of fields. Both sides are in the blueprint as a RELATION field and point to each other through inverseFieldRef, see Both sides of a relation.
5. Do not name an environment. A CDMS has no environment: its model is the same in development, test and production, and the environments differ only in their data. target.expectedEnvironment is therefore an error.

The hub checks strictly: an unknown JSON key is already an error. But it collects all content findings, so the AI client can fix everything in one pass.

Explicit changes: migrations

Everything that changes or removes existing things is its own entry under migrations:

Every migration counts as destructive in the plan. A cascading delete through a relation, a removed access filter and a model that is audited are destructive as well. You approve a change set with destructive changes only with a dedicated role and only if you confirm those changes separately, see “Approving destructive changes” further down.

The plan

cdms_plan_changes validates once more and then compares the blueprint with the current schema. The result is a plan:

{ "operationId": "4c2b…", "blueprint": { … as above … } }

{
  "planId": "af72…",
  "summary": { "createCount": 2, "updateCount": 0, "deleteCount": 0,
               "unchangedCount": 2, "destructiveChangeCount": 0 },
  "changes": [
    { "type": "UNCHANGED", "elementType": "folder", "path": "/crm" },
    { "type": "CREATE",    "elementType": "enum",   "path": "/crm/CUSTOMER_STATUS" },
    { "type": "UNCHANGED", "elementType": "model",  "path": "/crm/Customer" },
    { "type": "CREATE",    "elementType": "field",  "path": "/crm/Customer#status" }
  ],
  "destructiveChanges": [],
  "blueprintHash": "269a…"
}

Every row in changes has a type: CREATE, UPDATE, DELETE or UNCHANGED. destructiveChanges lists in plain text all changes that can destroy something. This exact plan is what the AI client shows you before you approve. A plan lives for 30 minutes.

The change set and its states

cdms_create_change_set takes only a planId, no new blueprint. So what gets approved is exactly what was planned.

stateDiagram-v2
    [*] --> PENDING_APPROVAL: cdms_create_change_set
    PENDING_APPROVAL --> APPROVED: cdms_approve_change_set
    APPROVED --> APPLIED: cdms_apply_change_set, success
    APPROVED --> FAILED: cdms_apply_change_set, error
    APPLIED --> ROLLED_BACK: cdms_rollback_change_set
    FAILED --> [*]
    ROLLED_BACK --> [*]
    APPLIED --> [*]

FAILED and ROLLED_BACK are final states. A change set is never tried a second time. There is no tool to discard one: a change set that you do not approve stays in PENDING_APPROVAL and is never applied.

Approving destructive changes

If the plan lists entries under destructiveChanges, a plain “yes” is not enough:

The AI client shows you the destructive changes one by one and asks about them separately. Only if you confirm exactly that part does it send confirmDestructive: true. Your administrator grants the role; which role it is, the operator of the hub decides. On apply the server checks the role once more. If it has been taken from you in the meantime, nothing is written.

A change set without destructive changes needs neither the role nor the confirmation.

Apply exactly once

When the base has changed in the meantime

Between planning and applying, someone else may have changed the model in the hub. That is why the server reads the schema again before writing:

Undo

cdms_rollback_change_set only works from APPLIED. The rollback undoes, in reverse order, what the change set created or changed. Elements that were only reused (REUSED) stay untouched. The rollback also runs in one transaction, and as with apply, only one runs on a CDMS at a time. It does not need the role for destructive changes: it only takes back what the same change set did.

A change set that deleted a model (DELETE_MODEL) or an enum (DELETE_ENUM) cannot be undone. In that case the server refuses the rollback right away.

The Operation Context: one target, half an hour

The operationId is not a key you can pass on. If someone else knows it, for example from a shared chat history, they cannot approve, apply or undo anything with it: for them, this context does not exist.

The context is valid for 30 minutes from when it is created. Approve, apply and undo need it. So the whole chain from opening to applying must run within this time. When the time is up, you open a new bracket and plan again.

When opening, the server accepts only the UUID of the CDMS. The reading tools also accept the exact module name. Several matches result in CDMS_TARGET_AMBIGUOUS. There is no fuzzy search.

Connecting the AI client

Your access

You get the access data from us when you register or sign the contract:

There is no client secret. Your access is a public OAuth client secured with PKCE: for every login the AI client creates a one-time key that only it knows. A tool on your machine could not keep a secret secret anyway.

What you may see and change is decided by your user account, not by the access. A CDMS you have no rights on does not show up in cdms_list_targets.

Claude Code

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

• --transport http goes before the name and the URL. Without it, Claude Code creates a local stdio server.
• --client-id and --callback-port are required. Without them Claude Code tries to register itself as a client, and the hub rejects that.
• No --client-secret, see above.
• With --scope project the entry goes into the project’s .mcp.json and applies to the whole team; with --scope user it applies to all your projects.

Then you log in inside a Claude Code session:

In the same /mcp menu you see the server’s tools and can log out again, for example when you switch users or your permissions have changed. You can also manage the entry from the command line:

claude mcp list                  # all servers with connection status
claude mcp get codamai-cdms      # details for one server
claude mcp remove codamai-cdms   # remove a server

Instead of claude mcp add you can also write the server directly into the project’s .mcp.json:

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

Do not add an Authorization header. The client gets the token itself through the login, and a fixed header would be a committed access key.

Fewer prompts, but not for writing

Claude Code asks before every tool call. You can allow the reading tools permanently in .claude/settings.json. The names follow the scheme mcp__<servername>__<toolname>:

{
  "permissions": {
    "allow": [
      "mcp__codamai-cdms__cdms_list_targets",
      "mcp__codamai-cdms__cdms_get_target",
      "mcp__codamai-cdms__cdms_get_capabilities",
      "mcp__codamai-cdms__cdms_get_structure",
      "mcp__codamai-cdms__cdms_get_schema"
    ]
  }
}

cdms_approve_change_set, cdms_apply_change_set and cdms_rollback_change_set never go into this list. The prompt before these calls is your approval.

Other AI clients

Permissions

Everything the MCP server reads and writes goes through the same permission checks as the REST API. A CDMS you may not see does not exist for you: the answer is CDMS_TARGET_NOT_FOUND, see Invisible means 404.

And then?

Applying only changes the models in the hub. Your application only notices it at the next build:

How the build fetches the metadata is described in Code generation in the build.

Pitfalls