Expose Integrations | Cessy Builder Docs

Choose the integration surface based on the caller and the direction of the workflow.

Need	Use
External system executes commands or reads projections	REST
External partner builds a user-facing agent chat	REST through a BFF
Custom UI needs flexible reads and command mutations	GraphQL or REST
Runtime agent operates the app	Runtime MCP
External system pushes events into Cessy	Webhooks
External consumer needs Cessy events	Subscriptions
Policy needs to call an external service	Adapter
Frontend needs orchestration or third-party APIs	BFF

REST first for system contracts

REST is the default public system contract because each published app exposes generated OpenAPI. Use the generated contract to discover exact endpoint names, schemas, and response envelopes.

Runtime REST also exposes a safe app agent catalog and app-scoped channel endpoints for user-delegated chat. A partner BFF can list agent IDs through normal Runtime auth, then use delegated user OAuth to create a fresh DM, list channels, exchange messages, or update read state for the authenticated user.

Runtime MCP first for agents

Agents should use Runtime MCP for published app operation. Runtime MCP names tools after the app’s commands and projections, and also exposes channel and user collaboration tools.

Do not give runtime agents Design MCP access unless they are explicitly meant to change the app model.

Webhooks and subscriptions

Use webhooks for inbound external events. Use subscriptions for outbound Cessy events. Keep both tied to modeled commands and events so behavior remains inspectable.

Adapters

Adapters are infrastructure dependencies used by policies and controlled app logic. They are not the normal public API for external consumers. If an external client needs a contract, expose a command, projection, webhook, subscription, or BFF endpoint instead.

BFF

Use a Backend-for-Frontend when a custom page needs orchestration that does not belong in the event model, such as combining Cessy projections with third-party data for display.

For partner chat, the BFF should authenticate the end user, call Runtime REST channel endpoints with user-delegated authority, and return UI-shaped thread or message payloads. Keep business mutations on generated commands and keep authoritative channel history in Cessy.

See BFF Pattern.