MCP App Sandbox Object Structure

Configure the sandbox host, size limits, and rate limits for MCP Apps rendered in chat.

Overview

MCP Apps are interactive interfaces that an MCP server returns alongside a tool result. LibreChat renders each one in a sandboxed frame served from a separate origin, so App content cannot reach the LibreChat page. The mcpAppSandbox object configures that sandbox and the limits applied to Apps.

MCP Apps are turned on with mcpSettings.apps. Every key under mcpAppSandbox is optional and has a default.

Example

mcpAppSandbox:
  url: https://mcp-sandbox.example.com/api/mcp/sandbox
  maxActiveViews: 3
  maxPersistedAppBytes: 1048576
  maxAdmissionRequestsPerMinute: 240
  operationLimits:
    maxBytes: 4194304
    timeoutMs: 30000
    maxActive: 16

Hosting the sandbox

The sandbox page is served by LibreChat itself at /api/mcp/sandbox. Give it a dedicated origin, such as a second hostname whose reverse proxy forwards to the same LibreChat server, and set url to that route on the dedicated origin.

The sandbox page refuses to be embedded unless the LibreChat origin is allowed to frame it. Set MCP_SANDBOX_FRAME_ANCESTORS to the origin users open LibreChat on, for example MCP_SANDBOX_FRAME_ANCESTORS=https://chat.example.com. When it is unset, the page is served with frame-ancestors 'none' and App frames stay blank.

Subkeys

Key	Type	Description	Example
url	String	Full URL of the sandbox page, loaded as the frame source. Point it at the /api/mcp/sandbox route on a dedicated origin that reaches LibreChat. Must use http:// or https://, and must differ from the origin LibreChat is served from. If omitted, the VITE_MCP_SANDBOX_URL build-time value is used when set; without a sandbox URL, Apps are not rendered.	url: "https://mcp-sandbox.example.com/api/mcp/sandbox"
maxSourcesPerDirective	Integer	Maximum number of sources accepted per directive in the Content Security Policy an App declares. Positive. Default: 32.	maxSourcesPerDirective: 32
maxSerializedLength	Integer	Maximum serialized length, in characters, of an App declared Content Security Policy. Positive. Default: 4096.	maxSerializedLength: 4096
maxPersistedAppBytes	Integer	Maximum size in bytes of an App stored with a message. Positive, up to 4194304 (4 MiB). Default: 1048576 (1 MiB).	maxPersistedAppBytes: 1048576
maxPersistedMessageBytes	Integer	Maximum total size in bytes of Apps stored in one message. Positive, up to 12582912 (12 MiB). Default: 12582912.	maxPersistedMessageBytes: 12582912
maxAdmissionRequestsPerMinute	Integer	Rate limit on App admission requests per minute. Positive. Default: 240.	maxAdmissionRequestsPerMinute: 240
maxActiveViews	Integer	Maximum number of App views that can be active at once in the client. Positive, up to 32. Default: 3.	maxActiveViews: 3
maxActionPreviewChars	Integer	Maximum number of characters shown in an action preview when an App asks to act on the user behalf. Positive, up to 131072. Default: 16384.	maxActionPreviewChars: 16384
operationLimits	Object	Limits for operations an App runs through its MCP server: maxBytes, timeoutMs, and maxActive.	See operationLimits below

operationLimits

Key	Type	Description	Example
maxBytes	Integer	Maximum size in bytes of a single operation payload. Positive, up to 16777216 (16 MiB). Default: 4194304 (4 MiB).	maxBytes: 4194304
timeoutMs	Integer	Timeout in milliseconds for one operation. Positive, up to 600000 (10 minutes). Default: 30000.	timeoutMs: 30000
maxActive	Integer	Maximum number of operations running at once. Positive, up to 256. Default: 16.	maxActive: 16