Design MCP

Design MCP is the builder automation surface. It gives MCP clients structured access to app design, Cessy reference knowledge, validation, workspace changesets, page preview, and selected operations.

Endpoints

Use the app-scoped endpoint whenever possible. It gives the MCP client the current app context and avoids tenant-wide ambiguity.

vNext Alpha and existing apps

The vNext Alpha can begin from an existing coherent published app even when only part of its model is supported by the current Artifact registry. Cessy captures the exact Production base first and classifies each item as writable, sealed, platform-bound, or excluded. Unsupported historical content does not force the agent to copy or remodel the app and does not block unrelated edits.

design__workspace__begin returns compact compatibility counts and a pinned base-compatibility Resource. Read that paginated Resource when the agent needs the per-Artifact boundary. Sealed and platform-bound items remain part of every Candidate and Release but cannot be patched, removed, shadowed, or overwritten through vNext. Apply returns an actionable Artifact-level diagnostic when a requested operation crosses that boundary.

The compatibility list remains metadata-only. To read one exact sealed item, open its exact-revision Artifact Resource or use Inspect with that ref. The response marks the retained content retained_read_only, includes its reason and safe next action, and intentionally omits a writable Kind contract. Platform-bound and excluded items remain metadata-only; artifact_not_found means the ref is absent from both authored and retained state.

Interactive Workspace evaluation validates initialPageKey before creating a durable Operation or browser session. Ineligible starts return the exact reason, eligible Page keys, and a safe next call. An admitted start builds the affected Page closure plus the explicit initial Page. The initial Page must be healthy; another selected Page with inherited build, route, or access debt is omitted from that Session instead of blocking it. The pageScope receipt lists admitted and unavailable Page keys and counts source-backed Pages outside the task-sized Session. Candidate evaluation remains fail-closed, and a client can start a new Session on the same revision when it needs another Page. The app-scoped workspace-continuations Resource likewise keeps its durable continuation core available when optional proof enrichment is temporarily unavailable, marks the proof partial, and tells the caller to retry the same Resource.

The Alpha keeps five tools: Begin, Inspect, Apply, Evaluate, and Finalize. Finalize creates an immutable Candidate; it does not itself publish to Production. Legacy Workspaces and ChangeSets remain available through the v1 route until the explicit consumer-migration and v1-retirement gates. If a Candidate Release is current, rebase Legacy work onto that exact Release and validate it again before promotion. Both publication paths share one Production base lease and target fence. Raw Legacy hosting writes, per-page Production restore, and arbitrary historical Legacy rollback remain unavailable across Candidate-sourced lineage. The sole cutover exception is an app-admin whole-Release Restore from the current first non-restore vNext Candidate to the exact retained Legacy Release named as its immediate base. It reactivates that snapshot directly, creates no synthetic Candidate Release, and exposes no historical Release selector.

Workspace status reports completed or aborted target fences as terminal with recovery.overdue: false and recovery.disposition: none. Their historical deadline remains available for audit but does not block later authoring or promotion.

Inspect publishes its required/optional selector matrix in the discovered tool schema. The complete artifact-kinds view accepts only an optional workspaceId; do not send cursor or limit. Unlisted selector combinations fail explicitly as non-retryable invalid_tool_input results.

vNext Automation vocabulary

The current pinned Registry models external invocation as model:trigger with only webhook or schedule, and Domain Event reactions as model:policy with only command, code, or agent. Executable Code lives in a same-key policy-code Artifact. Legacy subtype names, scheduler mechanics, hashes, manifests, secrets, provider settings, and runtime authority are platform-owned and never part of normal agent input.

One-time future dispatch is delivery on a Command Policy; recurring time is a Schedule Trigger. A pure Automation change receives a task-sized exact-revision runtime-binding check rather than automatically running unrelated scenarios. In the current v10 Registry, Agent Policies reference one bounded Agent Artifact. When an Evaluation scenario fires the Policy, the Workspace records its evaluated intent and context without a provider or Production side effect. Publication binds the Policy to the exact role-aware Agent generation; Production invokes that same bounded kernel from a durable, release-pinned queue and never falls back to Legacy Agent wake. Pinned v8 Workspaces remain replayable but reject new Agent Policy authoring.

Code Policies may declare durableRecovery as command_fanout_v1 or native_batch_v1; Cessy maps that canonical field to the existing runtime behavior and derives dispatch authority from the same-key policy-code Artifact. v10 accepts Policy source up to 300 KiB without placing it into normal agent context: use Inspect with an exact /code line range, then submit anchored replace_text edits in the ordinary atomic Apply transaction. Put related Policy metadata and source edits into that same Apply. Pinned v9 Workspaces keep their original 48 KiB source contract and reject the v10 extensions.

Auth

Design MCP supports bearer API keys and OAuth.

Read-only Design MCP requires design:read or design. Full Design MCP requires design.

Temporary Design REST scripting tokens

Full Design MCP exposes mint_design_rest_token for trusted builders and agents that need to automate documented Design REST calls from a local script. The tool returns a short-lived Authorization: Bearer ... header scoped to the caller’s tenant, principal, Design scope, and optionally one app.

• Default lifetime: 15 minutes.
• Maximum lifetime: 1 hour.
• Tokens are not long-lived API keys.
• Tokens are not runtime credentials and are rejected by Runtime APIs.
• Never write returned tokens into prompts, docs, source files, screenshots, or page bundles.

Supported Design REST endpoints:

Tool families

Design MCP includes tools for:

• reference knowledge
• app and model introspection
• cleanup impact inspection before removing commands, events, projections, or related artifacts
• workspace changesets
• validation
• task runs
• page preview and browser QA
• page design system inspection
• testing
• design resources
• tool discovery
• design changes
• credentials, adapters, environments, permissions, and operational support where enabled

Tool availability can depend on endpoint, auth scope, app context, and server configuration.

Workspace TestRuns

run_test_suite executes a Workspace suite in a fresh, short-lived runtime derived from the exact selected Workspace config. It does not use the source Workspace as mutable runtime state, so failed runs do not poison retries and fixed mustBeNew fixtures can be reused safely.

Policy-only command proof

principalType represents authenticated runtime ingress and accepts user, apiKey, or agent; Policies are not caller principals. Server-owned Policy dispatch records the attested actor { type: "policy", id: "<PolicyName>" } and does not enter through the public command authorization gate. To close a Command to external callers while retaining one internal Policy path, use an exact sentinel rule such as:

$actor.type == 'policy' && $actor.id == 'ComputeAnswerReliability'

Prove the boundary with two independent checks: a Workspace execute_command probe using a valid external synthetic principal must be denied, and a syntheticPolicy step must emit the Command with complete runtime evidence for the Policy actor. syntheticPolicy persists a canonical trigger only in the disposable execution runtime and skips unrelated Projection handlers. A TestSpec command step runs as the trusted TestRun system actor and is not an authorization probe.

Command steps expect success by default. An intended domain rejection can be declared with expectedResult: "failure" and an optional expectedFailure matcher containing code, messageIncludes, or both. Public failure codes are COMMAND_GUARD_REJECTED, COMMAND_VALIDATION_FAILED, and DECISION_SCOPE_NOT_FOUND. A matching rejection is retained as a failed command execution for assertions while the step passes and later assertions continue. Mismatches fail the test expectation; platform failures are never treated as expected domain behavior.

Each assertion has a separate bounded runtime in both Legacy TestRuns and vNext Workspace Evaluation. timeoutMs defaults to 15 seconds and cannot exceed 30 seconds; inside a wait step, the shorter remaining wait budget wins. Projection reads receive that same cancellation deadline. If one does not settle, Cessy records the assertion as errored with errorCode: "TEST_ASSERTION_TIMEOUT" and bounded expected/actual evidence, then finalizes the run instead of waiting for the suite-wide worker timeout. Other platform-side assertion failures use TEST_ASSERTION_EXECUTION_FAILED; neither code represents a domain mismatch.

Ephemeral Policy fixtures

If a Policy fails with zero fixture calls, inspect its retained Policy failure details before changing the fixtures. Infrastructure diagnostics distinguish deployment, execution, and isolated_execution; Docker failures additionally identify a bounded phase, reason, response status, and timeout flag when available. A container_start failure means the handler did not start. These diagnostics contain no daemon output or fixture payloads and do not change reconciliation or promotion requirements.

Legacy run_test_suite and vNext exact-revision Workspace Evaluation support the same two test-only fixture recipes. Put a recipe in an ordinary TestSpec fixture value; no file upload, cassette, credential, or local synchronization step is required.

Use a file recipe when a real custom Code Policy reads a FileRef through ctx.files:

{
  "$testRuntime": "file",
  "filename": "synthetic.pdf",
  "mimeType": "application/pdf",
  "size": 256
}

Cessy generates bounded deterministic bytes inside the short-lived runtime, resolves the fixture to a synthetic FileRef, and zeroizes the bytes after the Policy runtime drains. The bytes are never stored in the TestSpec or evidence.

Use an adapter-response recipe when that Policy calls a protected adapter:

{
  "$testRuntime": "adapter-response",
  "adapter": "lightrag",
  "operation": "documentIngestStaged",
  "ordinal": 1,
  "status": 202,
  "resultMetadata": {
    "status": "accepted",
    "contentHash": "synthetic-sha256"
  }
}

Matching uses only adapter, operation, and the call ordinal within one Policy execution. Request bodies and headers never participate in matching or evidence. Optional resultMetadata accepts bounded, content-free JSON metadata such as statuses, hashes, counts, coverage, timestamps, and attestations; content-, transport-, request/response-, and credential-shaped fields are rejected.

Fixture authority is available only in disposable, networkless TestRuns. A Legacy run must select exactly one block-only Workspace, use no cassette or allowed external host, and explicitly allow each synthetic adapter. vNext runs the selected TestSpec in its equivalent credential-free exact-revision runtime. Production, live or record HTTP, tenant credential resolution, raw adapter calls, undeclared file/adapter access, and external fetch all fail closed.

Both contracts return bounded fixtureEvidence with fixture identities, hashes, sizes, MIME/adapter metadata, read/call counts, Policy actor/execution identities, violation codes, and final zeroization status. They never retain file bytes, worker logs, snippets, queries, credentials, or adapter request and response bodies. TestSpec assertions must still prove the intended Domain events, projections, and final state.

Legacy Workspace TestRuns actively drain only their own short-lived execution Workspace. Cessy does this after mutating steps and on every wait poll, then refreshes event, command, Policy, projection, decider-state, and external-call evidence before assertions run. This also settles multi-hop durable Policy chains while the TestRun fixture authority is active. The source Workspace and Production are never used as the drain target; step evidence contains only bounded claimed/completed/reconciliation/failure counts.

A scheduledPolicy step retains its actual Command execution and correlation IDs and runs as the named Policy actor. After background settlement, canonical scheduled and downstream Policy events count toward event assertions and maxCreatedEvents. A no-event replay does not duplicate retained events, and a successful scheduled Command still fails an assertion for a missing event.

Exact Custom Page session QA

design__page__diagnose supports a revision-pinned mode for authorization and session-isolation evidence. Pass one exact target and omit the legacy workspaceId and deployment selectors:

{
  "appId": "app-id",
  "slug": "orders/order-123",
  "target": {
    "kind": "workspace-revision",
    "workspaceId": "workspace-id",
    "revision": 12,
    "artifactGraphHash": "<64 lowercase hex characters>"
  }
}

Production targets use kind: "production-release", releaseId, and coherenceToken. By default the tool runs distinct platform-generated principals A and B plus missing, expired, revoked, wrong-app, and foreign-tenant. Use sessionScenarios only to request a subset of those named cases.

Exact mode rejects the legacy roles and attributes fields. Principal identity and authorization attributes are platform-owned for this matrix.

The structured response identifies mode: "exact-session-scenarios", the observed target, the stateless session contract, and per-scenario evidence. Denied scenarios have no browser URL, module preflight/load, protected runtime data, or persistent session state. Allowed scenarios receive distinct, short-lived, exact-target Agent Page Session URLs after authorization and module preflight. Target drift, conflicting selectors, and caller-controlled identity, tenant, or environment selection fail closed.

Within an allowed Agent View, same-app Custom Page navigation through useCesNavigation() is continued by the host. Each destination receives a new page-scoped token with the same principal, authorization attributes, exact runtime target, audit id, and original expiry. Reload and browser Back/Forward restore the corresponding page token; cross-app navigation and direct wrong-page cookie replay remain denied.

Large inspection responses

Model inspection tools return inline JSON when the payload is small enough for the MCP response. Large list or export calls, such as projection lists or section exports, may return a compact response instead. The compact response includes artifact counts, names, truncation metadata, and suggested follow-up calls such as a single-artifact lookup.

Safe usage

For onboarding and review, connect read-only first. For mutation work, ask the agent to create or use a focused workspace, validate changes, and summarize impact before promotion.

Before removing or renaming model artifacts, ask the agent to inspect removal impact so live pages, Workspace pages, policies, triggers, seed data, tests, projection data, and replay risk are visible before deletion.

Do not use Design MCP for normal runtime user workflows. Published app operation belongs to Runtime MCP or Runtime APIs.