Connect Design MCP

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:

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

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:

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

Full design setup:

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

Start browser consent for the configured server:

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 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 <server-name> once for an affected, already-revoked connection.

API-key setup for automation:

export CESSY_DESIGN_API_KEY="<design-read-only-key>"
codex mcp add cessy_design_ci --url "https://your-instance.com/api/design-mcp-readonly?tenantId=<tenant-id>" --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:

https://your-instance.com/api/design-mcp-readonly?tenantId=<tenant-id>

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

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:

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.