Reference

MCP Reference

Cessy exposes different MCP servers for different jobs. Choose the narrowest server that matches the task.

Design MCP

Design MCP is for builder work:

  • inspect apps and DomainConfigs
  • read reference knowledge
  • create workspaces
  • edit model artifacts
  • validate changesets
  • preview pages
  • inspect errors
  • promote approved changes

Endpoints:

/api/design-mcp-readonly?tenantId=<tenant-id>&appId=<app-id>
/api/design-mcp?tenantId=<tenant-id>&appId=<app-id>
/api/design-mcp

Use read-only for onboarding, review, and discovery. Use full Design MCP only for trusted model-changing sessions.

Runtime MCP

Runtime MCP is for published app operation:

  • command tools
  • projection tools
  • event import and projection rebuild tools
  • channel tools
  • user and DM tools
  • page refresh tools

Tool names and schemas come from the published DomainConfig.

Endpoint:

/api/mcp/<tenant-id>/<app-id>

Runtime MCP requires bearer authentication with the runtime scope, or an app-scoped agent service token. For workspace-selected runtime calls, use workspaceId=<workspace-id> or X-CES-Workspace-ID; the older env query parameter is not supported.

Optional notebook-style MCP

Some deployments may expose notebook-style private note tools for agents. These are not part of the primary builder onboarding path and should not store business facts.

Client support

Codex supports Streamable HTTP MCP servers through codex mcp and ~/.codex/config.toml. Claude and ChatGPT can connect through custom connector flows by using the app-scoped Remote MCP URL.

See Connect Design MCP.

Tool design rule

MCP tools should expose intentional workflows, not raw database access. A tool should make authority, target app, target environment, and side effects clear.