> 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.

# Quickstart

> Connect an AI builder, inspect an app model, publish safely, and smoke-test the generated runtime contract.

This quickstart assumes you already have a Cessy tenant and an app. It takes you through the shortest useful builder loop: connect the Design MCP, inspect the model, make a scoped change, publish, and verify the runtime surface.

## 1. Copy the app-scoped Design MCP URL

Open the app in the Designer view and go to **Overview**. In **MCP Connections**, copy the read-only Remote MCP URL first:

```text
https://your-instance.com/api/design-mcp-readonly?tenantId=<tenant-id>&appId=<app-id>
```

Use the full Design MCP URL only when the agent is allowed to change the model:

```text
https://your-instance.com/api/design-mcp?tenantId=<tenant-id>&appId=<app-id>
```

## 2. Connect Claude or Codex

Use [Connect Design MCP](/start/connect-design-mcp) for the complete setup.

For Claude, add a custom connector in **Settings** -> **Connectors** and paste the Remote MCP URL.

For Codex:

```bash
codex mcp add cessy_design --url "https://your-instance.com/api/design-mcp-readonly?tenantId=<tenant-id>&appId=<app-id>"
```

Claude and Codex discover the Cessy OAuth defaults from the Remote MCP URL. Do not configure OAuth client IDs, secrets, resource URLs, or scopes manually.

## 3. Start with a concrete prompt

Paste this into Claude or Codex after the connector is available:

```text
Use the Cessy Design MCP connector for this app. Start read-only:
call get_app, get_domain_model, list_errors, and get_reference for
DomainConfig, commands, events, projections, policies, permissions, and
workspaces. Then summarize:

1. what this app currently does,
2. the main deciders, commands, events, projections, and policies,
3. any validation errors or modeling risks,
4. the smallest safe workspace plan for the change I ask for next.

Do not mutate the model until I explicitly ask you to create or update a
workspace.
```

This prompt makes the agent prove that it can see the real model before it suggests edits.

## 4. Make a scoped design change

Use a workspace for any meaningful change:

```text
create_workspace
upsert_event
upsert_command
upsert_projection
get_workspace_status
preview_rebase_workspace
rebase_workspace
create_changeset
validate_changeset
promote_changeset
```

Prefer one coherent business change per workspace. Do not mix unrelated feature work, permission changes, and frontend page work in the same changeset unless they must ship together.
Only run `rebase_workspace` after a clean preview, and pass `expectedEnvironmentReleaseId` when promoting.

## 5. Verify the published runtime contract

After publishing, fetch the generated OpenAPI contract:

```bash
curl https://your-instance.com/api/rest/<tenant-id>/<app-id>/openapi
```

Then smoke-test one command and one projection. The exact endpoint names come from the generated OpenAPI contract and the published DomainConfig.

## 6. Hand off the result

A good handoff includes:

* the app id, tenant id, workspace id, changeset id, and target environment
* the commands, events, projections, policies, permissions, adapters, or pages changed
* the validation result and remaining risks
* one runtime command/projection smoke test
* the Design MCP server name used by the reviewing agent