> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.cessy.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cessy.ai/_mcp/server. # Design MCP > Reference the Cessy Design MCP endpoints, OAuth scopes, tool families, and safe client usage for Claude, Codex, ChatGPT, and automation. 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 | Endpoint | Authority | | -------------------------------------------------------------- | ------------------------------------------------------------------------------- | | `/api/design-mcp-readonly?tenantId=&appId=` | App-scoped read-only inspection and reference access. | | `/api/design-mcp?tenantId=&appId=` | App-scoped full design access for trusted builder sessions. | | `/api/design-mcp` | Tenant-wide API-key workflows and trusted automation. | | `/api/design-mcp-vnext?tenantId=&appId=` | Allowlisted vNext Alpha: five-tool Workspace, Evidence, and Candidate contract. | 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. | Method | Use | | ------- | -------------------------------------------------------------------- | | OAuth | Human builders in Claude, Codex, ChatGPT, or compatible MCP clients. | | API key | Trusted service automation. | 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: | Method | Path | | -------- | ------------------------------------------------------------------------------------------------------ | | `GET` | `/api/apps/{appId}/config` | | `GET` | `/api/apps/{appId}/endpoints` | | `GET` | `/api/apps/{appId}/agents` | | `GET` | `/api/apps/{appId}/agents/{agentName}/docs` | | `GET` | `/api/apps/{appId}/agents/{agentName}/docs/{key}` | | `PUT` | `/api/apps/{appId}/agents/{agentName}/docs/{key}` | | `DELETE` | `/api/apps/{appId}/agents/{agentName}/docs/{key}` | | `GET` | `/api/apps/{appId}/projections/{projectionName}?workspaceId={workspaceId}&purpose=design` | | `GET` | `/api/apps/{appId}/projections/{projectionName}/{documentId}?workspaceId={workspaceId}&purpose=design` | ## 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: "" }` 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: ```jexl $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`: ```json { "$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: ```json { "$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: ```json { "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.