> 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. # Connect Design MCP > Add the Cessy Design MCP server to Claude, Codex, ChatGPT, or another compatible MCP client so builders and agents can inspect and change app design safely. Connecting the Design MCP server is a central onboarding step for Cessy builders. It lets Claude, Codex, ChatGPT, and compatible MCP clients work against the real app model instead of detached notes. ## Find the connection values Open the app in the Designer view and go to **Overview**. The **MCP Connections** area contains the app-scoped Design MCP URLs and credentials for the current tenant and app. Choose the URL that matches the work: | Endpoint | Use it when | | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | `/api/design-mcp-readonly?tenantId=&appId=` | The agent should inspect, review, explain, or draft without changing the model. | | `/api/design-mcp?tenantId=&appId=` | The agent is trusted to create workspaces, edit artifacts, validate, preview pages, or promote changesets. | | `/api/design-mcp` | Tenant-wide API-key workflows and trusted automation. | | `/api/design-mcp-vnext?tenantId=&appId=` | Alpha five-tool Workspace, Evidence, Candidate, and canonical Artifact authoring. | Default to read-only for discovery and review. Move to the full endpoint only when you intentionally want the client to mutate design state. Always use the exact Remote MCP URL shown in **MCP Connections**. Deployments may expose partner-owned hostnames for browser surfaces, but MCP Connections, OAuth discovery, and authorization stay on the canonical Cessy hostname. Browser-only partner aliases intentionally return `404` for MCP and OAuth server routes. ## Authentication choices | Method | Best for | Notes | | --------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | OAuth discovery | Human builders in Claude, Codex, or ChatGPT | Paste the app-scoped Remote MCP URL. Cessy exposes the OAuth metadata, client defaults, and consent flow from that URL. | | API key | Trusted service automation | Send `Authorization: Bearer ` or configure a bearer token environment variable. | For normal builder onboarding, do not configure client IDs, client secrets, authorization URLs, token URLs, OAuth resource URLs, or scopes manually. Use the Remote MCP URL from **MCP Connections** and let the client discover the OAuth defaults. ## Codex setup Codex supports Streamable HTTP MCP servers in `~/.codex/config.toml` and through the `codex mcp` CLI. The CLI and IDE extension share this configuration. Read-only setup: ```bash codex mcp add cessy_design --url "https://your-instance.com/api/design-mcp-readonly?tenantId=&appId=" ``` Full design setup: ```bash codex mcp add cessy_design_full --url "https://your-instance.com/api/design-mcp?tenantId=&appId=" ``` Start browser consent for the configured server: ```bash codex mcp login cessy_design ``` Use `cessy_design_full` instead when you added the full-design server. Codex reads protected-resource metadata from the exact Remote MCP URL or its RFC 9728 path-derived discovery URL, then continues through Cessy's authorization-server discovery. In Codex, run `/mcp` to confirm that the server is connected after consent. After consent, Codex refreshes the one-hour access token with the stored, rotating refresh token. Normal expiry does not require deleting or reinstalling the MCP server. Shared hosts need a Codex build that coordinates both expiry and HTTP-401 refresh before retrying requests. As verified on September 6, 2026, stable 0.153.4 still lacks the HTTP-401 path, even when its coordination flag is enabled. The tested prerelease 0.154.0-alpha.3 includes the [upstream repair](https://github.com/openai/codex/commit/88912c04cd1180becf77f7a74e3b10351f0779bb) when `features.mcp_oauth_refresh_coordination = true`. All processes sharing credentials must restart onto a qualified build; updating the installed files alone leaves running processes on the old implementation. Shared processes must also use the same credential storage backend. On managed headless Codex hosts, set the top-level `mcp_oauth_credentials_store = "file"` and keep the same private `CODEX_HOME` across processes. Automatic store selection can choose a keyring in one session and a file in another; refresh coordination alone does not reconcile those stores. Establish the current authorization before switching an existing installation, and reload existing MCP connections or restart checkpointed clients. Do not copy an older fallback token into the selected store. A successful isolated refresh test does not prove that running host clients have adopted the configuration. Cessy provides a one-minute recovery window for a rotation response lost before persistence. It cannot recover a grant already revoked by a stale client. After correcting the client, verify that the Remote MCP URL is unchanged and run `codex mcp login ` once for an affected, already-revoked connection. API-key setup for automation: ```bash export CESSY_DESIGN_API_KEY="" codex mcp add cessy_design_ci --url "https://your-instance.com/api/design-mcp-readonly?tenantId=" --bearer-token-env-var CESSY_DESIGN_API_KEY ``` For read-only verification automation, create a **Design Read-only** key with **App Access** set to **Current app only**, then point the automation at the tenant-scoped read-only endpoint: ```text https://your-instance.com/api/design-mcp-readonly?tenantId= ``` Pass the target `appId` in tool inputs such as page preview or route telemetry. The key's app restriction limits access to the selected app while keeping the automation profile reusable for read-only verification tools that require an `appId` parameter. Use API keys only for trusted automation. Human builder sessions should use the app-scoped Remote MCP URL and OAuth discovery. Do not paste raw keys into issues, PRs, logs, or screenshots. ## Claude connector setup Open Claude's connector settings: * **Settings** -> **Connectors** -> **Add custom connector** * Direct link: [Add custom connector](https://claude.ai/new?modal=add-custom-connector#settings/customize-connectors) Then enter: * Name: any label, for example `Cessy Design` * Remote MCP URL: the read-only or full app-scoped Design MCP URL from **Designer** -> **Overview** -> **MCP Connections** Claude discovers the Cessy OAuth metadata from the Remote MCP URL. Use the read-only URL for review and discovery. Use the full `/api/design-mcp` endpoint only for trusted model-changing sessions. ## ChatGPT connector setup Use the values copied from **Designer** -> **Overview** -> **MCP Connections**: * Remote MCP URL: the read-only or full app-scoped Design MCP URL Compatible clients can discover the protected resource metadata, authorization server metadata, dynamic client registration, and consent flow from that URL. ## First agent prompt After connecting, ask the agent to inspect before changing: ```text Use the Cessy Design MCP server. First call get_app, get_domain_model, list_errors, and get_reference for the relevant topics. Summarize the model, the open validation issues, and the safest workspace plan before making edits. ``` If the agent cannot see the server, check the Remote MCP URL, tenant/app selection, connector consent, and whether the MCP client has been restarted after configuration.