From 578571e45ef745b8814fe00884d158f22e5a294a Mon Sep 17 00:00:00 2001 From: Marco Beretta <81851188+berry-13@users.noreply.github.com> Date: Fri, 23 Oct 2026 17:13:52 +0200 Subject: [PATCH 1/2] docs: Update the core librechat.yaml reference Check the top-level, interface, file, registration, balance, memory, message filter, speech, MCP and skill sync reference pages against the LibreChat config schemas, fix wrong keys and defaults, document the keys that were missing, and add a page for the deployment-owned mcpAppSandbox block. --- .../configuration/librechat_yaml/example.mdx | 31 +-- .../configuration/librechat_yaml/index.mdx | 2 +- .../object_structure/balance.mdx | 74 ++++++- .../object_structure/config.mdx | 187 ++++++++++++++++-- .../object_structure/file_config.mdx | 96 +++++++-- .../object_structure/interface.mdx | 146 +++++++++++++- .../object_structure/mcp_app_sandbox.mdx | 116 +++++++++++ .../object_structure/mcp_servers.mdx | 113 +++++++---- .../object_structure/mcp_settings.mdx | 18 +- .../object_structure/memory.mdx | 6 +- .../object_structure/message_filter.mdx | 27 ++- .../object_structure/meta.de.json | 1 + .../object_structure/meta.es.json | 1 + .../object_structure/meta.fr.json | 1 + .../object_structure/meta.id.json | 1 + .../object_structure/meta.it.json | 1 + .../object_structure/meta.ja.json | 1 + .../librechat_yaml/object_structure/meta.json | 1 + .../object_structure/meta.ko.json | 1 + .../object_structure/meta.nl.json | 1 + .../object_structure/meta.pl.json | 1 + .../object_structure/meta.pt-BR.json | 1 + .../object_structure/meta.tr.json | 1 + .../object_structure/meta.vi.json | 1 + .../object_structure/meta.zh.json | 1 + .../librechat_yaml/object_structure/ocr.mdx | 2 - .../object_structure/registration.mdx | 41 +++- .../object_structure/skill_sync.mdx | 54 ++++- .../object_structure/speech.mdx | 54 +++-- .../object_structure/web_search.mdx | 8 +- 30 files changed, 867 insertions(+), 122 deletions(-) create mode 100644 content/docs/configuration/librechat_yaml/object_structure/mcp_app_sandbox.mdx diff --git a/content/docs/configuration/librechat_yaml/example.mdx b/content/docs/configuration/librechat_yaml/example.mdx index cfef2e4224..9cd20104de 100644 --- a/content/docs/configuration/librechat_yaml/example.mdx +++ b/content/docs/configuration/librechat_yaml/example.mdx @@ -7,13 +7,20 @@ icon: FileCode -This example config includes all documented endpoints (Except Azure, LiteLLM, MLX, and Ollama, which all require additional configurations) +This is a condensed example, not a complete configuration. It covers the pre-configured endpoints and a selection of common settings (Azure, LiteLLM, MLX, and Ollama need additional configuration and are omitted). For every available option, see the [full example file](https://github.com/LibreChat-AI/LibreChat/blob/main/librechat.example.yaml) in the LibreChat repository and the [object structure reference](/docs/configuration/librechat_yaml/object_structure/config). ```yaml filename="librechat.yaml" version: 1.3.18 cache: true +# Other top-level blocks not shown in this condensed example. Each is documented +# in the object structure reference: +# balance: { enabled: true, startBalance: 20000, autoRefillEnabled: false } +# memory: { disabled: false, tokenLimit: 10000 } +# summarization: { enabled: true } +# mcpServers: {} # see the MCP Servers Object Structure page + # Optional deployment-level headers for one self-hosted Langfuse origin or gateway. # Use environment references for credentials. # langfuse: @@ -198,8 +205,6 @@ endpoints: fetch: true titleConvo: true titleModel: 'meta-llama/Llama-2-7b-chat-hf' - summarize: false - summaryModel: 'meta-llama/Llama-2-7b-chat-hf' modelDisplayLabel: 'Anyscale' # APIpie @@ -258,8 +263,6 @@ endpoints: fetch: true titleConvo: true titleModel: 'accounts/fireworks/models/llama-v2-7b-chat' - summarize: false - summaryModel: 'accounts/fireworks/models/llama-v2-7b-chat' modelDisplayLabel: 'Fireworks' dropParams: ['user'] @@ -302,8 +305,6 @@ endpoints: fetch: true titleConvo: true titleModel: 'gpt-3.5-turbo' - summarize: false - summaryModel: 'gpt-3.5-turbo' modelDisplayLabel: 'OpenRouter' # Perplexity @@ -322,8 +323,6 @@ endpoints: fetch: false # fetching list of models is not supported titleConvo: true titleModel: 'sonar-medium-chat' - summarize: false - summaryModel: 'sonar-medium-chat' dropParams: ['stop', 'frequency_penalty'] modelDisplayLabel: 'Perplexity' @@ -336,8 +335,6 @@ endpoints: fetch: true titleConvo: true titleModel: 'gemini-pro' - summarize: false - summaryModel: 'llama-summarize' modelDisplayLabel: 'ShuttleAI' dropParams: ['user'] @@ -396,8 +393,6 @@ endpoints: fetch: false # fetching list of models is not supported titleConvo: true titleModel: 'togethercomputer/llama-2-7b-chat' - summarize: false - summaryModel: 'togethercomputer/llama-2-7b-chat' modelDisplayLabel: 'together.ai' ``` @@ -417,7 +412,7 @@ This example configuration file sets up LibreChat with detailed options across s - **Endpoints**: - **Assistants**: Configures the assistants' endpoint with a polling interval and a timeout for operations, and provides an option to disable the builder interface. - **Custom Endpoints**: - - Configures two external AI service endpoints, Mistral and OpenRouter, including API keys, base URLs, model handling, and specific feature toggles like conversation titles, summarization, and parameter adjustments. + - Configures two external AI service endpoints, Mistral and OpenRouter, including API keys, base URLs, model handling, and specific feature toggles like conversation titles and parameter adjustments. - For Mistral, it enables dynamic model fetching, applies additional parameters for safe prompts, and explicitly drops unsupported parameters. - For OpenRouter, it sets up a basic configuration without dynamic model fetching and specifies a model for conversation titles. @@ -641,13 +636,7 @@ endpoints: # titleMethod: "completion" # Defaults to "completion" if omitted. # Title Model: Specify the model to use for titles. - titleModel: 'mistral-tiny' # Defaults to "gpt-3.5-turbo" if omitted. - - # Summarize setting: Set to true to enable summarization. - # summarize: false - - # Summary Model: Specify the model to use if summarization is enabled. - # summaryModel: "mistral-tiny" # Defaults to "gpt-3.5-turbo" if omitted. + titleModel: 'mistral-tiny' # Defaults to the conversation's model if omitted. # The label displayed for the AI model in messages. modelDisplayLabel: 'Mistral' # Default is "AI" when not set. diff --git a/content/docs/configuration/librechat_yaml/index.mdx b/content/docs/configuration/librechat_yaml/index.mdx index 5b148e6f67..a5fd3c5172 100644 --- a/content/docs/configuration/librechat_yaml/index.mdx +++ b/content/docs/configuration/librechat_yaml/index.mdx @@ -218,7 +218,7 @@ If your server exits immediately after starting, this is likely a configuration 1. Check server logs: `docker compose logs api` 2. Validate your YAML syntax with the [YAML Validator](/toolkit/yaml_checker) -3. Common errors: incorrect indentation, missing colons, unknown keys, invalid values +3. Common errors: incorrect indentation, missing colons, invalid values, and unknown keys. An unknown or misspelled top-level key fails validation and stops the server. Inside nested blocks, strict ones (such as `telemetry`) reject unknown keys the same way, while others silently ignore them **Temporary workaround** (not recommended for production): diff --git a/content/docs/configuration/librechat_yaml/object_structure/balance.mdx b/content/docs/configuration/librechat_yaml/object_structure/balance.mdx index feef8cd552..7d7a7aa412 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/balance.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/balance.mdx @@ -16,6 +16,9 @@ The `balance` object allows administrators to configure how token credit balance - `refillIntervalValue` - `refillIntervalUnit` - `refillAmount` +- `refillMode` +- `reservationTtlMs` +- `display` **Notes:** @@ -34,6 +37,9 @@ balance: refillIntervalValue: 30 refillIntervalUnit: "days" refillAmount: 10000 + refillMode: "add" + reservationTtlMs: 1800000 + display: "credits" ``` @@ -123,7 +129,7 @@ balance: @@ -154,4 +160,68 @@ balance: ```yaml filename="balance / refillAmount" balance: refillAmount: 10000 -``` \ No newline at end of file +``` + + +## refillMode + +**Key:** + + + +**Default:** `"add"` + +**Example:** + +```yaml filename="balance / refillMode" +balance: + autoRefillEnabled: true + refillMode: "reset" + refillIntervalValue: 1 + refillIntervalUnit: "months" + refillAmount: 500000 +``` + + +## reservationTtlMs + +**Key:** + + + +**Default:** `1800000` (30 minutes) + +**Example:** + +```yaml filename="balance / reservationTtlMs" +balance: + reservationTtlMs: 1800000 +``` + + +## display + +**Key:** + + + +**Default:** `"credits"` + +**Example:** + +```yaml filename="balance / display" +balance: + display: "currency" +``` diff --git a/content/docs/configuration/librechat_yaml/object_structure/config.mdx b/content/docs/configuration/librechat_yaml/object_structure/config.mdx index fe27838ee1..33e1266547 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/config.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/config.mdx @@ -89,14 +89,28 @@ Controls retry behavior for concurrent access-control-list writes. 'Maximum compare-and-swap attempts for each ACL document, including the initial write. Only write conflicts are retried.', '3', ], + [ + 'leaseTtlMs', + 'Integer', + 'How long, in milliseconds, a holder keeps the per-resource permission lease without renewing it. Valid values range from 1000 through 600000.', + '30000', + ], + [ + 'leaseWaitMs', + 'Integer', + 'How long, in milliseconds, a permission update waits for a contended per-resource lease before answering with a 409 conflict. Valid values range from 0 through 60000.', + '3000', + ], ]} /> -Valid values range from `1` through `100`. +`maxWriteAttempts` ranges from `1` through `100`. ```yaml filename="permissions" permissions: maxWriteAttempts: 3 + leaseTtlMs: 30000 + leaseWaitMs: 3000 ``` ## langfuse @@ -395,7 +409,7 @@ see: [CloudFront Object Structure](/docs/configuration/librechat_yaml/object_str [ 'filteredTools', 'Array of Strings', - 'Filters out specific tools from both Plugins and OpenAI Assistants endpoints.', + 'Removes specific built-in tools from the tool list available to Agents and Assistants.', 'filteredTools: ["scholarai", "calculator"]', ], ]} @@ -403,11 +417,9 @@ see: [CloudFront Object Structure](/docs/configuration/librechat_yaml/object_str - **Notes**: - If `includedTools` and `filteredTools` are both specified, only `includedTools` will be recognized. - - Affects both `gptPlugins` and `assistants` endpoints - - You can find the names of the tools to filter in [`api/app/clients/tools/manifest.json`](https://github.com/LibreChat-AI/LibreChat/blob/main/api/app/clients/tools/manifest.json) + - Applies to the built-in tools loaded at startup, which Agents and Assistants use. The Ask User tool (`ask_user_question`) also honors these lists. MCP tools are configured separately. + - You can find the names of the tools in [`api/app/clients/tools/manifest.json`](https://github.com/LibreChat-AI/LibreChat/blob/main/api/app/clients/tools/manifest.json) - Use the `pluginKey` value - - Also, any listed under the ".well-known" directory `api/app/clients/tools/.well-known` - - Use the `name_for_model` value ## includedTools @@ -416,7 +428,7 @@ see: [CloudFront Object Structure](/docs/configuration/librechat_yaml/object_str [ 'includedTools', 'Array of Strings', - 'Includes specific tools from both Plugins and OpenAI Assistants endpoints.', + 'Limits the built-in tools available to Agents and Assistants to the listed tools.', 'includedTools: ["calculator"]', ], ]} @@ -424,11 +436,9 @@ see: [CloudFront Object Structure](/docs/configuration/librechat_yaml/object_str - **Notes**: - If `includedTools` and `filteredTools` are both specified, only `includedTools` will be recognized. - - Affects both `gptPlugins` and `assistants` endpoints - - You can find the names of the tools to filter in [`api/app/clients/tools/manifest.json`](https://github.com/LibreChat-AI/LibreChat/blob/main/api/app/clients/tools/manifest.json) + - Applies to the built-in tools loaded at startup, which Agents and Assistants use. The Ask User tool (`ask_user_question`) also honors these lists. MCP tools are configured separately. + - You can find the names of the tools in [`api/app/clients/tools/manifest.json`](https://github.com/LibreChat-AI/LibreChat/blob/main/api/app/clients/tools/manifest.json) - Use the `pluginKey` value - - Also, any listed under the ".well-known" directory `api/app/clients/tools/.well-known` - - Use the `name_for_model` value ## secureImageLinks @@ -718,9 +728,21 @@ see: [Web Search Object Structure](/docs/configuration/librechat_yaml/object_str 'Maximum number of tokens from text files to include in prompts before truncation.', 'fileTokenLimit: 100000', ], + ['imageGeneration', 'Object', 'Output size of generated images, as a percentage or in pixels.', ''], + [ + 'defaultLLMDeliveryPath', + 'Object', + 'How uploads without an explicit destination enter model context (provider, text, or none).', + '', + ], + ['legacyFileUploadUX', 'Boolean', 'Restores the destination chooser and eager, user-selected upload behavior.', ''], + ['fileContextSizeLimit', 'Number', 'Maximum aggregate size (in MB) of model-bound attachments in one Agent turn.', ''], + ['fileContextCharLimit', 'Number', 'Maximum aggregate extracted-text characters in one Agent turn.', ''], ]} /> +See [File Config Object Structure](/docs/configuration/librechat_yaml/object_structure/file_config) for the full reference, including `textFallbackWithoutTools`, `codeEnvLivenessSafeWindowMs`, and `legacySearchProbeTimeoutMs`. + ## clientImageResize **Key:** @@ -1086,7 +1108,9 @@ The confirmation endpoint is unauthenticated, so it is bounded by source address @@ -1244,6 +1268,7 @@ see: [Memory Object Structure](/docs/configuration/librechat_yaml/object_structu **Note:** Endpoints support [Shared Endpoint Settings](/docs/configuration/librechat_yaml/object_structure/shared_endpoint_settings) such as `streamRate`, `headers`, `titleModel`, `titleMethod`, `titlePrompt`, `titlePromptTemplate`, `titleEndpoint`, and `maxToolResultChars`. These can be configured individually per endpoint or globally using the `all` key. `headers` are merged with endpoint-level values winning on key collisions. The `all` key does not accept `baseURL`. +> **Note:** The `openAI`, `google`, `anthropic`, and `bedrock` keys are documented with their providers: [OpenAI](/docs/configuration/pre_configured_ai/openai), [Google](/docs/configuration/pre_configured_ai/google), [Anthropic](/docs/configuration/pre_configured_ai/anthropic), and [AWS Bedrock](/docs/configuration/librechat_yaml/object_structure/aws_bedrock). + > **Note:** `endpoints.agents.pullRequests` configures the conversation pull request chip and sidebar mark. See [`pullRequests`](/docs/configuration/librechat_yaml/object_structure/agents#pullrequests). > **Note:** `endpoints.allowedAddresses` applies to user-provided `baseURL` values (when an admin configures a custom endpoint with `apiKey: 'user_provided'` and `baseURL: 'user_provided'`). Each user-supplied baseURL is validated against the SSRF block at request time; entries listed here are exempted. See [`mcpSettings.allowedAddresses`](/docs/configuration/librechat_yaml/object_structure/mcp_settings#allowedaddresses) for the field semantics — same rules apply (private IP space only, port required, no URLs/paths/CIDR/bare hosts/public IP literals). @@ -1619,7 +1650,7 @@ see: [MCP Settings Object Structure](/docs/configuration/librechat_yaml/object_s - `stdio` - `websocket` - `sse` - - `streamable-http` + - `streamable-http` (`http` is accepted as an alias) - The `type` field specifies the connection type to the MCP server. - If `type` is omitted, it defaults based on the presence and format of `url` or `command`: - If `url` is specified and starts with `http` or `https`, `type` defaults to `sse`. @@ -1763,6 +1794,134 @@ see: [Turnstile Object Structure](/docs/configuration/librechat_yaml/object_stru see: [Transactions Object Structure](/docs/configuration/librechat_yaml/object_structure/transactions) +## telemetry + +Controls browser real user monitoring (RUM). This block rejects unknown keys. + + + +```yaml filename="telemetry" +telemetry: + rum: + enabled: true + sessionReplay: + enabled: false +``` + +## credentials + + + +```yaml filename="credentials" +credentials: + writeFormat: v3 +``` + +## toolCallPreviews + +Bounds the tool call output and arguments sent when a conversation loads. The client receives the start and end of each long string and fetches a part in full only when the reader opens it. Set `enabled: false` to send every load in full. + + + +```yaml filename="toolCallPreviews" +toolCallPreviews: + enabled: true + outputChars: 512 + argsChars: 512 +``` + +## githubCompare + +Controls the GitHub Compare tool, which compares commit ancestry in a public GitHub repository without a workspace. It is available to agents only and is off by default. This block rejects unknown keys. + + + +```yaml filename="githubCompare" +githubCompare: + enabled: true + timeoutMs: 10000 +``` + +## passwordHashing + +Password and auth token hashing runs on worker threads, off the event loop. + + + +```yaml filename="passwordHashing" +passwordHashing: + maxWorkers: 2 +``` + +## timeouts + +Time budgets, in milliseconds, for outbound calls made inside a request. Each key is optional and takes a positive integer up to 2147483647. Exceeding a budget fails the call with an error naming the key. + + + +```yaml filename="timeouts" +timeouts: + ragMs: 30000 + ocrMs: 300000 +``` + +## openapi + + + +```yaml filename="openapi" +openapi: + enabled: true +``` + +## skillDeletion + +Controls how deleted Skills are finalized and cleaned up in the background. See [Skill Deletion](/docs/configuration/librechat_yaml/object_structure/skill_sync#skill-deletion) for the keys. + +## mcpAppSandbox + +Configures the sandbox host, size limits, and rate limits for MCP Apps rendered in chat. See [MCP App Sandbox Object Structure](/docs/configuration/librechat_yaml/object_structure/mcp_app_sandbox). + +## balance + +Configures token credit balances, including starting balance, automatic refills, refill mode, and how the balance is displayed. See [Balance Object Structure](/docs/configuration/librechat_yaml/object_structure/balance). + ## Additional links - [Summarization Object Structure](/docs/configuration/librechat_yaml/object_structure/summarization) diff --git a/content/docs/configuration/librechat_yaml/object_structure/file_config.mdx b/content/docs/configuration/librechat_yaml/object_structure/file_config.mdx index 08552a0809..1144b4a70f 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/file_config.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/file_config.mdx @@ -7,18 +7,22 @@ icon: FileCode The `fileConfig` object allows you to configure file handling settings for the application, including size limits and MIME type restrictions. This section provides a detailed breakdown of the `fileConfig` object structure. -There are 13 main fields under `fileConfig`: +The main fields under `fileConfig` are: - `endpoints` - `skills` - `serverFileSizeLimit` - `avatarSizeLimit` - `imageGeneration` + - `clientImageResize` - `fileTokenLimit` - `fileContextSizeLimit` - `fileContextCharLimit` - `defaultLLMDeliveryPath` - `legacyFileUploadUX` + - `textFallbackWithoutTools` + - `codeEnvLivenessSafeWindowMs` + - `legacySearchProbeTimeoutMs` - `ocr` - `text` - `stt` @@ -79,7 +83,10 @@ fileConfig: legacyFileUploadUX: false imageGeneration: percentage: 100 - px: 1024 + clientImageResize: + maxWidth: 1900 + maxHeight: 1900 + quality: 0.92 ocr: supportedMimeTypes: - "^image/(jpeg|gif|png|webp|heic|heif)$" @@ -106,20 +113,24 @@ fileConfig: ]} /> -`skills` supports two parameters: +`skills` supports three parameters: -- `fileSizeLimit` (Integer) +- `fileSizeLimit` (Number) - Maximum size of a single Skill upload, specified in megabytes (MB). - **Default:** `50` - `importCleanupConcurrency` (Integer) - Maximum concurrent cleanup operations after a failed Skill archive import. Use `1` for serial cleanup. - **Default:** `8` +- `deletionCleanupConcurrency` (Integer) + - Maximum concurrent cleanup operations when a Skill is deleted. Use `1` for serial cleanup. + - **Default:** `8` ```yaml filename="fileConfig / skills" fileConfig: skills: fileSizeLimit: 50 importCleanupConcurrency: 8 + deletionCleanupConcurrency: 8 ``` See [Skills](/docs/features/skills) for the rest of the import rules, such as the per-file and archive-entry limits. @@ -128,7 +139,7 @@ See [Skills](/docs/features/skills) for the rest of the import rules, such as th @@ -141,7 +152,7 @@ fileConfig: @@ -160,15 +171,15 @@ fileConfig: `imageGeneration` supports the following parameters: -- `percentage` (Integer) +- `percentage` (Number) - The output size of the generated image expressed as a percentage (e.g., `100` means 100% of base size). - Use this to scale the output image relative to a default or original size. -- `px` (Integer) +- `px` (Number) - Specifies the output image dimension in pixels (e.g., `1024`). - Use this to explicitly set the output size of the generated image regardless of base size. -You may set only one of these parameters (`percentage` or `px`), not both, depending on your use case +Set only one of these parameters (`percentage` or `px`), not both. Example configuration: @@ -176,7 +187,28 @@ Example configuration: fileConfig: imageGeneration: percentage: 100 - px: 1024 +``` + +## clientImageResize + +Controls client-side resizing of images before upload, which prevents upload errors from oversized images. Users can toggle resizing in Settings > Chat. Setting `enabled` here overrides that choice for everyone and locks the toggle; omit it to leave users in control. + +- `enabled` (Boolean) + - Force resizing on (`true`) or off (`false`) for everyone. When omitted, each user decides, with resizing on by default. +- `maxWidth` (Number) + - Maximum width of resized images, in pixels. Minimum `1`. **Default:** `1900` +- `maxHeight` (Number) + - Maximum height of resized images, in pixels. Minimum `1`. **Default:** `1900` +- `quality` (Number) + - JPEG compression quality from `0` to `1`. **Default:** `0.92` + +```yaml filename="fileConfig / clientImageResize" +fileConfig: + clientImageResize: + enabled: true + maxWidth: 1900 + maxHeight: 1900 + quality: 0.92 ``` ## fileTokenLimit @@ -259,6 +291,44 @@ fileConfig: legacyFileUploadUX: true ``` +## textFallbackWithoutTools + +When an upload is routed to `none` (stored, available only to tools) and the turn runs no tool that can read it, LibreChat can deliver the file's extracted text instead. Set `textFallbackWithoutTools: true` to enable this. It can be set globally under `fileConfig`, or per entry under `fileConfig.endpoints` (including `default`); an endpoint value takes precedence over the global one. + +**Default:** `false` + +It applies only to message attachments whose route was inferred; a destination the user chose explicitly is never re-resolved, and files kept on an agent's tool resources never reach a prompt. Only the built-in document and plain-text extractors run, so no RAG or OCR call is made for a file meant for a tool. Existing files without extracted text are not backfilled. + +```yaml filename="fileConfig / textFallbackWithoutTools" +fileConfig: + textFallbackWithoutTools: true + endpoints: + openAI: + textFallbackWithoutTools: false +``` + +## codeEnvLivenessSafeWindowMs + +Files provisioned to the code execution environment within this window (in milliseconds) skip the live availability check before reuse. Minimum `0`. + +**Default:** `21600000` (6 hours) + +```yaml filename="fileConfig / codeEnvLivenessSafeWindowMs" +fileConfig: + codeEnvLivenessSafeWindowMs: 21600000 +``` + +## legacySearchProbeTimeoutMs + +How long, in milliseconds, priming waits on a legacy File Search availability check before embedding the file anyway. Minimum `1`. + +**Default:** `5000` + +```yaml filename="fileConfig / legacySearchProbeTimeoutMs" +fileConfig: + legacySearchProbeTimeoutMs: 5000 +``` + ## ocr @@ -471,7 +543,7 @@ YourCustomEndpointName: **Key:** diff --git a/content/docs/configuration/librechat_yaml/object_structure/interface.mdx b/content/docs/configuration/librechat_yaml/object_structure/interface.mdx index 5bb2438ec0..b5253190c5 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/interface.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/interface.mdx @@ -51,6 +51,16 @@ These are fields under `interface`: - `queuedSendLockTimeoutMs` - `peoplePicker` - `marketplace` +- `landingHeading` +- `landingFooter` +- `runningChatRename` +- `colorModeFromUrl` +- `historyCacheTtlMs` +- `historyCacheRecent` +- `historyCacheMaxBytes` +- `buildInfo` +- `mascot` +- `traceViewer` **Notes:** @@ -1036,6 +1046,18 @@ Enables the experimental [Scheduled Chats](/docs/features/scheduled_chats) panel 'Pins every scheduled conversation to one Chat Project, overriding the stored choice and implying `requireProject`.', '', ], + [ + 'mcpConsent', + 'Object', + 'Controls the stored consent that lets scheduled runs use MCP tools. Sub-keys: enabled (Boolean), maxLifetimeHours (1-8760), resources (record of resource bindings), and readOnlyPolicy (record of trusted read-only tool declarations keyed by server and upstream tool name).', + '', + ], + [ + 'mcpReceiptRetry', + 'Object', + 'Bounded exponential retry interval for MCP consent receipts, with jitter. Sub-keys: baseMs (100-60000, default 250) and maxMs (100-600000, default 30000). maxMs must be at least baseMs.', + '', + ], ]} /> @@ -1686,7 +1708,10 @@ Enables/disables access to the Agent Marketplace. **Sub-keys:** **Default:** @@ -1703,3 +1728,122 @@ interface: marketplace: use: true # Enable marketplace access ``` + +## landingHeading + +Chooses what heads the welcome screen when an agent, assistant, or branded model spec is selected: its name (`entity`) or the time-of-day greeting with the user's name (`greeting`). Use `greeting` when your header selector already names the entity. + +**Default:** `entity` + +```yaml filename="interface / landingHeading" +interface: + landingHeading: greeting +``` + +## landingFooter + +Shows the generic disclaimer and policy links beneath the welcome screen's composer. A configured custom footer still renders when this is `false`. + +**Default:** `true` + +```yaml filename="interface / landingFooter" +interface: + landingFooter: false +``` + +## runningChatRename + +Allows renaming a conversation while it is running. Set to `false` during a rolling upgrade, until every API replica supports title ownership and old title jobs have drained. + +**Default:** `true` + +```yaml filename="interface / runningChatRename" +interface: + runningChatRename: false +``` + +## colorModeFromUrl + +Accepts `?theme=dark`, `?theme=light`, or `?theme=system` on an entry link as the user's color mode, so another app can hand its mode over. + +**Default:** `false` + +```yaml filename="interface / colorModeFromUrl" +interface: + colorModeFromUrl: true +``` + +## historyCacheTtlMs + +Milliseconds a conversation's message history stays cached in the browser after the user leaves it, so returning soon renders without refetching. Long agent transcripts can run to tens of megabytes, so keep this short for mobile browsers. + +**Default:** `60000`. Valid values range from `0` to `3600000`. + +## historyCacheRecent + +How many of the most recently left conversations keep that grace period. Older ones are released at the next conversation switch. + +**Default:** `1`. Valid values range from `0` to `20`. + +## historyCacheMaxBytes + +Aggregate estimated payload budget, in bytes, for histories kept during the grace period. Oversized histories reload on return; histories that are being observed, running, or belong to Assistants stay. `0` disables the grace period. This is not a browser heap limit. + +**Default:** `8388608` (8 MiB) + +```yaml filename="interface / history cache" +interface: + historyCacheTtlMs: 60000 + historyCacheRecent: 1 + historyCacheMaxBytes: 8388608 +``` + +## buildInfo + +Controls whether build information (such as the commit and version) is shown in Settings > About and returned by the configuration endpoint. Set to `false` to hide it. + +**Default:** `true` + +```yaml filename="interface / buildInfo" +interface: + buildInfo: false +``` + +## mascot + +Allows Lia, the welcome screen mascot. Users still opt in from Settings. + +**Default:** `true` + +```yaml filename="interface / mascot" +interface: + mascot: false +``` + +## traceViewer + +Shows a conversation trace control for traces this deployment exported to Langfuse, with a record inspector. It depends on Langfuse tracing being set up; see [Langfuse](/docs/configuration/langfuse). + + + +```yaml filename="interface / traceViewer" +interface: + traceViewer: + enabled: true + showInputOutput: false + showToolNames: false + maxRecords: 1000 + maxContentLength: 50000 + requestsPerMinute: 30 + requestTimeoutMs: 10000 +``` diff --git a/content/docs/configuration/librechat_yaml/object_structure/mcp_app_sandbox.mdx b/content/docs/configuration/librechat_yaml/object_structure/mcp_app_sandbox.mdx new file mode 100644 index 0000000000..3e216c2146 --- /dev/null +++ b/content/docs/configuration/librechat_yaml/object_structure/mcp_app_sandbox.mdx @@ -0,0 +1,116 @@ +--- +title: 'MCP App Sandbox Object Structure' +icon: Blocks +description: 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`](/docs/configuration/librechat_yaml/object_structure/mcp_settings#apps). Every key under `mcpAppSandbox` is optional and has a default. + +## Example + +```yaml filename="mcpAppSandbox" +mcpAppSandbox: + url: https://sandbox.example.com/ + maxActiveViews: 3 + maxPersistedAppBytes: 1048576 + maxAdmissionRequestsPerMinute: 240 + operationLimits: + maxBytes: 4194304 + timeoutMs: 30000 + maxActive: 16 +``` + +## Subkeys + + + +### operationLimits + + + +## References + +- [MCP Settings](/docs/configuration/librechat_yaml/object_structure/mcp_settings) +- [MCP Servers](/docs/configuration/librechat_yaml/object_structure/mcp_servers) diff --git a/content/docs/configuration/librechat_yaml/object_structure/mcp_servers.mdx b/content/docs/configuration/librechat_yaml/object_structure/mcp_servers.mdx index cd0f9843f1..40577abd8e 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/mcp_servers.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/mcp_servers.mdx @@ -89,7 +89,7 @@ mcpServers: [ '', 'Object', - 'Each key under `mcpServers` represents an individual MCP server configuration, identified by a unique name. This name is used to reference the server configuration within the application.', + 'Each key under mcpServers represents an individual MCP server configuration, identified by a unique name. This name is used to reference the server configuration within the application.', '', ], ]} @@ -122,43 +122,43 @@ mcpServers: [ 'type', 'String', - 'Specifies the connection type to the MCP server. Valid options are `"stdio"`, `"websocket"`, `"streamable-http"`, or `"sse"`. If omitted, it defaults based on the presence and format of `url` or `command`.', + 'Specifies the connection type to the MCP server. Valid options are "stdio", "websocket", "streamable-http" (or its alias "http"), or "sse". If omitted, it defaults based on the presence and format of url or command.', 'type: "stdio"', ], [ 'command', 'String', - '(For `stdio` type) The command or executable to run to start the MCP server.', + '(For stdio type) The command or executable to run to start the MCP server.', 'command: "npx"', ], [ 'args', 'Array of Strings', - '(For `stdio` type) Command line arguments to pass to the `command`.', + '(For stdio type) Command line arguments to pass to the command. Supports the same placeholders as env.', 'args: ["-y", "@modelcontextprotocol/server-puppeteer"]', ], [ 'url', 'String', - '(For `websocket`, `streamable-http`, or `sse` type) The URL to connect to the MCP server.', + '(For websocket, streamable-http, or sse type) The URL to connect to the MCP server.', 'url: "http://localhost:3001/sse"', ], [ 'proxy', 'String', - '(Optional, for `sse` and `streamable-http` types) Outbound proxy URL for this remote MCP server. Supports `http://`, `https://`, `socks://`, and `socks5://` URLs.', + '(Optional, for sse and streamable-http types) Outbound proxy URL for this remote MCP server. Supports http://, https://, socks://, and socks5:// URLs.', 'proxy: "${MCP_PROXY_URL}"', ], [ 'headers', 'Object', - '(Optional, for `sse` and `streamable-http` types) Custom headers to send with the request. Supports dynamic user field substitution with `{{LIBRECHAT_USER_*}}` placeholders and environment variables with `${ENV_VAR}`.', + '(Optional, for sse and streamable-http types) Custom headers to send with the request. Supports dynamic user field substitution with {{LIBRECHAT_USER_*}} placeholders and environment variables with ${ENV_VAR}.', 'headers:\n X-User-ID: "{{LIBRECHAT_USER_ID}}"\n X-API-Key: "${SOME_API_KEY}"', ], [ 'apiKey', 'Object', - '(Optional, for `sse` and `streamable-http` types) API key authentication configuration for the MCP server.', + '(Optional, for sse and streamable-http types) API key authentication configuration for the MCP server.', 'See apiKey section below', ], [ @@ -170,7 +170,7 @@ mcpServers: [ 'chatMenu', 'Boolean', - '(Optional) When `false`, excludes the MCP server from the regular chat picker and rejects it from picker-supplied chat selections. Saved Agents and explicitly assigned model specs can still use it. Defaults to `true`.', + '(Optional) When false, excludes the MCP server from the regular chat picker and rejects it from picker-supplied chat selections. Saved Agents and explicitly assigned model specs can still use it. Defaults to true.', 'chatMenu: false', ], [ @@ -182,37 +182,43 @@ mcpServers: [ 'timeout', 'Integer', - '(Optional) Timeout in milliseconds for MCP server requests. Must be a non-negative integer.', - 'timeout: 30000', + '(Optional) Timeout in milliseconds for MCP server requests. Must be a non-negative integer. Defaults to 60000.', + 'timeout: 60000', ], [ 'initTimeout', 'Integer', - '(Optional) Timeout in milliseconds for MCP server initialization. Must be a non-negative integer.', - 'initTimeout: 10000', + '(Optional) Timeout in milliseconds for MCP server initialization. Must be a non-negative integer. Defaults to 30000.', + 'initTimeout: 30000', + ], + [ + 'sseReadTimeout', + 'Integer', + '(Optional, for sse and streamable-http types) Timeout in milliseconds for the body of the long-lived SSE stream. Must be a positive integer. Defaults to 300000.', + 'sseReadTimeout: 300000', ], [ 'env', 'Object', - '(Optional, `stdio` type only) Environment variables to use when spawning the process.', + '(Optional, stdio type only) Environment variables to use when spawning the process.', 'env:\n NODE_ENV: "production"', ], [ 'requiresOAuth', 'Boolean', - "(Optional, remote transports: `sse`, `streamable-http`, `websocket`) Whether this server requires OAuth authentication. If not specified, will be auto-detected during server startup. Although optional, it's best to set this value explicitly if you know whether the server requires OAuth or not. Setting `requiresOAuth: false` is useful for servers protected by a static `Authorization` header, to skip auto-detection that would otherwise misclassify them as OAuth-protected.", + "(Optional, remote transports: sse, streamable-http, websocket) Whether this server requires OAuth authentication. If not specified, will be auto-detected during server startup. Although optional, it's best to set this value explicitly if you know whether the server requires OAuth or not. Setting requiresOAuth: false is useful for servers protected by a static Authorization header, to skip auto-detection that would otherwise misclassify them as OAuth-protected.", 'requiresOAuth: false', ], [ 'stderr', 'String or Integer', - '(Optional, `stdio` type only) How to handle `stderr` of the child process. Options: `"pipe"`, `"ignore"`, `"inherit"`, or a non-negative integer (file descriptor). Defaults to `"inherit"`.', + '(Optional, stdio type only) How to handle stderr of the child process. Options: "pipe", "ignore", "inherit", or a non-negative integer (file descriptor). Defaults to "inherit".', 'stderr: "inherit"', ], [ 'customUserVars', 'Object', - '(Optional) Defines custom variables that users can set for this MCP server, allowing for per-user credentials or configurations (e.g., API keys). These variables can then be referenced in `headers` or `env` fields.', + '(Optional) Defines custom variables that users can set for this MCP server, allowing for per-user credentials or configurations (e.g., API keys). These variables can then be referenced in headers or env fields. Each variable requires a title and a description.', 'customUserVars:\n API_KEY:\n title: "API Key"\n description: "Your personal API key."', ], [ @@ -230,19 +236,19 @@ mcpServers: [ 'oauthPrompt', 'String', - "(Optional) When an OAuth server asks a user to sign in. `on_start` (default) asks when the conversation turn starts. `on_use` waits until the agent first calls one of the server's tools, when every tool the agent selected from the server is deferred and `oauthToolCatalog` is declared.", + "(Optional) When an OAuth server asks a user to sign in. on_start (default) asks when the conversation turn starts. on_use waits until the agent first calls one of the server's tools, when every tool the agent selected from the server is deferred and oauthToolCatalog is declared.", 'oauthPrompt: on_use', ], [ 'oauthToolCatalog', 'Array of Objects', - '(Optional) Tools an `oauthPrompt: on_use` server offers to tool search before the user signs in. Each entry has a `name` and an optional `description` and `inputSchema`.', + '(Optional) Tools an oauthPrompt: on_use server offers to tool search before the user signs in. Each entry has a name and an optional description and inputSchema.', 'oauthToolCatalog:\n - name: read_sheet\n description: Read the values in a spreadsheet range', ], [ 'obo', 'Object', - "(Optional, for `sse` and `streamable-http` types) On-Behalf-Of token exchange configuration. Exchanges the current user's OpenID access token for a delegated downstream token and forwards it as a Bearer token.", + "(Optional, for sse and streamable-http types) On-Behalf-Of token exchange configuration. Exchanges the current user's OpenID access token for a delegated downstream token and forwards it as a Bearer token.", 'obo:\n scopes: "api://mcp-server-id/Mcp.Tools.ReadWrite"', ], [ @@ -283,7 +289,7 @@ mcpServers: #### `type` - **Type:** String -- **Description:** Specifies the connection type to the MCP server. Valid options are `"stdio"`, `"websocket"`, `"streamable-http"`, or `"sse"`. +- **Description:** Specifies the connection type to the MCP server. Valid options are `"stdio"`, `"websocket"`, `"streamable-http"`, or `"sse"`. `"http"` is accepted as an alias of `"streamable-http"`. - **Default Value:** Determined based on the presence and format of `url` or `command`. #### `command` @@ -294,7 +300,7 @@ mcpServers: #### `args` - **Type:** Array of Strings -- **Description:** (For `stdio` type) Command line arguments to pass to the `command`. +- **Description:** (For `stdio` type) Command line arguments to pass to the `command`. Placeholders such as `${ENV_VAR}`, `{{LIBRECHAT_USER_*}}`, and `{{CUSTOM_VARIABLE_NAME}}` are resolved in each argument, the same as in `env`. #### `url` @@ -331,7 +337,7 @@ mcpServers: - `{{LIBRECHAT_GRAPH_*}}`: Microsoft Graph token placeholders for YAML-defined servers. - `{{LIBRECHAT_BODY_*}}`: Request body placeholders for YAML-defined servers, such as the current `conversationId`, `parentMessageId`, or `messageId`. - `{{CUSTOM_VARIABLE_NAME}}`: Replaced with the value provided by the user for a variable defined in `customUserVars` (e.g., `{{MY_API_KEY}}`). - - `${ENV_VAR}`: Will be replaced with the value of the environment variable `{{ENV_VAR}}`. + - `${ENV_VAR}`: Will be replaced with the value of the environment variable `ENV_VAR`. **Available User Field Placeholders:** @@ -403,14 +409,15 @@ requestHeaders: - **Type:** Object (Optional, for `sse` and `streamable-http` types) - **Description:** API key authentication configuration for the MCP server. Provides a structured way to configure API key-based authentication. - **Sub-keys:** - - `source`: String - Where the API key comes from. Options: - - `"admin"`: API key is configured by the administrator (in environment variables or config) + - `source`: String (Required) - Where the API key comes from. Options: + - `"admin"`: API key is configured by the administrator with `key` - `"user"`: API key is provided by the user through the UI - - `authorization_type`: String - How the API key is sent in requests. Options: + - `key`: String - (For `source: "admin"`) The API key value, shared by all users. Supports `${ENV_VAR}` references. With `source: "admin"`, no header is sent when `key` is omitted. + - `authorization_type`: String (Required) - How the API key is sent in requests. Options: - `"bearer"`: Sent as `Authorization: Bearer ` - `"basic"`: Sent as `Authorization: Basic ` - `"custom"`: Sent in a custom header (requires `custom_header`) - - `custom_header`: String - (Required when `authorization_type` is `"custom"`) The header name to use for the API key + - `custom_header`: String - (Used when `authorization_type` is `"custom"`) The header name to use for the API key. Defaults to `X-Api-Key` when omitted. - **Example:** ```yaml @@ -420,6 +427,7 @@ requestHeaders: url: https://api.example.com/mcp apiKey: source: 'admin' + key: '${MY_SERVER_API_KEY}' authorization_type: 'bearer' # User-provided API key with custom header @@ -483,19 +491,25 @@ For UI-created, shared servers using `apiKey.source: user`, saved keys are bound - `{{LIBRECHAT_USER_ID}}`: Replaced with the current user's ID. - `{{LIBRECHAT_USER_*}}`: Dynamic user field placeholders (e.g., `{{LIBRECHAT_USER_EMAIL}}`). - `{{CUSTOM_VARIABLE_NAME}}`: Replaced with the value provided by the user for a variable defined in `customUserVars` (e.g., `{{MY_API_KEY}}`). - - `${ENV_VAR}`: Replaced with the value of the server-side environment variable `{{ENV_VAR}}`. + - `${ENV_VAR}`: Replaced with the value of the server-side environment variable `ENV_VAR`. #### `timeout` - **Type:** Integer (Optional) -- **Description:** Timeout in milliseconds for MCP server requests. Must be a non-negative integer. -- **Default Value:** `30000` (30 seconds) +- **Description:** Timeout in milliseconds for MCP server requests. Must be a non-negative integer. For `sse` connections, the same value also bounds the initial connection, which waits up to 120000 ms (2 minutes) when `timeout` is not set. +- **Default Value:** `60000` (60 seconds) #### `initTimeout` - **Type:** Integer (Optional) - **Description:** Timeout in milliseconds for MCP server initialization. Must be a non-negative integer. -- **Default Value:** `10000` (10 seconds) +- **Default Value:** `30000` (30 seconds) + +#### `sseReadTimeout` + +- **Type:** Integer (Optional, for `sse` and `streamable-http` types) +- **Description:** Timeout in milliseconds for the body of the long-lived SSE `GET` stream. If no data arrives within this window, the stream is aborted. Must be a positive integer. +- **Default Value:** `300000` (5 minutes) #### `requiresOAuth` @@ -511,7 +525,7 @@ For UI-created, shared servers using `apiKey.source: user`, saved keys are bound #### OAuth refresh coordination -For multi-replica deployments, `oauthRefreshCoordination: true` serializes token refresh through the shared Redis instance. `oauthRefreshWaitTimeout` controls how long a replica waits for the refresh result, and `oauthPersistenceWaitTimeout` controls how long it waits for refreshed credentials to become readable; both default to `15000` milliseconds. +For multi-replica deployments, `oauthRefreshCoordination: true` serializes token refresh through the shared Redis instance. `oauthRefreshWaitTimeout` controls how long a replica waits for the refresh result, and `oauthPersistenceWaitTimeout` controls how long it waits for refreshed credentials to become readable; both default to `15000` milliseconds. `oauthRefreshWaitTimeout` is clamped to a maximum of `30000`, and `oauthPersistenceWaitTimeout` accepts at most `840000` (14 minutes). Enable coordination only after every replica is upgraded and connected to the same Redis deployment. Use identical values on every replica, drain active requests before changing the setting, and avoid toggling it during a rolling deployment. @@ -529,7 +543,7 @@ Enable coordination only after every replica is upgraded and connected to the sa - The `customUserVars` object contains keys, where each key represents a variable name (e.g., `MY_API_KEY`). This name will be used in placeholders like `{{MY_API_KEY}}`. - Each variable name is an object with the following subkeys: - `title`: String (Required) - A user-friendly title for the variable, displayed in the configuration UI. - - `description`: String (Optional) - A description or instructions for the variable, also displayed in the UI to guide the user. HTML can be used in this field (e.g., to create a link: `More info`). + - `description`: String (Required) - A description or instructions for the variable, also displayed in the UI to guide the user. HTML can be used in this field (e.g., to create a link: `More info`). - `sensitive`: Boolean (Optional) - Controls whether the value is treated as a secret and masked in the UI. Defaults to masked/secret behavior when omitted; set to `false` for non-secret fields such as project IDs or base URLs. - **Usage in `headers` and `env`:** - Once defined under `customUserVars`, these variables can be referenced in the `headers` (for `sse` and `streamable-http` types) or `env` (for `stdio` type) sections using the `{{VARIABLE_NAME}}` syntax. @@ -546,6 +560,7 @@ Enable coordination only after every replica is upgraded and connected to the sa alt="MCP Per-User Variables Configuration - Settings Panel Access" width={300} /> + - Servers created in the UI resolve only the variables they declare in `customUserVars`. They do not resolve `${ENV_VAR}` references or `{{LIBRECHAT_USER_*}}` placeholders. - These user-provided values are stored securely, associated with the individual user and the specific MCP server, and substituted at runtime. - **Example:** ```yaml @@ -600,22 +615,28 @@ See [OpenID Connect Token Reuse](/docs/configuration/authentication/OAuth2-OIDC/ - **Type:** Object (Optional) - **Description:** OAuth2 configuration for authenticating with the MCP server. When configured, users will be prompted to authenticate via OAuth flow before the MCP server can be used. If no client id & client secret is provided, Dynamic Client Registration (DCR) will be used. -- **Required Subkeys:** +- **Subkeys:** All `oauth` subkeys are optional. Endpoints can be auto-discovered, and a client can be obtained through Dynamic Client Registration. - `authorization_url`: String - The OAuth authorization endpoint URL - `token_url`: String - The OAuth token endpoint URL - `client_id`: String - OAuth client identifier - - `client_secret`: String - OAuth client secret - - `redirect_uri`: String - [OAuth redirect URI](/docs/features/mcp#oauth-callback-url) (eg. `http://localhost:3080/api/mcp/${serverName}/oauth/callback`) + - `client_secret`: String - OAuth client secret. Requires `client_id`, and a `client_id` with a `client_secret` also requires both `authorization_url` and `token_url`. + - `redirect_uri`: String - [OAuth redirect URI](/docs/features/mcp#oauth-callback-url). Defaults to `/api/mcp/{serverName}/oauth/callback`. - `scope`: String - OAuth scopes (space-separated) -- **Optional Subkeys:** +- **Additional Subkeys:** - `grant_types_supported`: Array of Strings - Supported grant types (defaults to `["authorization_code", "refresh_token"]`) - `token_endpoint_auth_methods_supported`: Array of Strings - Supported token endpoint authentication methods (defaults to `["client_secret_basic", "client_secret_post"]`) - `token_exchange_method`: String - Optional token exchange override. Use `default_post` to send client credentials in the form-encoded POST body, or `basic_auth_header` to send them in an HTTP Basic authorization header. When omitted, LibreChat discovers the provider's advertised token endpoint authentication methods and defaults to Basic auth if none are advertised. - `response_types_supported`: Array of Strings - Supported response types (defaults to `["code"]`) - `code_challenge_methods_supported`: Array of Strings - Supported PKCE code challenge methods (defaults to `["S256", "plain"]`) - `skip_code_challenge_check`: Boolean - Skip checking whether the OAuth provider advertises PKCE support. Useful for providers like AWS Cognito that support S256 but don't advertise it in their metadata. (defaults to `false`) + - `revocation_endpoint`: String - Token revocation endpoint URL. Auto-discovered when omitted. + - `revocation_endpoint_auth_methods_supported`: Array of Strings - Authentication methods supported by the revocation endpoint. Auto-discovered when omitted. + - `audience`: String - Sent as the `audience` parameter on the authorization request, for providers such as Auth0 that issue API-scoped tokens only when an audience is requested. Admin-only: rejected for servers users create in the UI. + - `forward_audience_on_refresh`: Boolean - Whether `audience` is also sent on the `refresh_token` grant. Defaults to `true`, which Auth0 needs. Set to `false` for providers with strict token endpoints, such as AWS Cognito, that reject the extra parameter. Ignored when `audience` is not set. Admin-only. + - `send_resource_parameter`: Boolean - Whether the RFC 8707 `resource` parameter is sent on the authorization request, the code exchange, and the refresh grant. Defaults to `true`. Set to `false` for providers that reject it, such as Microsoft Entra ID v2.0, which fails with `AADSTS9010010` when `resource` and `scope` are both sent. Use `scope` or `audience` to obtain an API-scoped token instead. Admin-only. - **Environment variables:** YAML-defined OAuth URL fields, including `authorization_url`, `token_url`, `redirect_uri`, and `revocation_endpoint`, can use `${ENV_VAR}` references. LibreChat resolves the environment value before URL validation. User-managed OAuth endpoint URLs submitted through the UI must be literal URLs and reject `${ENV_VAR}` placeholders. - **Example:** + ```yaml oauth-api-server: authorization_url: https://api.example.com/oauth/authorize @@ -631,6 +652,17 @@ See [OpenID Connect Token Reuse](/docs/configuration/authentication/OAuth2-OIDC/ code_challenge_methods_supported: ['S256', 'plain'] ``` + Auth0 example: + + ```yaml + auth0-server: + type: streamable-http + url: https://api.example.com/mcp/ + oauth: + audience: https://api.example.com + scope: 'read:data offline_access' + ``` + When `token_exchange_method` and `token_endpoint_auth_methods_supported` are both omitted for a preconfigured client secret, LibreChat allows up to five seconds for protected-resource and authorization-server metadata discovery. It uses advertised capabilities only when the discovered token endpoint exactly matches the configured `token_url`; discovery cannot redirect the configured client credentials to another endpoint. Set `token_exchange_method` explicitly when a provider does not publish usable metadata or needs a forced method. Server-side OAuth discovery, registration, token, and revocation HTTP requests do **not** follow redirects, even if the original URL is allowed. Configure the provider's final endpoint directly when it redirects. Private IP-literal destinations are blocked unless explicitly permitted by the administrator's trusted host or exact address-and-port policy. This restriction applies to server-side OAuth HTTP requests; it does not prevent the user's browser from completing the normal authorization-page redirect. @@ -643,6 +675,7 @@ Server-side OAuth discovery, registration, token, and revocation HTTP requests d - Adding authentication to dynamic client registration endpoints, such as `Authorization: Bearer ${DCR_API_KEY}` - Including custom provider-specific headers required for OAuth flows - Setting headers needed by OAuth token endpoints +- **Placeholder Support:** Values accept `{{LIBRECHAT_USER_*}}` placeholders and `${ENV_VAR}` references, as do the string fields under `oauth`. - **Key Differences from `headers`:** - **`headers`**: Sent with regular MCP server requests after authentication is complete - **`oauth_headers`**: Sent only during OAuth authentication flows @@ -661,7 +694,7 @@ Server-side OAuth discovery, registration, token, and revocation HTTP requests d - `on_use`: the turn starts without a prompt, and the agent finds the server's tools through tool search. The prompt appears when the agent first calls one of the server's tools, and the run waits for the user to sign in. - **Default Value:** `on_start` - **Notes:** - - `on_use` applies only when every tool the agent selected from the server is [deferred](/docs/features/agents#deferred-tools) ("Defer Loading" on). If any selected tool loads up front, or the agent selects the whole server rather than individual tools, the prompt stays at turn start. + - `on_use` applies only when every tool the agent selected from the server is [deferred](/docs/features/agents#deferred-tools) ("Defer" on). If any selected tool loads up front, or the agent selects the whole server rather than individual tools, the prompt stays at turn start. - The `deferred_tools` [agent capability](/docs/configuration/librechat_yaml/object_structure/agents#capabilities) must be enabled. When the `run_in_background` capability is enabled, a selected tool that opts into background execution keeps the prompt at turn start, since a detached call cannot wait for a sign-in. - `on_use` requires a declared [`oauthToolCatalog`](#oauthtoolcatalog). Without one, the server keeps the turn-start prompt, even for a user who has connected before. - The tools offered before sign-in must include every selected tool, or the prompt stays at turn start. That is the declared catalog, or the user's own tool list when an earlier connection left one. @@ -946,12 +979,12 @@ composio-googlesheets: initTimeout: 15000 ``` -**Related Environment Variables (Optional):** +**Related Environment Variables (Optional):** See [Environment Variables](/docs/configuration/dotenv) for all MCP settings. ```bash # OAuth configuration for MCP servers MCP_OAUTH_ON_AUTH_ERROR=true -MCP_OAUTH_DETECTION_TIMEOUT=10000 +MCP_OAUTH_DETECTION_TIMEOUT=5000 MCP_OAUTH_HANDLING_TIMEOUT=600000 MCP_OAUTH_FLOW_TTL=900000 diff --git a/content/docs/configuration/librechat_yaml/object_structure/mcp_settings.mdx b/content/docs/configuration/librechat_yaml/object_structure/mcp_settings.mdx index da823e629d..5724f43029 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/mcp_settings.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/mcp_settings.mdx @@ -45,10 +45,20 @@ mcpSettings: options={[ ['allowedDomains', 'Array of Strings', 'A list specifying allowed domains for MCP server connections.', 'When configured, only listed domains are allowed. When not configured, SSRF targets are blocked but all other domains are allowed.'], ['allowedAddresses', 'Array of Strings', 'An SSRF exemption list, scoped to private IP space. Hostname/IP + port pairs listed here bypass the default-deny SSRF block when `allowedDomains` is not configured.', 'Use when you want default SSRF protection AND specific internal MCP servers, without flipping `allowedDomains` into strict-whitelist mode.'], + ['apps', 'Boolean', 'Controls MCP Apps. When true, MCP Apps are enabled and MCP servers are connected with Apps support. When unset, only legacy HTML UI resources are rendered. When false, legacy HTML UI resources are disabled as well.', 'Apps render in a sandbox configured by mcpAppSandbox.'], ['catalogRecovery', 'Object', 'Optional bounds for passive MCP discovery, OAuth reauthentication recovery, and cross-replica authorization fencing.', 'Uses the defaults shown in the example.'], ]} /> +## apps + +`apps` turns on MCP Apps, the interactive interfaces that MCP servers return with tool results. The setting is read on the server and also reported to the client at startup. Apps render in a sandboxed frame whose host, size limits, and rate limits are set by the top-level [`mcpAppSandbox`](/docs/configuration/librechat_yaml/object_structure/mcp_app_sandbox) object. + +```yaml filename="mcpSettings / apps" +mcpSettings: + apps: true +``` + ## catalogRecovery `catalogRecovery` prevents passive catalog requests from repeatedly rediscovering disconnected OAuth servers and bounds the authorization-generation checks used across replicas. Most deployments should retain the defaults. @@ -156,7 +166,7 @@ mcpSettings: ## allowedAddresses -`allowedAddresses` is an **exemption list** for the SSRF private-IP block — not a domain whitelist. It is the right tool when you want to permit one or two specific private/internal services without restricting what your MCP servers can reach in the public internet. +`allowedAddresses` is an **exemption list** for the SSRF private-IP block, not a domain whitelist. It is the right tool when you want to permit one or two specific private/internal services without restricting what your MCP servers can reach in the public internet. ### When to use it instead of `allowedDomains` @@ -169,7 +179,7 @@ mcpSettings: allowedAddresses: - "host.docker.internal:8080" - "10.0.0.5:8000" - # allowedDomains is intentionally not set — public destinations + # allowedDomains is intentionally not set: public destinations # remain reachable, only listed private host:port services are exempted. ``` @@ -184,9 +194,9 @@ If `allowedDomains` is configured, it is authoritative: private services must be ### Rejected entries (validated at config load) - **URLs / paths / CIDR ranges**: `http://10.0.0.5`, `10.0.0.0/24`, `/path` -- **Bare hostnames or IPs**: `localhost`, `10.0.0.5`, `::1`, `[::1]` — every entry must include a port +- **Bare hostnames or IPs**: `localhost`, `10.0.0.5`, `::1`, `[::1]`: every entry must include a port - **Invalid ports**: `localhost:0`, `localhost:65536`, `localhost:http` -- **Public IP literals**: `8.8.8.8:53`, `1.1.1.1:53`, `[2001:4860::8888]:443` — the field is scoped to private IP space; public IPs are not SSRF targets and a public-IP exemption has no defensive purpose +- **Public IP literals**: `8.8.8.8:53`, `1.1.1.1:53`, `[2001:4860::8888]:443`: the field is scoped to private IP space; public IPs are not SSRF targets and a public-IP exemption has no defensive purpose ### Hostname trust diff --git a/content/docs/configuration/librechat_yaml/object_structure/memory.mdx b/content/docs/configuration/librechat_yaml/object_structure/memory.mdx index 3ca45f410f..a693b3a7f7 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/memory.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/memory.mdx @@ -43,6 +43,8 @@ memory: **Default:** `false` +Memory is only active when a `memory` block is present in `librechat.yaml`. Omitting the block leaves memory off. + ```yaml filename="memory / disabled" memory: disabled: true @@ -139,7 +141,7 @@ memory: [ 'personalize', 'Boolean', - 'When set to true, gives users the ability to opt in or out of using memory features. Users can toggle memory on/off in their chat interface. When false, memory features are completely disabled.', + 'When set to true, gives users the ability to opt in or out of using memory features. Users can toggle memory on/off in their chat interface. When false, only the user opt-out toggle is removed; memory stays on. To turn memory off, use disabled: true.', 'personalize: true', ], ]} @@ -361,7 +363,7 @@ memory: ## Notes - Memory functionality enhances conversation continuity and personalization -- When `personalize` is true, users get a toggle in their chat interface to control memory usage +- When `personalize` is true, users get a toggle in their chat interface to control memory usage. Setting it to `false` only removes that toggle; memory stays on. Use `disabled: true` to turn memory off - Token limits help control memory usage and processing costs - `maxInputTokens` bounds the chat context sent to the automatic memory agent, while `tokenLimit` controls stored memory usage - Valid keys provide granular control over what information can be stored diff --git a/content/docs/configuration/librechat_yaml/object_structure/message_filter.mdx b/content/docs/configuration/librechat_yaml/object_structure/message_filter.mdx index 472c1e84fd..e86bb10874 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/message_filter.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/message_filter.mdx @@ -48,15 +48,36 @@ filters: For each enabled source: -- Omit `action` or set it to `block` to reject matches. Set `action: audit` for a shadow rollout that records findings without rejecting, changing, or redacting content. +- Omit `action` or set it to `block` to reject matches. Set `action: audit` for a shadow rollout that records findings without rejecting, changing, or redacting content. Set `action: redact` to opt into redaction (see [Redaction](#redaction)). - Omit `fields` to inspect every supported field for that source. An explicit list must contain between 1 and 256 supported field names. - Omit `starterPatterns` to enable the full starter catalog. Set it to `[]` to disable starter patterns while retaining any `customPatterns`. -- Configure `customPatterns` with an `id`, user-facing `label`, and `regex`. +- Configure `customPatterns` with an `id`, user-facing `label`, and `regex`. Optionally set `category` to one of `email`, `phone`, `name`, `credential`, or `custom`. +- `maxCharacters` (1 to 262144, default 65536) bounds the total text inspected per transformation session, and `maxMatches` (1 to 4096, default 256) bounds the matches per session. Both apply to `redact`. -Audit mode evaluates all configured fragments and rules so operators can measure findings before enforcement. Each info-level audit record identifies the action, detector, rule, label, source, field, and provenance, but never includes the matched text or source content. Audit mode does not provide redaction; unsupported action values are rejected when the configuration loads. +Audit mode evaluates all configured fragments and rules so operators can measure findings before enforcement. Each info-level audit record identifies the action, detector, rule, label, source, field, and provenance, but never includes the matched text or source content. In `audit` mode nothing is changed or redacted. Action values other than `block`, `audit`, and `redact` are rejected when the configuration loads. Actions are configured independently per source, so one source can audit while another blocks. `filters.files.pii.uninspectable: block` remains an independent fail-closed rule for opaque or oversized selected file content, even when that source's pattern action is `audit`. +### Redaction + +`action: redact` transforms matches in fresh, text-only interactive Agent chat submissions that carry a `clientRequestId`. Edits, resumes, files, quotes, other endpoints, and other fields still use blocking checks. + +Redaction requires a valid `CREDS_KEY`. The original text is stored as an encrypted, unindexed field that is deleted or expires with the message, so keep the same `CREDS_KEY` to preserve owner recovery of originals; changing it makes existing originals unavailable. The message text remains canonical and filtered in ordinary exports. + +```yaml filename="librechat.yaml" +filters: + messages: + pii: + action: redact + maxCharacters: 65536 + maxMatches: 256 + customPatterns: + - id: organization_identifier + label: Organization identifier + regex: 'ORG-[A-Z0-9]{12}' + category: custom +``` + The built-in starter pattern IDs are: - `sk_prefix`: `sk-`-style token prefixes. diff --git a/content/docs/configuration/librechat_yaml/object_structure/meta.de.json b/content/docs/configuration/librechat_yaml/object_structure/meta.de.json index 41c95e41e5..98c07c2595 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/meta.de.json +++ b/content/docs/configuration/librechat_yaml/object_structure/meta.de.json @@ -25,6 +25,7 @@ "actions", "mcp_servers", "mcp_settings", + "mcp_app_sandbox", "skill_sync", "memory", "summarization", diff --git a/content/docs/configuration/librechat_yaml/object_structure/meta.es.json b/content/docs/configuration/librechat_yaml/object_structure/meta.es.json index 31ace4f1af..729ddcf109 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/meta.es.json +++ b/content/docs/configuration/librechat_yaml/object_structure/meta.es.json @@ -25,6 +25,7 @@ "actions", "mcp_servers", "mcp_settings", + "mcp_app_sandbox", "skill_sync", "memory", "summarization", diff --git a/content/docs/configuration/librechat_yaml/object_structure/meta.fr.json b/content/docs/configuration/librechat_yaml/object_structure/meta.fr.json index 10a1627c24..30aac5bd9a 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/meta.fr.json +++ b/content/docs/configuration/librechat_yaml/object_structure/meta.fr.json @@ -25,6 +25,7 @@ "actions", "mcp_servers", "mcp_settings", + "mcp_app_sandbox", "skill_sync", "memory", "summarization", diff --git a/content/docs/configuration/librechat_yaml/object_structure/meta.id.json b/content/docs/configuration/librechat_yaml/object_structure/meta.id.json index 8bf7c35473..2c7fde9072 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/meta.id.json +++ b/content/docs/configuration/librechat_yaml/object_structure/meta.id.json @@ -25,6 +25,7 @@ "actions", "mcp_servers", "mcp_settings", + "mcp_app_sandbox", "skill_sync", "memory", "summarization", diff --git a/content/docs/configuration/librechat_yaml/object_structure/meta.it.json b/content/docs/configuration/librechat_yaml/object_structure/meta.it.json index 4eb8402725..cc6d3b27e7 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/meta.it.json +++ b/content/docs/configuration/librechat_yaml/object_structure/meta.it.json @@ -25,6 +25,7 @@ "actions", "mcp_servers", "mcp_settings", + "mcp_app_sandbox", "skill_sync", "memory", "summarization", diff --git a/content/docs/configuration/librechat_yaml/object_structure/meta.ja.json b/content/docs/configuration/librechat_yaml/object_structure/meta.ja.json index 63ff236359..58838d4613 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/meta.ja.json +++ b/content/docs/configuration/librechat_yaml/object_structure/meta.ja.json @@ -25,6 +25,7 @@ "actions", "mcp_servers", "mcp_settings", + "mcp_app_sandbox", "skill_sync", "memory", "summarization", diff --git a/content/docs/configuration/librechat_yaml/object_structure/meta.json b/content/docs/configuration/librechat_yaml/object_structure/meta.json index bfbb6e919d..f4c8f916eb 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/meta.json +++ b/content/docs/configuration/librechat_yaml/object_structure/meta.json @@ -25,6 +25,7 @@ "actions", "mcp_servers", "mcp_settings", + "mcp_app_sandbox", "skill_sync", "memory", "summarization", diff --git a/content/docs/configuration/librechat_yaml/object_structure/meta.ko.json b/content/docs/configuration/librechat_yaml/object_structure/meta.ko.json index 2284df644f..eabb0bed9c 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/meta.ko.json +++ b/content/docs/configuration/librechat_yaml/object_structure/meta.ko.json @@ -25,6 +25,7 @@ "actions", "mcp_servers", "mcp_settings", + "mcp_app_sandbox", "skill_sync", "memory", "summarization", diff --git a/content/docs/configuration/librechat_yaml/object_structure/meta.nl.json b/content/docs/configuration/librechat_yaml/object_structure/meta.nl.json index 0bc58254e9..fcbcbc2d87 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/meta.nl.json +++ b/content/docs/configuration/librechat_yaml/object_structure/meta.nl.json @@ -25,6 +25,7 @@ "actions", "mcp_servers", "mcp_settings", + "mcp_app_sandbox", "skill_sync", "memory", "summarization", diff --git a/content/docs/configuration/librechat_yaml/object_structure/meta.pl.json b/content/docs/configuration/librechat_yaml/object_structure/meta.pl.json index 9365a990d4..a4df9f275c 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/meta.pl.json +++ b/content/docs/configuration/librechat_yaml/object_structure/meta.pl.json @@ -25,6 +25,7 @@ "actions", "mcp_servers", "mcp_settings", + "mcp_app_sandbox", "skill_sync", "memory", "summarization", diff --git a/content/docs/configuration/librechat_yaml/object_structure/meta.pt-BR.json b/content/docs/configuration/librechat_yaml/object_structure/meta.pt-BR.json index 394c8591ea..88b0e4fa90 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/meta.pt-BR.json +++ b/content/docs/configuration/librechat_yaml/object_structure/meta.pt-BR.json @@ -25,6 +25,7 @@ "actions", "mcp_servers", "mcp_settings", + "mcp_app_sandbox", "skill_sync", "memory", "summarization", diff --git a/content/docs/configuration/librechat_yaml/object_structure/meta.tr.json b/content/docs/configuration/librechat_yaml/object_structure/meta.tr.json index aa23d6292b..326747df1c 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/meta.tr.json +++ b/content/docs/configuration/librechat_yaml/object_structure/meta.tr.json @@ -25,6 +25,7 @@ "actions", "mcp_servers", "mcp_settings", + "mcp_app_sandbox", "skill_sync", "memory", "summarization", diff --git a/content/docs/configuration/librechat_yaml/object_structure/meta.vi.json b/content/docs/configuration/librechat_yaml/object_structure/meta.vi.json index a8612ba1e6..de4aabebaf 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/meta.vi.json +++ b/content/docs/configuration/librechat_yaml/object_structure/meta.vi.json @@ -25,6 +25,7 @@ "actions", "mcp_servers", "mcp_settings", + "mcp_app_sandbox", "skill_sync", "memory", "summarization", diff --git a/content/docs/configuration/librechat_yaml/object_structure/meta.zh.json b/content/docs/configuration/librechat_yaml/object_structure/meta.zh.json index 03dcd4e85a..c1fed301d4 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/meta.zh.json +++ b/content/docs/configuration/librechat_yaml/object_structure/meta.zh.json @@ -25,6 +25,7 @@ "actions", "mcp_servers", "mcp_settings", + "mcp_app_sandbox", "skill_sync", "memory", "summarization", diff --git a/content/docs/configuration/librechat_yaml/object_structure/ocr.mdx b/content/docs/configuration/librechat_yaml/object_structure/ocr.mdx index d73cc51e4e..1e3451240d 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/ocr.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/ocr.mdx @@ -160,8 +160,6 @@ ocr: ]} /> -## allowedAddresses - OCR requests block private, loopback, link-local, and cloud-metadata destinations at connect time and disable redirects. `allowedAddresses` is an exemption list for exact trusted private `host:port`, `private.ip:port`, or `[ipv6]:port` targets; it does not restrict access to public destinations. diff --git a/content/docs/configuration/librechat_yaml/object_structure/registration.mdx b/content/docs/configuration/librechat_yaml/object_structure/registration.mdx index 037ce856b3..41b93567bc 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/registration.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/registration.mdx @@ -12,6 +12,10 @@ registration: allowedDomains: - "gmail.com" - "protonmail.com" + oauthStateTtlMs: 600000 + openidDiscovery: + startupAttempts: 1 + retryDelayMs: 5000 ``` ## socialLogins @@ -38,11 +42,44 @@ socialLogins: ["google", "facebook", "github", "discord", "openid"] ]} /> -**Required** +This key is optional. If you omit it, registration is allowed for any email domain. **Example:** ```yaml filename="registration / allowedDomains" allowedDomains: - "gmail.com" - "protonmail.com" -``` \ No newline at end of file +``` + +## oauthStateTtlMs + +**Key:** + + +**Example:** +```yaml filename="registration / oauthStateTtlMs" +oauthStateTtlMs: 900000 +``` + +## openidDiscovery + +Controls how LibreChat retries OpenID Connect discovery against your identity provider. Each field set here takes precedence over the matching environment variable (`OPENID_DISCOVERY_RETRY_ATTEMPTS`, `OPENID_DISCOVERY_RETRY_DELAY_MS`); fields you leave unset fall back to the environment variable, then to the default. + +**Keys:** + + +**Example:** +```yaml filename="registration / openidDiscovery" +openidDiscovery: + startupAttempts: 3 + retryDelayMs: 10000 +``` diff --git a/content/docs/configuration/librechat_yaml/object_structure/skill_sync.mdx b/content/docs/configuration/librechat_yaml/object_structure/skill_sync.mdx index be9e4acbe4..42629d26d1 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/skill_sync.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/skill_sync.mdx @@ -5,7 +5,7 @@ icon: RefreshCw ## Overview -The `skillSync` object lets admins mirror Skills from external sources. In v1.3.13, GitHub is the supported provider. +The `skillSync` object lets admins mirror Skills from external sources. GitHub is the supported provider. GitHub Skill Sync reads `SKILL.md` files and their bundled files from configured repository paths, stores them as Skills with `source: "github"`, and keeps mirrored rows aligned with the upstream repository on later syncs. @@ -58,7 +58,7 @@ skillSync: [ 'github.sources', 'Array of Objects', - 'GitHub repositories and paths to scan for Skills. Required when GitHub Skill Sync is enabled.', + 'GitHub repositories and paths to scan for Skills. Enabling GitHub Skill Sync with no sources is rejected, and each source id must be unique.', '', ], ]} @@ -95,7 +95,7 @@ Each `github.sources` entry configures one repository source. [ 'skillDiscoveryDepth', 'Number', - 'Directory depth below each configured path to scan for `SKILL.md`. Defaults to `2`; maximum is `10`.', + 'Directory depth below each configured path to scan for SKILL.md. Defaults to 2; minimum is 0 and maximum is 10.', 'skillDiscoveryDepth: 2', ], [ @@ -175,3 +175,51 @@ The admin API exposes GitHub Skill Sync status, manual runs, and stored credenti /> Status reads require admin access and Skills read permission. Manual runs and credential writes require platform-level Skills management permission. + +## Skill Deletion + +The top-level `skillDeletion` object controls the background process that finishes deleting Skills and cleans up their stored files, along with abandoned Skill uploads. It is separate from `skillSync` and applies to all Skills. Unknown keys are rejected. + +```yaml filename="librechat.yaml" +skillDeletion: + finalizationEnabled: true + sweepIntervalMs: 60000 + claimLeaseMs: 120000 + batchSize: 100 + recheckIntervalMs: 3600000 +``` + + diff --git a/content/docs/configuration/librechat_yaml/object_structure/speech.mdx b/content/docs/configuration/librechat_yaml/object_structure/speech.mdx index 6235bbae85..0d9321a65d 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/speech.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/speech.mdx @@ -15,8 +15,7 @@ The `speech` object allows you to configure Text-to-Speech (TTS) and Speech-to-T **Notes:** -- Multiple providers can be configured simultaneously -- Users can select their preferred provider from the available options +- Configure exactly one provider under `tts` and exactly one under `stt`. If more than one is set, requests fail with "Multiple providers are set. Please set only one provider." - API keys in the config file should use environment variable references for security ## Example @@ -29,10 +28,6 @@ speech: apiKey: "${TTS_API_KEY}" model: "tts-1" voices: ["alloy", "echo", "fable", "onyx", "nova", "shimmer"] - elevenlabs: - apiKey: "${ELEVENLABS_API_KEY}" - model: "eleven_multilingual_v2" - voices: ["voice-id-1", "voice-id-2"] stt: allowedAddresses: ["stt.internal:8080"] openai: @@ -61,7 +56,7 @@ When a forward proxy carries a hostname request, the proxy performs destination ## tts -The `tts` object configures Text-to-Speech providers. Multiple providers can be configured, and users can choose which one to use. +The `tts` object configures the Text-to-Speech provider. Set exactly one provider (`openai`, `azureOpenAI`, `elevenlabs`, or `localai`); setting more than one is an error. @@ -188,7 +189,7 @@ tts: ## stt -The `stt` object configures Speech-to-Text providers. +The `stt` object configures the Speech-to-Text provider. Set exactly one provider (`openai` or `azureOpenAI`); setting more than one is an error. @@ -319,6 +320,11 @@ speechTab: ## Complete Example +Only one TTS provider can be active at a time. The tabs show the same configuration with each supported provider. + + + + ```yaml filename="librechat.yaml" version: 1.3.18 cache: true @@ -329,6 +335,29 @@ speech: apiKey: "${TTS_API_KEY}" model: "tts-1-hd" voices: ["alloy", "echo", "fable", "onyx", "nova", "shimmer"] + stt: + openai: + apiKey: "${STT_API_KEY}" + model: "whisper-1" + speechTab: + conversationMode: false + advancedMode: false + speechToText: true + textToSpeech: + engineTTS: "external" + voice: "nova" + automaticPlayback: false +``` + + + + +```yaml filename="librechat.yaml" +version: 1.3.18 +cache: true + +speech: + tts: elevenlabs: apiKey: "${ELEVENLABS_API_KEY}" model: "eleven_multilingual_v2" @@ -346,16 +375,19 @@ speech: speechToText: true textToSpeech: engineTTS: "external" - voice: "nova" + voice: "21m00Tcm4TlvDq8ikWAM" automaticPlayback: false ``` + + + --- ## Notes - Always use environment variable references (e.g., `${API_KEY}`) for API keys in configuration files -- Multiple TTS providers can be configured; users select their preferred option in the UI +- Only one provider can be configured for TTS and one for STT; users choose between `browser` and `external` in the UI - The `speechTab` settings define defaults that users can override in their personal settings - `browser` uses the browser's built-in speech support; `external` uses the server-side providers configured under `speech.stt` or `speech.tts` - Existing `openai` and `azureOpenAI` STT defaults, and `openai`, `azureOpenAI`, `elevenlabs`, and `localai` TTS defaults, are migrated to `external`; an unavailable external engine falls back to `browser` diff --git a/content/docs/configuration/librechat_yaml/object_structure/web_search.mdx b/content/docs/configuration/librechat_yaml/object_structure/web_search.mdx index c6114f53c3..28396127b2 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/web_search.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/web_search.mdx @@ -259,7 +259,7 @@ Adding more engines widens coverage but also slows every search down, since Sear ['includeRawContent', 'Boolean or String', 'Include cleaned and parsed HTML content. "markdown" or true for markdown format, "text" for plain text.', 'Default: false'], ['includeDomains', 'Array of Strings', 'Restrict search to specific domains. Maximum 300 domains.', ''], ['excludeDomains', 'Array of Strings', 'Exclude specific domains from results. Maximum 150 domains.', ''], - ['timeRange', 'String', 'Time range filter based on publish or last updated date.', 'Options: "day", "week", "month", "year"'], + ['timeRange', 'String', 'Time range filter based on publish or last updated date.', 'Options: "day", "week", "month", "year", or the short forms "d", "w", "m", "y"'], ['includeImageDescriptions', 'Boolean', 'When includeImages is true, also add a descriptive text for each image.', 'Default: false'], ['includeFavicon', 'Boolean', 'Include the favicon URL for each search result.', 'Default: false'], ['chunksPerSource', 'Number', 'Maximum number of relevant content chunks per source. Only available when searchDepth is "advanced".', 'Range: 1-3. Default: 3'], @@ -615,7 +615,7 @@ webSearch: @@ -625,7 +625,7 @@ webSearch: @@ -650,7 +650,7 @@ webSearch: - Tavily does not inherit the global safe search setting by default; set `tavilySearchOptions.safeSearch` explicitly only when your Tavily account supports `safe_search` - Keenable supports keyless search and page fetch; its optional key raises public rate limits, and its fetch URL override is environment-only - SearXNG query behavior (engines, language, time range, request timeout) is configured under `searxngSearchOptions`; see [Choosing engines](#choosing-engines) if searches come back empty -- Never put actual API keys in the YAML configuration - only use environment variable names +- Prefer `${ENV_VAR}` references for API keys and URLs. A literal value written in `librechat.yaml` is accepted and used as a system credential, but a literal API key is sent only to a URL set alongside it in the same configuration. An environment key or a user's own saved key is never sent to a URL written in the configuration, so reference both the key and its URL from the environment, or set both together. Keys saved through the admin configuration API are encrypted at rest, and the API asks for the key again when a write changes or removes the URL beside it. ## Setting Up SearXNG From 31658b6aec41bdc520ac324eb649a0303d02d802 Mon Sep 17 00:00:00 2001 From: Marco Beretta <81851188+berry-13@users.noreply.github.com> Date: Fri, 23 Oct 2026 22:10:16 +0200 Subject: [PATCH 2/2] docs: Explain how to host the MCP App sandbox The sandbox url is the frame source itself, so it has to name the /api/mcp/sandbox route on the dedicated origin, and the page is only embeddable once MCP_SANDBOX_FRAME_ANCESTORS lists the LibreChat origin. --- .../object_structure/mcp_app_sandbox.mdx | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/content/docs/configuration/librechat_yaml/object_structure/mcp_app_sandbox.mdx b/content/docs/configuration/librechat_yaml/object_structure/mcp_app_sandbox.mdx index 3e216c2146..da4bd2898d 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/mcp_app_sandbox.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/mcp_app_sandbox.mdx @@ -14,7 +14,7 @@ MCP Apps are turned on with [`mcpSettings.apps`](/docs/configuration/librechat_y ```yaml filename="mcpAppSandbox" mcpAppSandbox: - url: https://sandbox.example.com/ + url: https://mcp-sandbox.example.com/api/mcp/sandbox maxActiveViews: 3 maxPersistedAppBytes: 1048576 maxAdmissionRequestsPerMinute: 240 @@ -24,6 +24,12 @@ mcpAppSandbox: 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`](/docs/configuration/dotenv#mcp-server-configuration) 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