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, link
    K->>B: shows the plan and the link
    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",
      "messageKey": "model-reused", "params": ["/crm/Customer", "9b1…"],
      "message": "The model '/crm/Customer' already exists (9b1…) and is reused; …" }
  ],
  "models": [ { "ref": "model.customer", "existingId": "9b1…" } ], …
}

Every finding names its element and says in message, in English, what is wrong. That is what the AI client reads. messageKey and params are the same finding as a key, from which the change set page in the hub shows the text in your language. The warnings, the destructive changes and the detail of every planned change in the plan have the same shape.

You should know five 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.

Change sets in the hub

Every change set has its own page in the hub. There you can look at the plan calmly, instead of only reading it in the chat. And you can approve and apply it there.

The pages

There are two ways to get there:

• Through the link. cdms_create_change_set answers with a link to the page of the new change set. The AI client passes it on to you.
• Through the module. On the module’s page, the Change Sets button opens the list.

The detail page groups the plan in the order it is applied in: folders, enumerations, abstract models, data models, fields, relations, access filters, migrations. Each change carries its type: Neu (CREATE), Ergänzt (UPDATE), Entfernt (DELETE) or Unverändert (UNCHANGED).

The trail names every step with time and person, and for approving and applying also the way: per MCP (through MCP) or im Frontend (in the frontend). If applying failed, the cause is shown with it. People appear with their ID from the token.

Everyone who may see the CDMS sees the list. A CDMS you may not see does not exist here either, see Invisible means 404.

Approving and applying in the hub

You can mix the ways: the AI client creates the change set, you approve it in the hub, and the AI client applies it. Or the other way round.

If the hub refuses, the page says in words why, for example:

Undoing works only through the AI client with cdms_rollback_change_set.

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.

The server keeps no session with the client. Every call stands on its own; the hub holds the context, the plan and the change set. If a connection drops, the client simply repeats the call, and the operationId stays valid. An interrupted apply is repeated with the same idempotencyKey: if it already ran, the client gets the result instead of a second write.

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