> 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. # Runtime MCP > Use generated Runtime MCP tools for published app commands, projection and file reads, event operations, channels, users, DMs, and page refresh. Runtime MCP exposes a published app as agent tools. Tool names and schemas come from the app's published DomainConfig, with canonical `runtime_*` names and discovery contracts for progressive inspection. ## Connect Runtime MCP is available per tenant and app: ```text /api/mcp// ``` Calls require a bearer token with the `runtime` scope, or an app-scoped agent service token issued by the platform. OAuth-capable MCP clients can use the exact app URL directly: a public non-SSE `GET` returns its RFC 9728 protected-resource metadata, while unauthenticated `POST` requests advertise the same resource through `WWW-Authenticate`. For workspace preview or validation calls, pass `workspaceId=` or the `X-CES-Workspace-ID` header. If both are supplied, they must match. Do not reuse Design MCP credentials for runtime agents. Design MCP changes app design; Runtime MCP operates the published or workspace-selected runtime. Runtime MCP-only app agents use the built-in `runtime-operator` Agent Scope by default when they have no explicit assignment. That default exposes Runtime MCP production projection reads and workspace/production command tools, but command and projection `authRules` still decide whether the agent may act on a specific business resource. ## Generated tools Runtime MCP generates: * one `runtime_command_` tool per published command unless excluded from MCP * one `runtime_projection__query` tool per published projection unless excluded from MCP * `runtime_events_import` for controlled operational use * `runtime_channel_*`, `runtime_workspace_*`, and `runtime_user_dm_*` collaboration tools * `runtime_file_read` and `runtime_channel_attachment_read` for authorized file content * `runtime_page_refresh_current` for current-page refresh The exact business tools differ per app. Start with `runtime_capabilities_list`, then inspect a group with `runtime_capability_get` or a specific tool with `runtime_tool_contract_get`. `runtime_tool_contracts_list` lists contracts when a client needs the full surface. ## Design-time tool metadata Design MCP vNext workspaces on registry `pioneer-artifacts-14` can set strict per-tool `runtimeMcp` metadata directly on `model:command` and `model:projection` Artifacts. Use it to declare group, discoverability, risk, task support, output mode, data classification, and human-approval metadata. For example, if app-wide defaults classify tools as reads, set `runtimeMcp.risk: "mutate"` on every mutating Command. This metadata shapes the MCP contract; it does not authorize the caller. Agent Scope and command/projection `authRules` still apply. The app-wide `runtime-mcp` singleton remains platform-managed in vNext, and workspaces pinned to registry `pioneer-artifacts-13` or earlier keep their historical read-only behavior for this field. ## Reserve an action for a human For a human-in-the-loop workflow, set the approval Command's metadata to: ```json { "runtimeMcp": { "expose": "hidden" } } ``` For example, add this field to `ApprovePurchase`. Publish/promote the app configuration, then reconnect your Runtime MCP client. `ApprovePurchase` will be absent from the tool list, tool discovery, command catalog, and execution suggestions. Calling its known MCP tool name also fails without executing the Command, including MCP task calls. Workspace Runtime MCP uses the same rule. The Command remains part of the app: an authorized user can still execute it from your approval page through the normal command API. Model the waiting state and the approval transition in the domain as usual. This setting does not create an approval workflow or grant permissions; use `authRules` when the action must be restricted to human principals across other API surfaces too. `hidden` also excludes projection tools. Unset, `default`, and `discoverable` retain their existing MCP availability. App-wide `runtimeMcp.toolDefaults` apply first; explicit per-command or per-projection metadata overrides them. `requiresHumanApproval` alone is metadata and does not replace this exclusion. Existing MCP sessions must reconnect to pick up the changed tool surface. ## Command tools Command tools execute business decisions. They validate input, auth, permissions, command logic, and event append behavior through the same runtime pipeline as REST and GraphQL. Agents should read relevant projections before executing commands. If a command changes user-visible state, explain the action in the channel or user conversation. ## Projection tools Projection tools read current runtime state. Use filters, sorting, pagination, and output controls to keep agent context focused. Projection output should be treated as read state, not as a source for direct mutation. To change state, execute a command. ## File tools Runtime MCP exposes file bytes through two read-only tools: | Tool | Access boundary | | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `runtime_file_read({ fileId, offset?, maxChars? })` | Reads a durable `FileRef` from the MCP session's exact tenant, app, and Production or Workspace runtime. A `principal` file requires the exact authenticated MCP principal, an explicitly versioned `app` file is available to that runtime, and a `projection-document` file also requires the owning document and its `authRules`. | | `runtime_channel_attachment_read({ channelId, attachmentId, offset?, maxChars? })` | Reads an attachment only when the calling agent is a participant in that channel and the exact attachment metadata was committed by its uploader in a message in the same channel. An attachment id by itself grants nothing. | Text-like MIME types are returned as embedded text resources. Paging defaults to 32,768 characters and `maxChars` is capped at 131,072. Other MIME types are returned as base64 MCP resources up to 8 MiB. Channel chat accepts at most four attachments per message and 8 MiB per attachment, so all accepted channel binaries fit that response boundary. Durable runtime files can be larger (100 MiB by default), but a non-text file above 8 MiB must be handled through an authenticated application download flow instead of being inserted into agent context. Both tools return the stored filename, MIME type, byte size, SHA-256 digest, stable resource URI, and access metadata before the resource body. MIME type is metadata, not permission: authorization is always derived server-side. Durable file authorization is shared with browser `GET`/`HEAD`; tool arguments, roles or tags copied into metadata, and knowledge of a `fileId` do not grant access. Legacy app-wide records that predate explicit authorization fail closed until they are deliberately reclassified or replaced. Existing projection-document records keep their document authorization. Files are not copied into the prompt or `agentTurnContext`. Messages and later session history carry only `channelId`/`attachmentId` pointers, and the agent fetches bytes when needed. No second agent-owned copy or global workspace file is created. A channel upload remains readable while its underlying attachment record exists; deleting the upload makes it unavailable. Durable `FileRef` deletion or `expiresAt` has the same effect. Channel attachments are never implicitly promoted to another channel—an uploader must explicitly attach the same object there, producing a message proof in that channel. ## Channel and user tools Runtime MCP includes collaboration tools for channels, entity channels, users, and DMs. Use them to keep agent work visible and tied to business context. Common flows: * open an entity channel before discussing a specific case or order * post an explanation before executing a sensitive command * set attention when a human needs to respond * DM a user only when the workflow calls for a private message ## Operational tools Event import is powerful. Limit it to migrations, repair work, and controlled operations. Normal workflows should execute commands. Projection rebuild is not exposed through Runtime MCP. Use the appropriate admin, Design MCP, or REST maintenance surface when projection rebuild work is required. ## Agent bridge constraints Runtime MCP is for published app operation. Do not use it as a substitute for Design MCP. If the app model needs to change, switch to a builder workflow and use a scoped Design MCP workspace. Agent bridge failures identify the layer that blocked the call: MCP surface absence, Agent Scope denial, or downstream command/projection auth denial. If Runtime MCP is present but a call is blocked by Agent Scope, assign `runtime-operator` or a custom profile with the required runtime permissions.