Config Structure

Note: Fields not specifically mentioned as required are optional.

version

• required

cache

fileStrategy

• Options: "local" | "firebase" | "s3" | "azure_blob"

• Notes:
  • "firebase" is currently the only option that serves files through a true CDN (Content Delivery Network), which means images and avatars are delivered from edge locations globally. S3 and Azure Blob Storage are object storage backends — files are accessible but not CDN-served by default.
  • S3 serves files via presigned URLs (temporary signed tokens) that expire. Once expired, any image or avatar referencing that URL will appear broken in the UI. This makes S3 unsuitable as a primary strategy for visual assets. See the related discussion for details.
  • CloudFront (CDN for S3) is planned and in active development.
  • For best performance of images and avatars, use "firebase" or configure fileStrategies to route avatar and image to a CDN-backed strategy.
  • Please refer to the File Storage & CDN documentation for setup details

fileStrategies

Allows granular control over file storage strategies for different file types.

• Available Strategies: "local" | "firebase" | "s3" | "azure_blob"

Sub-keys:

• Notes:
  • This setting takes precedence over the single fileStrategy option
  • If a specific file type is not configured, it falls back to default, then to fileStrategy, and finally to "local"
  • Images and avatars need persistent, stable URLs to render correctly across the UI. S3 presigned URLs expire (AWS cap: 7 days for IAM users, hours for STS/role-based credentials), causing broken images in the model selector and chat UI. See the related discussion for full context. Use "firebase" (the only current CDN-backed strategy) for avatar and image to avoid this.
  • CloudFront support for S3 is in active development and will eliminate presigned URL limitations.
  • S3 and Azure Blob Storage are well-suited for document storage, where short-lived presigned download URLs are appropriate.
  • Please refer to the File Storage & CDN documentation for setup details for each storage provider

Examples:

# Use a single strategy for all file types
fileStrategies:
  default: "s3"

# Route images and avatars to CDN, keep documents in object storage
fileStrategies:
  avatar: "firebase"   # CDN delivery for avatars
  image: "firebase"    # CDN delivery for generated/uploaded images
  document: "s3"       # Object storage for documents

# Only configure specific types, others use default
fileStrategies:
  default: "local"
  avatar: "firebase"   # Only avatars use Firebase CDN, everything else is local

filteredTools

• 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
    • 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

• 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
    • 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

imageOutputType

• Note: Case-sensitive. Google endpoint only supports "jpeg" and "png" output types.
• Options: "png" | "webp" | "jpeg"

ocr

Key:

Subkeys:

see: OCR Config Object Structure

webSearch

Key:

Subkeys:

see: Web Search Object Structure

fileConfig

Key:

Subkeys:

clientImageResize

Key:

Subkeys:

Description:

The clientImageResize configuration enables automatic client-side image resizing before upload. This feature helps:

• Prevent upload failures due to large image files exceeding server limits
• Reduce bandwidth usage by compressing images before transmission
• Improve upload performance with smaller file sizes
• Maintain image quality while optimizing file size

When enabled, images that exceed the specified maxWidth or maxHeight dimensions are automatically resized on the client side before being uploaded to the server. The resizing maintains the original aspect ratio while ensuring the image fits within the specified bounds.

Example:

fileConfig:
  clientImageResize:
    enabled: true
    maxWidth: 1920
    maxHeight: 1080
    quality: 0.8
    compressFormat: "jpeg"

Notes:

• Only applies to image files (JPEG, PNG, WebP, etc.)
• Resizing occurs automatically when images exceed the specified dimensions
• Original aspect ratio is preserved during resizing
• The feature works with all supported image upload endpoints
• Quality setting only applies to JPEG and WebP formats
• Setting quality too low (< 0.5) may result in noticeable image degradation

see: File Config Object Structure

rateLimits

Key:

Subkeys:

fileUploads Subkeys:

conversationsImport Subkeys:

tts Subkeys:

stt Subkeys:

• Example:

rateLimits:
  fileUploads:
    ipMax: 100
    ipWindowInMinutes: 60
    userMax: 50
    userWindowInMinutes: 60
  conversationsImport:
    ipMax: 100
    ipWindowInMinutes: 60
    userMax: 50
    userWindowInMinutes: 60
  stt:
    ipMax: 100
    ipWindowInMinutes: 1
    userMax: 50
    userWindowInMinutes: 1
  tts:
    ipMax: 100
    ipWindowInMinutes: 1
    userMax: 50
    userWindowInMinutes: 1

registration

Key:

Subkeys:

see also:

• socialLogins,
• alloweddomains,
• Registration Object Structure

memory

Key:

Subkeys:

see: Memory Object Structure

actions

Key:

Subkeys:

see also:

• alloweddomains,
• Actions Object Structure

interface

Key:

Subkeys:

see: Interface Object Structure

modelSpecs

Key:

Subkeys:

see: Model Specs Object Structure

endpoints

Key:

Subkeys:

Note: All endpoints support Shared Endpoint Settings which include streamRate, titleModel, titleMethod, titlePrompt, titlePromptTemplate, and titleEndpoint. These can be configured individually per endpoint or globally using the all key.

mcpSettings

Key:

Subkeys:

• Notes:
  • This is a security feature to protect against abuse / misuse of internal addresses via MCP servers
  • By default, LibreChat restricts MCP servers from connecting to internal, local, or private network addresses
  • MCP servers using local IP addresses or domains must be explicitly allowed
  • As with all yaml configuration changes, a LibreChat restart is required to take effect
  • Supports domains, wildcard subdomains (*.example.com), docker domains, and IP addresses

Example:

mcpSettings:
  allowedDomains:
    - "example.com"           # Specific domain
    - "*.example.com"         # All subdomains
    - "mcp-server"            # Local Docker domain
    - "172.24.1.165"          # Internal network IP

see: MCP Settings Object Structure

mcpServers

Key:

Subkeys:

• Notes:
  • Initialization happens at startup, and the app must be restarted for changes to take effect.
  • The <serverName> is a unique identifier for each MCP server configuration.
  • Each MCP server can be configured using one of four connection types:
    • stdio
    • websocket
    • sse
    • streamable-http
  • 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.
    • If url is specified and starts with ws or wss, type defaults to websocket.
    • If command is specified, type defaults to stdio.
  • Additional configuration options include:
    • timeout: Timeout in milliseconds for MCP server requests. Determines how long to wait for a response for tool requests.
    • initTimeout: Timeout in milliseconds for MCP server initialization. Determines how long to wait for the server to initialize.
    • serverInstructions: Controls whether server instructions are included in agent context. Can be true (use server-provided), false (disabled), or a custom string (overrides server-provided).
    • customUserVars: (Optional) Defines custom variables (e.g., API keys, URLs) that individual users can set for an MCP server. These per-user values, provided through the UI, can then be referenced in the server's headers or env configurations using {{VARIABLE_NAME}} syntax. This allows for per-user authentication or customization for MCP tools.
  • see: MCP Servers Object Structure

Example:

mcpServers:
  everything:
    # type: sse # type can optionally be omitted
    url: http://localhost:3001/sse
    timeout: 30000
    initTimeout: 10000
    serverInstructions: true  # Use server-provided instructions
  puppeteer:
    type: stdio
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-puppeteer"
    timeout: 30000
    initTimeout: 10000
    serverInstructions: "Do not access any local files or local/internal IP addresses"
  filesystem:
    # type: stdio
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-filesystem"
      - /home/user/LibreChat/
    iconPath: /home/user/LibreChat/client/public/assets/logo.svg
  mcp-obsidian:
    command: npx
    args:
      - -y
      - "mcp-obsidian"
      - /path/to/obsidian/vault
  streamable-http-example:
    type: streamable-http
    url: https://example.com/mcp
    headers:
      Authorization: "Bearer ${API_TOKEN}"
    timeout: 30000
  per-user-crendentials-example:
    type: sse
    url: "https//some.mcp/sse"
    headers:
      X-Custom-Auth-Token: "{{USER_API_KEY}}" # Placeholder for the user-provided API key, defined in `customUserVars` below.
    customUserVars:
      USER_API_KEY:
        title: "Service API Key"
        description: "Your personal API key for this service. You can get it <a href='https://example.com/api-keys' target='_blank'>here</a>."
    serverInstructions: true

see: MCP Servers Object Structure

speech

Key:

Subkeys:

see: Speech Object Structure

turnstile

Key:

Subkeys:

see: Turnstile Object Structure

transactions

Key:

Subkeys:

see: Transactions Object Structure

Additional links

• AWS Bedrock Object Structure
• Custom Endpoint Object Structure
• Azure OpenAI Endpoint Object Structure
• Assistants Endpoint Object Structure
• Agents
• OCR Config Object Structure
• Speech Object Structure
• Turnstile Object Structure
• Transactions Object Structure
• Balance Object Structure
• Web Search Object Structure
• Memory Object Structure