Runtime MCP

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:

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

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=<workspace-id> 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_<command_name> tool per published command unless excluded from MCP
• one runtime_projection_<projection_name>_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:

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

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.