Connect Design MCP

Connecting the Design MCP server is a central onboarding step for Cessy builders. It lets Claude, Codex, ChatGPT, and the ces CLI 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.

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

Codex discovers the Cessy OAuth metadata from the Remote MCP URL. In Codex, run /mcp to confirm that the server is connected and complete the browser consent flow if Codex asks for authorization.

API-key setup for automation:

$
export CESSY_DESIGN_API_KEY="dsk_..."
$
codex mcp add cessy_design_ci --url "https://your-instance.com/api/design-mcp?tenantId=<tenant-id>" --bearer-token-env-var CESSY_DESIGN_API_KEY

Use API keys only for trusted automation. Human builder sessions should use the app-scoped Remote MCP URL and OAuth discovery.

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.

ces CLI setup

Use ces when you want a fast terminal interface to the Design MCP tools:

$
ces setup --endpoint "https://your-instance.com/api/design-mcp" --token "dsk_..." --profile my-app
$
ces config show
$
ces get_domain_model --appId <app-id>

ces is useful for scripted inspection, migrations, and quick debugging from any terminal or agent.

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.