fix(mcp): reject CREATE VIEW ENTITY instead of leaving it out of sync

A view entity created over MCP showed "View Entity is out of sync with the OQL
Query" in Studio Pro (CE6770). Root cause: a synced view entity needs each
attribute's value to be an OqlViewValue, but PED's Attribute schema exposes no
`value`, a `set` on the nested value is refused ("only primitive or reference
properties"), and the sync (syncViewEntity) is reachable only through the
LLM-backed `oql_generate` tool — which regenerates the query from a natural-
language intent rather than writing the user's OQL verbatim (and is slow/may need
Maia config). PED's deterministic write tools therefore cannot produce a synced
view entity.

Rather than write the OQL + entity and leave a broken, error-flagged entity in
the model, reject up front. CreateViewEntitySourceDocument is the executor's first
view-entity backend call (before the companion entity), so the rejection leaves
nothing half-created. Gated on capabilities.yaml/view_entities (flipped to
available:false with the reason); verified live that it rejects with an actionable
error and creates no source doc or entity.

Removed view entities from 01-mcp-domain-model-examples.mdl (now ~20 statements,
all of which run clean over MCP) and from the MCP docs; the cost-doc tally is
softened to "~60 calls" and no longer pinned to an exact, drifting statement count.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ako

docs-site/src/internals/mcp-backend-cost.md

@@ -16,7 +16,7 @@ and what it means for latency, token usage, and an LLM's context window.
 
 > The numbers below trace the worked example
 > [`mdl-examples/doctype-tests/01-mcp-domain-model-examples.mdl`](https://github.com/mendixlabs/mxcli/blob/main/mdl-examples/doctype-tests/01-mcp-domain-model-examples.mdl)
-> — a 25-statement domain-model script that stays entirely inside the MCP
+> — a ~20-statement domain-model script that stays entirely inside the MCP
 > authoring surface. To see the surface for your connected version, run
 > `mxcli mcp capabilities -p app.mpr --mcp`.
 
@@ -29,17 +29,19 @@ The choreography — not the statement count — drives the cost.
 |---|---|---|
 | `create module` | `ped_create_module` | 1 |
 | `create enumeration` | `ped_create_document` + `ped_check_errors` | 2 |
-| `create entity` (incl. `extends`, non-persistent) | `ped_update_document` (add) + `ped_check_errors` | 2 |
-| `create association` | `ped_update_document` (add) + `ped_check_errors` | 2 |
-| `create view entity` | create source-doc + set `/oql` + entity add + check | 4 |
+| `create entity` (incl. `extends`) | `ped_update_document` (add) + `ped_check_errors` | 2 |
+| … plus each `NOT NULL` / `UNIQUE` rule | `ped_read_document` (locate entity) + `ped_update_document` (add rules) | +2 |
+| `create association` | 2× `ped_read_document` (resolve parent/child entity refs) + `ped_update_document` (add) + `ped_check_errors` | 4 |
 | `alter entity` (add / rename / set documentation) | 2× `ped_read_document` (locate + read live attrs) + `ped_update_document` + `ped_check_errors` | 4 |
 | `show` / `describe` of a **just-modified** module | `ped_read_document` (entities + associations) + an enrichment read for attribute types | 2 |
 | `show enumerations` (and other reads of unchanged docs) | served from the local `.mpr` | 0 |
-| one-time `ped_get_schema` per element type (entity, attribute, association, view source) | fetched once per session, then cached | 4 total |
+| one-time `ped_get_schema` per element type (entity, attribute, association, validation rule) | fetched once per session, then cached | ~4 total |
 | `initialize` handshake | once per connection | 1 |
 
-For the 25-statement example that works out to **≈ 62 tool calls** on the happy
-path: ~47 writes-plus-validation, ~10 read-backs, 4 schema fetches, 1 handshake.
+For a ~20-statement domain-model script like the example, that's **on the order of
+60 tool calls** — overwhelmingly per-write validation and read-backs, not the
+statement count. (Run it with `--mcp-trace` to see the exact tally for your
+script; the precise number shifts as the example evolves.)
 
 > **See it yourself.** Run any script with `--mcp-trace` (or `--mcp-verbose`) to
 > print the actual PED calls each MDL command makes — the runtime view of this
@@ -48,7 +50,7 @@ path: ~47 writes-plus-validation, ~10 read-backs, 4 schema fetches, 1 handshake.
 ### Three things inflate the count
 
 1. **Validation runs after every write.** `ped_check_errors` fires once per write
-   statement, so **~17 of the 62 calls are validation alone**. This keeps the live
+   statement, so **a large share of the calls are validation alone**. This keeps the live
    model provably consistent at each step, but it is not free.
 2. **`ALTER` is read-modify-write.** Because PED cannot change an attribute's type
    in place, mxcli first *reads* the live entity (to tell a rename from a drop+add,
@@ -73,9 +75,9 @@ statements. The practical levers:
 
 - **Batch writes into one script run**, not many small invocations — the
   `initialize` handshake and schema fetches are paid once per connection.
-- **Drop trailing `SHOW`/`DESCRIBE` verification** from production scripts. In the
-  example, the eight read-back lines account for ~10 of the 62 calls; removing them
-  cuts roughly a sixth of the traffic.
+- **Drop trailing `SHOW`/`DESCRIBE` verification** from production scripts. Each
+  read-back of a just-written module costs ~2 calls, so the verification block is an
+  easy chunk to cut when you don't need it.
 - **The file backend has zero round trips.** If Studio Pro doesn't need to be open
   — e.g. CI, bulk generation, or scripted migrations — the file backend applies the
   same script far faster. Reserve `--mcp` for when live, validated, no-reload edits
@@ -90,7 +92,7 @@ hinges on a single question: *who makes the tool calls?*
 
 When an agent runs `mxcli exec script.mdl -p app.mpr --mcp` (via the shell, the
 REPL, or an editor command), the agent emits **one** action — the MDL script — and
-receives **one** summarized result. The ~62 PED tool calls, and their often
+receives **one** summarized result. The ~60 PED tool calls, and their often
 verbose, schema-laden JSON responses, happen *inside the mxcli process*. They never
 enter the model's context window, and they don't each cost a model turn.
 
@@ -104,12 +106,12 @@ That is a few thousand tokens, regardless of how many PED round trips it took.
 ### Agent → Studio Pro MCP directly (expensive)
 
 An agent connected straight to Studio Pro's MCP server has no such amortization. To
-build the same domain model it must issue each of the ~62 calls **as its own tool
+build the same domain model it must issue each of the ~60 calls **as its own tool
 call**:
 
 - every request *and* every response (schemas, validation output, read-backs) is
   written into the context window, and
-- each call is a separate model turn — so the model "thinks" ~62 times instead of
+- each call is a separate model turn — so the model "thinks" ~60 times instead of
   once, multiplying both latency and per-turn token cost.
 
 The same work that is one declarative script for the mxcli path becomes dozens of
@@ -120,14 +122,14 @@ imperative, stateful tool calls whose intermediate results accumulate in context
 ```
                      calls in LLM context   model turns   tokens in context
 Agent → mxcli (--mcp)          0                  1              low (script + summary)
-Agent → Studio Pro MCP        ~62               ~62             high (every request + result)
+Agent → Studio Pro MCP        ~60               ~60             high (every request + result)
 ```
 
 mxcli's MCP backend is, in effect, a **compression layer over the PED tool surface**:
 the LLM works in compact, reviewable MDL while mxcli absorbs the chatty,
 validation-heavy, read-modify-write round trips on the model's behalf. For bulk
 authoring this is the difference between one cheap turn and dozens of expensive
-ones — and it is why, even though a script "costs" ~62 tool calls, running it
+ones — and it is why, even though a script "costs" ~60 tool calls, running it
 *through mxcli* keeps that cost out of the model's context.
 
 ## See also

docs-site/src/tools/mcp-connect.md

@@ -82,8 +82,8 @@ mxcli exec mdl-examples/doctype-tests/01-mcp-domain-model-examples.mdl \
   --mcp-dial host.docker.internal:7784
 ```
 
-The new entities, enumerations, associations, and view entities appear in Studio
-Pro as the script runs — no save or reload required.
+The new entities, enumerations, and associations appear in Studio Pro as the
+script runs — no save or reload required.
 
 The same `--mcp` / `--mcp-dial` flags work for a single statement (`-c "…"`) and in
 the interactive REPL (`mxcli -p app.mpr --mcp …` with no subcommand) — in every
@@ -151,12 +151,12 @@ mxcli exec changes.mdl -p app.mpr --mcp http://localhost/mcp --mcp-dial 127.0.0.
 
 ## What works over MCP
 
-The MCP backend authors a subset of MDL — entities (incl. `extends` and
-`ALTER`), associations, enumerations, constants, microflows, pages (`CREATE` +
-`ALTER`), workflows, and view entities. Some document types (nanoflows, Java
-actions, business-event services), security, navigation, and `MOVE` are **not**
-authorable over MCP today. Reads of any document type always work (they come from
-the local `.mpr`).
+The MCP backend authors a subset of MDL — entities (incl. `extends`, `ALTER`, and
+NOT NULL / UNIQUE), associations, enumerations, constants, microflows, pages
+(`CREATE` + `ALTER`), and workflows. Some document types (nanoflows, Java actions,
+business-event services, **view entities**), security, navigation, and `MOVE` are
+**not** authorable over MCP today. Reads of any document type always work (they
+come from the local `.mpr`).
 
 `mxcli mcp capabilities -p app.mpr --mcp … --mcp-dial …` reports exactly what your
 connected version supports. See also

mdl-examples/doctype-tests/01-mcp-domain-model-examples.mdl

@@ -18,10 +18,12 @@
 --   - create persistent entity, with NOT NULL / UNIQUE validation rules (+ error messages)
 --   - create entity ... extends ...                    (generalization)
 --   - create association ... (reference, referenceset) WITHIN a single module
---   - create view entity ... as <OQL>
 --   - alter entity ... add / rename attribute, set documentation
 --
 -- OUT of scope — NOT used here, with reasons (capabilities.yaml):
+--   - view entities (OQL)               PED syncs view-entity attributes to the OQL only via
+--                                        the LLM-backed oql_generate tool; its deterministic
+--                                        tools leave the entity out of sync (CE6770)
 --   - default values                    the entity slice doesn't author attribute defaults yet
 --                                        (PED's attribute object carries name/type only)
 --   - non-persistent entities           PED's entity constructor exposes no persistable flag
@@ -206,51 +208,8 @@ create persistent entity McpDm.Truck extends McpDm.Vehicle (
 );
 /
 
--- @version: 10.18+
 -- ############################################################################
--- PART 5: VIEW ENTITIES (OQL) — requires Mendix 10.18+
--- ############################################################################
-
-/**
- * Active products only.
- */
-@position(1100, 100)
-create view entity McpDm.ActiveProducts (
-  Name: string(200),
-  Code: string(50),
-  Price: decimal,
-  Stock: integer
-) as
-  select
-    p.Name as Name,
-    p.Code as Code,
-    p.Price as Price,
-    p.Stock as Stock
-  from McpDm.Product as p
-  where p.IsActive = true;
-/
-
-/**
- * Order totals per customer, joined via the association.
- */
-@position(1100, 300)
-create view entity McpDm.CustomerOrderTotals (
-  CustomerEmail: string(200),
-  OrderCount: integer,
-  TotalSpent: decimal
-) as
-  select
-    c.Email as CustomerEmail,
-    count(o.OrderNumber) as OrderCount,
-    sum(o.TotalAmount) as TotalSpent
-  from McpDm.SalesOrder as o
-  inner join o/McpDm.SalesOrder_Customer/McpDm.Customer as c
-  GROUP by c.Email;
-/
-
--- @version: any
--- ############################################################################
--- PART 6: ALTER ENTITY (add / rename attribute, documentation)
+-- PART 5: ALTER ENTITY (add / rename attribute, documentation)
 -- ############################################################################
 --
 -- Only the ALTER actions the MCP backend supports are used here: add attribute
@@ -274,12 +233,11 @@ alter entity McpDm.Customer
   set comment 'Customer master, MCP-authored.';
 
 -- ############################################################################
--- PART 7: VERIFY (reads always work over MCP — they delegate to the local .mpr)
+-- PART 6: VERIFY (reads always work over MCP — they delegate to the local .mpr)
 -- ############################################################################
 
 show entities in McpDm;
 show enumerations in McpDm;
 describe entity McpDm.Customer;
 describe entity McpDm.SalesOrder;
 describe entity McpDm.Truck;
-describe entity McpDm.CustomerOrderTotals;

mdl/backend/mcp/capabilities.go

@@ -24,6 +24,7 @@ const (
 	capNanoflowCreate      = "nanoflow_create"
 	capJavaActionCreate    = "javaaction_create"
 	capBusinessEventCreate = "businessevent_create"
+	capViewEntityCreate    = "view_entities"
 )
 
 // Capability is one authorable/blocked feature for a given server version.

mdl/backend/mcp/capabilities.yaml

@@ -51,9 +51,9 @@ features:
     available: true
     note: "CREATE / CREATE OR REPLACE / DROP / ALTER (full, any nesting depth)"
   - key: view_entities
-    feature: "View entities"
-    available: true
-    note: "CREATE"
+    feature: "View entities — CREATE"
+    available: false
+    note: "PED syncs a view entity's attributes to its OQL only via the LLM-backed oql_generate tool; its deterministic write tools leave attributes as StoredValue, out of sync with the query (CE6770). mxcli writes user OQL verbatim and does not invoke the generator, so it does not author view entities over MCP"
   - key: documents_into_folders
     feature: "Documents into folders"
     available: true

mdl/backend/mcp/viewentity.go

@@ -6,33 +6,25 @@ import (
 	"github.com/mendixlabs/mxcli/model"
 )
 
-const viewEntitySourceDocType = "DomainModels$ViewEntitySourceDocument"
-
-// CreateViewEntitySourceDocument creates the OQL source document that backs a
-// view entity, then sets its query. The companion view entity (created
-// afterwards by the executor via CreateEntity) references this document by
-// qualified name through its OqlViewEntitySource. By convention the source
-// document's name equals the view entity's name.
+// CreateViewEntitySourceDocument is gated on the capability model
+// (capabilities.yaml / view_entities) and rejects. A view entity is only valid
+// when its attributes are synced to the OQL's SELECT columns (each attribute's
+// value becomes an OqlViewValue). PED has no deterministic way to do that — its
+// Attribute schema exposes no `value`, a `set` on the nested value is refused,
+// and the sync (syncViewEntity) is reachable only through the LLM-backed
+// oql_generate tool, which regenerates the query rather than writing the user's
+// OQL verbatim. Writing the OQL with PED's plain tools leaves the entity out of
+// sync with its query (CE6770). So mxcli refuses up front instead of leaving a
+// broken entity in the model.
 //
-// Choreography (verified live): ped_create_document {name} -> ped_update_document
-// set /oql. No ped_check_errors here: the source document is "unlinked" until
-// the entity referencing it exists, so validation runs after the entity write.
+// This is the executor's first view-entity backend call (before the companion
+// entity is created), so rejecting here leaves nothing half-created.
 func (b *Backend) CreateViewEntitySourceDocument(moduleID model.ID, moduleName, docName, oqlQuery, documentation string) (model.ID, error) {
-	if err := b.ensureSchema(viewEntitySourceDocType); err != nil {
-		return "", err
-	}
-	if err := b.pedCreateDocument(moduleName, viewEntitySourceDocType, docName, map[string]any{"name": docName}, ""); err != nil {
-		return "", err
-	}
 	qn := moduleName + "." + docName
-	ops := []pedOpEntry{{Path: "/oql", Operation: pedOperation{Type: "set", Value: oqlQuery}}}
-	if documentation != "" {
-		ops = append(ops, pedOpEntry{Path: "/documentation", Operation: pedOperation{Type: "set", Value: documentation}})
-	}
-	if err := b.pedUpdateDoc(viewEntitySourceDocType, qn, ops...); err != nil {
-		return "", err
+	if !b.canAuthor(capViewEntityCreate) {
+		return "", b.notAuthorable("view entity", qn, capViewEntityCreate)
 	}
-	return model.ID("mcp~vesrc~" + qn), nil
+	return "", errCreatePathUnbuilt("view entity", qn)
 }
 
 // DeleteViewEntitySourceDocumentByName is a no-op: the PED server exposes no

mdl/backend/mcp/viewentity_test.go

@@ -53,42 +53,19 @@ func TestBuildEntityValue_ViewEntity_RequiresSourceRef(t *testing.T) {
 	}
 }
 
-func TestCreateViewEntitySourceDocument_Choreography(t *testing.T) {
-	f := newFakePED(t, func(string, map[string]any) (string, bool) { return "SUCCESS", false })
-	b := &Backend{
-		client:        f.connectClient(t),
-		dirty:         map[string]bool{},
-		schemaFetched: map[string]bool{},
+// View entities are not authorable over MCP: PED can only sync a view entity's
+// attributes to its OQL via the LLM-backed oql_generate tool, so the deterministic
+// path leaves the entity out of sync (CE6770). CreateViewEntitySourceDocument is
+// the executor's first view-entity backend call and must reject before any PED
+// write, leaving nothing half-created.
+func TestCreateViewEntitySourceDocument_Rejected(t *testing.T) {
+	b := &Backend{} // no client/server needed — it rejects before any PED call
+	_, err := b.CreateViewEntitySourceDocument("m1", "MyFirstModule", "LocView", "select 1 as X", "")
+	if err == nil {
+		t.Fatal("expected view-entity creation to be rejected over MCP")
 	}
-
-	id, err := b.CreateViewEntitySourceDocument("m1", "MyFirstModule", "LocView", "select 1 as X", "")
-	if err != nil {
-		t.Fatalf("CreateViewEntitySourceDocument: %v", err)
-	}
-	if id == "" {
-		t.Error("expected a non-empty source document id")
-	}
-
-	create, ok := f.callByName("ped_create_document")
-	if !ok {
-		t.Fatal("ped_create_document not called")
-	}
-	craw, _ := json.Marshal(create.Args["documents"])
-	if !strings.Contains(string(craw), `"documentType":"DomainModels$ViewEntitySourceDocument"`) ||
-		!strings.Contains(string(craw), `"documentName":"LocView"`) {
-		t.Errorf("create-document args wrong: %s", craw)
-	}
-
-	update, ok := f.callByName("ped_update_document")
-	if !ok {
-		t.Fatal("ped_update_document (set /oql) not called")
-	}
-	uraw, _ := json.Marshal(update.Args["operations"])
-	if !strings.Contains(string(uraw), `"path":"/oql"`) || !strings.Contains(string(uraw), `"select 1 as X"`) {
-		t.Errorf("set /oql op wrong: %s", uraw)
-	}
-	if update.Args["documentName"] != "MyFirstModule.LocView" {
-		t.Errorf("oql set targeted wrong doc: %v", update.Args["documentName"])
+	if !strings.Contains(err.Error(), "not authorable") {
+		t.Errorf("error should explain the view entity is not authorable: %v", err)
 	}
 }