MCP Servers Object Structure

Example

# Example MCP Servers Object Structure
mcpServers:
  everything:
    # type: sse # type can optionally be omitted
    url: http://localhost:3001/sse
  googlesheets:
    type: sse
    url: https://mcp.composio.dev/googlesheets/some-endpoint
    requiresOAuth: true
    headers:
      X-User-ID: '{{LIBRECHAT_USER_ID}}'
      X-API-Key: '${SOME_API_KEY}'
    serverInstructions: true # Use server-provided instructions
  puppeteer:
    type: stdio
    command: npx
    args:
      - -y
      - '@modelcontextprotocol/server-puppeteer'
    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
    # The “wrench” icon shows up if no icon is provided as it is the default rendering.
  mcp-obsidian:
    command: npx
    args:
      - -y
      - 'mcp-obsidian'
      - /path/to/obsidian/vault
  streamable-http-server:
    type: streamable-http
    url: https://example.com/api/
    proxy: '${MCP_PROXY_URL}'
  per-user-credentials-example:
    type: streamable-http
    url: 'https://example.com/api/'
    headers:
      X-Auth-Token: '{{MY_SERVICE_API_KEY}}'
    customUserVars:
      MY_SERVICE_API_KEY:
        title: 'My Service API Key'
        description: "Enter your personal API key for the service. You can generate one at <a href='https://myservice.example.com/developer/keys' target='_blank'>Service Developer Portal</a>."
        sensitive: true
      MY_SERVICE_PROJECT:
        title: 'Project ID'
        description: 'Enter the project ID used by this service.'
        sensitive: false
  oauth-example:
    type: streamable-http
    url: https://api.example.com/mcp/
    oauth:
      authorization_url: https://example.com/oauth/authorize
      token_url: https://example.com/oauth/token
      client_id: your_client_id
      client_secret: your_client_secret
      redirect_uri: http://localhost:3080/api/mcp/oauth-example/oauth/callback
      scope: 'read execute'
  obo-example:
    type: streamable-http
    url: https://api.example.com/mcp/
    obo:
      scopes: 'api://mcp-server-id/Mcp.Tools.ReadWrite'

<serverName>

Key:

Subkeys

title

• Type: String (Optional)
• Description: Custom display name for the MCP server in the UI. If not specified, the server key name is used.
• Validation: Must start with a Unicode letter or number. The remaining characters may include Unicode letters, numbers, combining marks, spaces, hyphens, and straight or curly apostrophes.
• Example:

  my-server:
    title: 'File System Access'
    command: npx
    args: ['-y', '@modelcontextprotocol/server-filesystem']

description

• Type: String (Optional)
• Description: Description of the MCP server, displayed in the UI to help users understand its purpose and capabilities.
• Example:

  my-server:
    title: 'File System Access'
    description: 'Provides read/write access to local files and directories'
    command: npx
    args: ['-y', '@modelcontextprotocol/server-filesystem']

type

• Type: String
• 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

• Type: String
• Description: (For stdio type) The command or executable to run to start the MCP server.

args

• Type: Array of Strings
• 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

• Type: String
• Description: (For websocket, streamable-http, or sse type) The URL to connect to the MCP server. Supports dynamic user field placeholders ({{LIBRECHAT_USER_*}}) and environment variable substitution (${ENV_VAR}).
• Notes:
  • For sse type, the URL must start with http:// or https://.
  • For streamable-http type, the URL must start with http:// or https://.
  • For websocket type, the URL must start with ws:// or wss://.

proxy

• Type: String (Optional, for sse and streamable-http types)
• Description: Outbound proxy URL for this remote MCP server. The value can reference environment variables with ${ENV_VAR}.
• Supported protocols: http://, https://, socks://, and socks5://
• Security note: proxy is admin-controlled. It resolves environment variables, but does not resolve user-controlled placeholders such as {{LIBRECHAT_USER_ID}} or customUserVars.
• Example:

  mcpServers:
    remote-api:
      type: streamable-http
      url: https://api.example.com/mcp
      proxy: '${MCP_PROXY_URL}'

headers

• Type: Object (Optional, for sse and streamable-http types)
• Description: Custom headers to send with the request. Supports various placeholder types for dynamic value substitution.
• Placeholder Support:
  • {{LIBRECHAT_USER_ID}}: Will be replaced with the current user's ID, enabling multi-user support.
  • {{LIBRECHAT_USER_*}}: Dynamic user field placeholders. Replace * with the UPPERCASE version of any allowed field.
  • {{LIBRECHAT_OPENID_*}}: OpenID token/session placeholders for YAML-defined servers.
  • {{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.

Available User Field Placeholders:

Note: Missing fields will be replaced with empty strings.

{{LIBRECHAT_BODY_*}} placeholders are request-scoped. LibreChat creates the MCP connection for the active run, reuses it across tool calls in that run, and cleans it up when the request ends. Request-scoped servers are excluded from the persistent tool cache so request-specific headers and URLs are not reused outside the active run. Agent Builder attaches the complete server through one runtime-tools selection and resolves its tools after a run supplies body values. Completing OAuth stores authorization but defers the connection until that request context exists. {{LIBRECHAT_USER_*}}, {{LIBRECHAT_OPENID_*}}, and {{LIBRECHAT_GRAPH_*}} placeholders still make the server user-scoped, but HTTP transports refresh resolved headers before each tool call without forcing a reconnect by themselves.

{{LIBRECHAT_BODY_PARENTMESSAGEID}} receives the root-turn parent message in native Agent chats, OpenAI-compatible Agents API requests, and legacy Assistants runs. Open Responses requests have no compatible parent-message model, so a server that requires this placeholder fails closed on that interface; previous_response_id is not substituted for it.

OpenID access and ID tokens expire independently. {{LIBRECHAT_OPENID_ACCESS_TOKEN}} and the legacy {{LIBRECHAT_OPENID_TOKEN}} use the stored access-token expiry, while {{LIBRECHAT_OPENID_ID_TOKEN}} requires a current ID token. If a credential token is unavailable or expired, LibreChat returns an actionable 401 re-authentication error instead of sending an empty or literal bearer value; sign in again before retrying. For a request with no OpenID identity, a header containing one of those unresolved credential placeholders is omitted entirely. Identity metadata placeholders keep their existing empty-value behavior.

Trusted operators can pass the signed-in user's live OpenID access token directly to a YAML-defined remote MCP server:

mcpServers:
  trusted-api:
    type: streamable-http
    url: https://mcp.example.com/mcp
    headers:
      Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}'

Use direct passthrough only when the MCP server is trusted to receive the user's upstream access token. Explicit MCP OAuth, on-behalf-of exchange, and administrator API-key authentication take precedence over this header. LibreChat resolves the live session token before connecting and refreshes the connection once after a 401 or 403. It does not automatically replay the rejected tool call because the server may already have executed it; retry the tool deliberately after recovery succeeds. If the token cannot be refreshed, the user must sign in again.

{{LIBRECHAT_GRAPH_ACCESS_TOKEN}} exchanges the user's reusable OpenID access token for a Microsoft Graph token through the on-behalf-of flow. The requested scopes come from GRAPH_API_SCOPES, which defaults to https://graph.microsoft.com/.default and is separate from OPENID_GRAPH_SCOPES (people and group search).

• Example:

  headers:
    X-User-ID: '{{LIBRECHAT_USER_ID}}'
    X-User-Email: '{{LIBRECHAT_USER_EMAIL}}'
    X-User-Role: '{{LIBRECHAT_USER_ROLE}}'
    X-API-Key: '${SOME_API_KEY}'
    Authorization: 'Bearer ${SOME_AUTH_TOKEN}'

requestHeaders

• Type: Object (Optional, for sse and streamable-http types)
• Description: Headers resolved only for an active chat request. They use the same placeholders as headers, are merged over headers, and win when both objects define the same name.
• Discovery behavior: Tool discovery omits requestHeaders entirely, so request-only values such as {{LIBRECHAT_BODY_*}} do not hide the server's tool catalog. The active run resolves and sends them when it connects.

requestHeaders:
  X-Conversation-ID: '{{LIBRECHAT_BODY_CONVERSATIONID}}'
  X-Schedule-ID: '{{LIBRECHAT_BODY_SCHEDULEID}}'

apiKey

• 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 (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
  • 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 <key>
    • "basic": Sent as Authorization: Basic <key>
    • "custom": Sent in a custom header (requires custom_header)
  • 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:

  # Admin-provided API key with Bearer auth
  my-server:
    type: streamable-http
    url: https://api.example.com/mcp
    apiKey:
      source: 'admin'
      key: '${MY_SERVER_API_KEY}'
      authorization_type: 'bearer'
  
  # User-provided API key with custom header
  another-server:
    type: sse
    url: https://api.example.com/sse
    apiKey:
      source: 'user'
      authorization_type: 'custom'
      custom_header: 'X-API-Key'

For UI-created, shared servers using apiKey.source: user, saved keys are bound to the normalized request destination. Changing the URL path or query, proxy, transport, authorization format/header, or configured OAuth client/destination requires users to enter new keys; equivalent or cosmetic edits preserve them. Existing legacy keys keep working on their unchanged boundary. Only currently declared credential variables can be substituted, including in requestHeaders; an injected old generated name cannot reuse its key. Complete the upgrade on every API replica, including configuration writers. See Create a server from the UI for what users see.

iconPath

• Type: String (Optional)
• Description: Defines the tool's display icon shown in the tool selection dialog.

chatMenu

• Type: Boolean (Optional)
• Description: When set to false, the server is left out of the MCP Servers section of the chat composer, and chat requests that name it are rejected. Agents can still use the server, as can a model spec that lists it.
• Default Value: true
• Example:

  mcpServers:
    internal-tools:
      command: npx
      args: ['-y', 'internal-mcp-server']
      chatMenu: false # only available in the Agent Builder

serverInstructions

• Type: Boolean or String (Optional)

• Description: Controls how MCP server instructions are injected into agent context. Server instructions provide high-level usage guidance for the entire MCP server, complementing individual tool descriptions.

• Options:

  • undefined (default): No instructions are included
  • true: Use server-provided instructions (if available) - ideal for well-documented servers with comprehensive guidance
  • false: Explicitly disable instructions - useful for saving context tokens or when tools are self-explanatory
  • string: Use custom instructions (overrides server-provided) - best for application-specific workflows or when server instructions are insufficient

• Default Value: undefined (no instructions included)

• Notes:

  • Instructions are automatically injected when serverInstructions is configured and the server's tools are available to the agent
  • Multiple servers can each contribute instructions to the agent context
  • LibreChat stores server-advertised text separately from the configured declaration. Inspection does not replace true or an operator-authored string, and Redis-backed registry entries from earlier builds are refreshed automatically during initialization.

• Example:

  # Use server-provided instructions
  serverInstructions: true
  
  # Use custom instructions
  serverInstructions: |
    When using this filesystem server:
    1. Always use absolute paths for file operations
    2. Check file permissions before attempting write operations
  
  # Explicitly disable instructions
  serverInstructions: false

env

• Type: Object (Optional, stdio type only)
• Description: Environment variables to use when spawning the process.
• Placeholder Support:
  • {{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.

timeout

• Type: Integer (Optional)
• Description: Timeout in milliseconds for MCP server requests, including tool calls. Must be a non-negative integer.
• Default Value: 60000 (60 seconds)
• Note: If long tool calls still get cut off, check the timeouts on any reverse proxy in front of LibreChat or the MCP server (nginx, Traefik, and so on).
• Example:

  mcpServers:
    data-processor:
      type: streamable-http
      url: https://api.example.com/mcp
      initTimeout: 15000 # 15 seconds to connect
      timeout: 60000 # 60 seconds per tool call

initTimeout

• Type: Integer (Optional)
• Description: Timeout in milliseconds for MCP server initialization. Must be a non-negative integer. It does not limit how long a user has to finish an OAuth sign-in; that is MCP_OAUTH_HANDLING_TIMEOUT (see OAuth callback URL).
• Default Value: 30000 (30 seconds)

requiresOAuth

• Type: Boolean (Optional, remote transports only: sse, streamable-http, websocket)
• Description: 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.
• Default Value: Auto-detected if not specified
• Notes:
  • Applicable to remote (URL-based) transports: sse, streamable-http, and websocket. It has no effect on stdio servers, which have no URL to authenticate against.
  • Auto-detection occurs during server startup, which may add initialization time
  • Explicit configuration improves startup performance by skipping detection
  • Set requiresOAuth: false for servers protected only by a static Authorization header (e.g. a Bearer API key). Auto-detection probes the server without your configured headers, so a server that answers 401 with a WWW-Authenticate: Bearer challenge can be misclassified as OAuth-protected; this flag bypasses that probe and lets your static header authenticate the connection normally.
  • Works with MCP OAuth environment variables (MCP_OAUTH_ON_AUTH_ERROR, MCP_OAUTH_DETECTION_TIMEOUT, MCP_OAUTH_HANDLING_TIMEOUT, MCP_OAUTH_FLOW_TTL) for enhanced connection management

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

stderr

• Type: String or Integer (Optional, stdio type only)
• Description: How to handle stderr of the child process. This matches the semantics of Node's child_process.spawn. Valid string values: "pipe", "ignore", "inherit". Alternatively, a non-negative integer can be used as a file descriptor.
• Default Value: "inherit" (messages to stderr will be printed to the parent process's stderr).

customUserVars

• Type: Object (Optional)
• Description: Defines custom variables that users can set for this MCP server. This allows administrators to specify variables (e.g., API keys, URLs) that each user must configure individually. These user-provided values can then be used in headers or env configuration. Servers with customUserVars are automatically excluded from app-level connections, ensuring per-user credentials are always resolved at runtime.
• Structure:
  • 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 (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: <a href="https://example.com" target="_blank">More info</a>).
    • 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.
  • Users enter these values when they first connect to the server, and can change them later with Configure in the chat composer or in MCP Settings. See Credentials and variables.
  • These user-provided values are stored per user and per MCP server, and substituted at runtime.
  • If the variables are not available when LibreChat starts (for example a GitHub personal access token), you can also set startup: false so LibreChat does not try to connect until a user does.
• Example:

  customUserVars:
    MY_SERVICE_API_KEY:
      title: 'My Service API Key'
      description: "Your personal API access key for My Service. Find it at <a href='https://myservice.example.com/settings/api' target='_blank'>My Service API Settings</a>."
      sensitive: true
    SOME_OTHER_VAR:
      title: 'Some Other Variable'
      description: 'The specific value for some other configuration (e.g., a specific path or identifier).'
      sensitive: false

  Usage in headers:

  headers:
    X-Auth-Token: '{{MY_SERVICE_API_KEY}}'
    X-Some-Other-Config: '{{SOME_OTHER_VAR}}'

  Usage in env (for stdio type):

  env:
    API_KEY: '{{MY_SERVICE_API_KEY}}'

obo

• Type: Object (Optional, for sse and streamable-http types only)
• Description: Configures OAuth 2.0 On-Behalf-Of token exchange for an MCP server. LibreChat exchanges the logged-in user's OpenID access token for a delegated downstream token with the configured scopes, then forwards that token to the MCP server as an Authorization: Bearer ... header.
• Required Subkeys:
  • scopes: String - Non-empty scopes requested for the downstream token exchange.
• Validation:
  • obo is only valid for sse and streamable-http MCP servers.
  • obo is rejected for stdio and websocket servers.
  • Users need the MCP_SERVERS.CONFIGURE_OBO role permission to configure this field. Seed it with interface.mcpServers.configureObo or manage it from the admin panel.
• Prerequisites:
  • OpenID authentication must be configured with reusable access tokens.
  • Your identity provider and downstream application must allow the requested delegated scope.
• Example:

  mcpServers:
    enterprise-tools:
      type: streamable-http
      url: https://api.example.com/mcp/
      obo:
        scopes: 'api://mcp-server-id/Mcp.Tools.ReadWrite'

See OpenID Connect Token Reuse and SharePoint Integration for related token-reuse and delegated-token setup.

oauth

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

• 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 (eg. http://localhost:3080/api/mcp/${serverName}/oauth/callback)
  • scope: String - OAuth scopes (space-separated)

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

  oauth-api-server:
    authorization_url: https://api.example.com/oauth/authorize
    token_url: https://api.example.com/oauth/token
    client_id: your_client_id
    client_secret: your_client_secret
    redirect_uri: http://localhost:3080/api/mcp/oauth-api-server/oauth/callback
    scope: 'read execute'
    grant_types_supported: ['authorization_code', 'refresh_token']
    token_endpoint_auth_methods_supported: ['client_secret_post']
    token_exchange_method: default_post
    response_types_supported: ['code']
    code_challenge_methods_supported: ['S256', 'plain']

  Auth0 example:

  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.

oauth_headers

• Type: Object (Optional)
• Description: Headers used specifically for OAuth flow requests. These headers are used during OAuth authentication, such as dynamic client registration and token exchange, and are not sent during regular MCP server communication.
• Common Use Cases:
  • 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
• Example:

  oauth_headers:
    Authorization: "Bearer ${DCR_API_KEY}"
    X-Custom-Header: "custom_value"

oauthPrompt

• Type: String (Optional)
• Description: Controls when a user is asked to sign in to an OAuth-protected server.
  • on_start: the sign-in prompt appears when the conversation turn starts, before the agent runs.
  • 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 ("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 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. 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.
  • Only operator-configured servers qualify: those defined in librechat.yaml or added through admin configuration overrides. Servers users create in the UI keep the turn-start prompt. The prompt stays at turn start for a server that uses obo, customUserVars, requestHeaders, or per-user or per-request placeholders ({{LIBRECHAT_USER_*}}, {{LIBRECHAT_OPENID_*}}, {{LIBRECHAT_GRAPH_*}}, {{LIBRECHAT_BODY_*}}) in its connection settings.
  • Applies whether OAuth is configured up front (oauth, requiresOAuth: true) or detected when the server refuses the connection.
  • Not available on servers users create in the UI.
• Example:

  mcpServers:
    google-sheets:
      type: streamable-http
      url: https://sheets.example.com/mcp
      requiresOAuth: true
      oauthPrompt: on_use
      oauthToolCatalog:
        - name: read_sheet
          description: Read the values in a spreadsheet range

oauthToolCatalog

• Type: Array of Objects (Optional)
• Description: The tools an oauthPrompt: on_use server offers to tool search before a user signs in. LibreChat cannot list a protected server's tools for a user who has not signed in, so the operator declares them here. The catalog is the same for every user; no user's connection decides what other users' agents see. Once a user signs in, the server's own tool definitions are used, and the server validates every call.
• Entry fields:
  • name: String (Required) - The tool's name on the server, as the agent selects it.
  • description: String (Optional) - What the tool does, shown to tool search and the model.
  • inputSchema: Object (Optional) - The tool's parameters:
    • type: must be object
    • properties: map of parameter name to a property schema
    • required: array of required parameter names
• Property schema: a bounded subset of JSON Schema with these keys only:
  • type: one of string, number, integer, boolean, object, array, null, or a non-empty list of them
  • description: String
  • enum: non-empty array of strings, numbers, booleans, or null
  • default: a string, number, boolean, or null
  • items: for arrays, an object with type, description, and enum
• Notes:
  • Validation is strict. A misspelled entry key (such as input_schema) or a keyword outside the bounded schema (such as minLength, pattern, or $ref) fails config validation instead of being ignored.
  • A user whose earlier connection left a tool list is offered that list instead; either way it must include every tool the agent selected from the server, or the prompt stays at turn start.
  • Not available on servers users create in the UI.
• Example:

  oauthToolCatalog:
    - name: read_sheet
      description: Read the values in a spreadsheet range
      inputSchema:
        type: object
        properties:
          range: { type: string }
        required: [range]

startup

• Type: Boolean (Optional)
• Description: When set to false, this MCP server will not be connected at application startup. This is useful for servers that require user input or configuration before connecting, or for cases where you want to control when the server is initialized.
• Default Value: true
• Example:

  mcpServers:
    my-mcp-server:
      type: streamable-http
      url: 'https://api.example.com/mcp/'
      startup: false

Notes

• Type Inference:
  • If type is omitted:
    • 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.
• Connection Types:
  • stdio: Starts an MCP server as a child process and communicates via standard input/output.
  • websocket: Connects to an external MCP server via WebSocket.
  • sse: Connects to an external MCP server via Server-Sent Events (SSE).
  • streamable-http: Connects to an external MCP server via HTTP with support for streaming responses.
  • stdio runs one process on the LibreChat host and suits local, single-user setups. sse is the older remote transport. For multi-user or production deployments, use streamable-http.
• Internal/Local Addresses:
  • Important: MCP servers using internal IP addresses (e.g., 172.24.1.165, 192.168.1.100), or local domains (e.g., mcp-server, host.docker.internal) must be explicitly allowed. Use mcpSettings.allowedAddresses for exact private host:port services when you want public destinations to remain reachable, or mcpSettings.allowedDomains when you want a strict whitelist.
  • See MCP Settings for configuration details.

OAuth callback URL

When a server uses OAuth, the provider redirects back to LibreChat at:

${DOMAIN_SERVER}/api/mcp/<server-name>/oauth/callback

<server-name> is the key under mcpServers. For example, a server named salesforce with DOMAIN_SERVER=https://chat.example.com uses https://chat.example.com/api/mcp/salesforce/oauth/callback. A local Docker install usually uses http://localhost:3080 as the base. For servers created in the UI, the server's generated identifier takes the place of the key, and LibreChat shows the full Redirect URI after the server is created.

Register this exact URL with the OAuth provider. Other LibreChat callback paths, such as /api/oauth/callback or /api/oauth/openid/callback, do not work for MCP.

If the provider supports dynamic client registration, the server needs no oauth block at all; LibreChat registers itself as a client the first time a user connects:

mcpServers:
  # No refresh tokens: users sign in again when the token expires
  paypal:
    type: sse
    url: https://mcp.paypal.com/sse
    initTimeout: 150000
  # Issues refresh tokens: LibreChat renews access automatically
  spotify:
    type: streamable-http
    url: https://mcp-spotify-oauth-example.account.workers.dev/mcp
    initTimeout: 150000

Users have 10 minutes to finish signing in, and LibreChat keeps the pending flow for 15 minutes. Change these with MCP_OAUTH_HANDLING_TIMEOUT and MCP_OAUTH_FLOW_TTL in .env (see MCP environment variables). The flow TTL is always kept at least one minute longer than the handling timeout, so a callback that arrives near the deadline still finds its flow.

Servers created in the UI

Users whose role has the CREATE permission (see interface.mcpServers) can add servers from MCP Settings without editing this file. Those servers are stored in the database and differ from YAML servers in a few ways:

• Only remote transports (streamable-http and sse) are available. stdio servers must be defined here.
• ${ENV_VAR}, {{LIBRECHAT_USER_*}}, {{LIBRECHAT_OPENID_*}}, {{LIBRECHAT_GRAPH_*}}, and {{LIBRECHAT_BODY_*}} placeholders are removed from their headers, because the server may be shared with other users. Only customUserVars placeholders are kept.
• OAuth endpoint URLs must be literal URLs; ${ENV_VAR} references are rejected.
• Choosing an API key that each user provides creates a customUserVars entry named MCP_API_KEY_<hash> and the matching header. Servers saved before this change may keep the legacy MCP_API_KEY name until their URL or authentication changes. See apiKey for which edits make users enter their key again.
• A server with an API key (shared or per user) is treated as API-key authenticated and skips OAuth auto-detection, unless it also has an OAuth configuration. If an API-key server saved by an older version stays on Needs Auth, edit and save it once to refresh its stored metadata.
• Stored OAuth clients and tokens are bound to the server URL and the OAuth client and endpoint settings. Changing them makes users sign in again, and the editor has to re-enter a stored client secret when changing the URL, client ID, authorization URL, token URL, or token exchange method.
• oauthPrompt and oauthToolCatalog are not available.
• mcpSettings domain and address restrictions apply.
• New and edited servers take effect without a restart. An OAuth server is saved disconnected until a user signs in.

For the full placeholder set, define the server in librechat.yaml.

Finding servers

Smithery lists public MCP servers. On a server's page, the Connect section can generate an install command for the LibreChat client that writes the entry into librechat.yaml; restart LibreChat afterwards. The MCP Servers guides walk through setting up specific servers.

Examples

Configuration with Internal Addresses

When using internal/local MCP servers and no strict domain whitelist is needed, configure mcpSettings.allowedAddresses with the exact host and port:

# MCP Settings - Required for internal/local addresses
mcpSettings:
  allowedAddresses:
    - '172.24.1.165:8000' # Internal IP and port
    - 'mcp-prod:8001' # Docker container and port
    - 'host.docker.internal:8080' # Docker host and port

# MCP Servers - Individual configurations
mcpServers:
  prod-mcp:
    type: streamable-http
    url: http://172.24.1.165:8000/mcp
    timeout: 120000

  test-mcp:
    type: streamable-http
    url: http://mcp-prod:8001/mcp
    timeout: 120000

stdio MCP Server

puppeteer:
  type: stdio
  command: npx
  args:
    - -y
    - '@modelcontextprotocol/server-puppeteer'
  timeout: 30000
  initTimeout: 10000
  env:
    NODE_ENV: 'production'
    USER_EMAIL: '{{LIBRECHAT_USER_EMAIL}}'
    USER_ROLE: '{{LIBRECHAT_USER_ROLE}}'
  stderr: inherit

sse MCP Server

everything:
  url: http://localhost:3001/sse
  headers:
    X-User-ID: '{{LIBRECHAT_USER_ID}}'
    X-API-Key: '${SOME_API_KEY}'

websocket MCP Server

myWebSocketServer:
  url: ws://localhost:8080

streamable-http MCP Server

streamable-http-server:
  type: streamable-http
  url: https://example.com/api/
  headers:
    X-User-ID: '{{LIBRECHAT_USER_ID}}'
    X-API-Key: '${SOME_API_KEY}'

MCP Server with Dynamic User Fields

user-aware-server:
  type: sse
  url: https://api.example.com/users/{{LIBRECHAT_USER_USERNAME}}/stream
  headers:
    X-User-ID: '{{LIBRECHAT_USER_ID}}'
    X-User-Email: '{{LIBRECHAT_USER_EMAIL}}'
    X-User-Role: '{{LIBRECHAT_USER_ROLE}}'
    X-Email-Verified: '{{LIBRECHAT_USER_EMAILVERIFIED}}'
    Authorization: 'Bearer ${API_TOKEN}'

MCP Server with Per-User Credentials via customUserVars

my-mcp-server:
  type: streamable-http
  url: 'https://api.example-service.com/api/' # Example URL
  headers:
    X-Auth-Token: '{{API_KEY}}' # Uses the API_KEY defined below
  customUserVars:
    API_KEY: # This key will be used as {{API_KEY}} in headers/url
      title: 'API Key' # This is the label shown above the input field
      description: "Get your API key <a href='https://example.com/api-keys' target='_blank'>here</a>." # This description appears below the input

See Credentials and variables for what users see when they connect a server with customUserVars.

MCP Server with Custom Icon

filesystem:
  command: npx
  args:
    - -y
    - '@modelcontextprotocol/server-filesystem'
    - /home/user/LibreChat/
  iconPath: /home/user/LibreChat/client/public/assets/logo.svg
  chatMenu: false # Exclude from regular chat selection; Agent use remains available

MCP Server with OAuth Authentication

oauth-api-server:
  type: streamable-http
  url: https://api.example.com/mcp/
  oauth:
    authorization_url: https://api.example.com/oauth/authorize
    token_url: https://api.example.com/oauth/token
    client_id: your_client_id
    client_secret: your_client_secret
    redirect_uri: http://localhost:3080/api/mcp/oauth-api-server/oauth/callback
    scope: 'read execute'
  oauth_headers:
    X-Custom-Header: 'custom_value'

MCP Server with OAuth Sign-In on First Tool Use

google-sheets:
  type: streamable-http
  url: https://sheets.example.com/mcp
  requiresOAuth: true
  # Ask users to sign in when the agent first calls one of this server's tools.
  # Every tool the agent selects from this server must be deferred.
  oauthPrompt: on_use
  # Offered to tool search until a user signs in; without it the turn-start prompt is kept.
  oauthToolCatalog:
    - name: read_sheet
      description: Read the values in a spreadsheet range
      inputSchema:
        type: object
        properties:
          range: { type: string }
        required: [range]

MCP Server with Server Instructions

# Server that uses its own provided instructions
web-search:
  type: streamable-http
  url: https://example.com/mcp/search
  serverInstructions: true

# Server with instructions explicitly disabled
filesystem:
  command: npx
  args:
    - -y
    - '@modelcontextprotocol/server-filesystem'
    - /home/user/documents/
  serverInstructions: false

# Server with custom instructions
puppeteer:
  type: stdio
  command: npx
  args:
    - -y
    - '@modelcontextprotocol/server-puppeteer'
  serverInstructions: |
    Browser automation security and best practices:
    1. Be cautious with local file access and internal IP addresses
    2. Take screenshots to verify successful page interactions
    3. Wait for page elements to load before interacting with them
    4. Use specific CSS selectors for reliable element targeting
    5. Check console logs for JavaScript errors when troubleshooting

OAuth-Enabled MCP Server (Legacy requiresOAuth)

composio-googlesheets:
  type: sse
  url: https://mcp.composio.dev/googlesheets/sse-endpoint
  requiresOAuth: true
  headers:
    X-User-ID: '{{LIBRECHAT_USER_ID}}'
    X-API-Key: '${COMPOSIO_API_KEY}'
  timeout: 45000
  initTimeout: 15000

Related Environment Variables (Optional): See Environment Variables for all MCP settings.

# OAuth configuration for MCP servers
MCP_OAUTH_ON_AUTH_ERROR=true
MCP_OAUTH_DETECTION_TIMEOUT=5000
MCP_OAUTH_HANDLING_TIMEOUT=600000
MCP_OAUTH_FLOW_TTL=900000

# API key for the service
COMPOSIO_API_KEY=your_composio_api_key_here

Importing MCP Server Configurations

The mcpServers configurations allow LibreChat to dynamically interact with various MCP servers, which can perform specialized tasks or provide specific functionalities within the application. This modular approach facilitates extending the application's capabilities by simply adding or modifying server configurations.

Additional Information

• Default Behavior:
  • Servers in librechat.yaml are initialized at startup, so changes to this file need a restart. Servers created in the UI do not.
  • Servers that send notifications/tools/list_changed can add or remove tools while running; LibreChat refetches the tool list from the live connection without a restart.
  • When a user presses Stop during a tool call, LibreChat cancels the MCP request. Streamable HTTP servers receive notifications/cancelled and have to honor it to stop their own work. Tool calls running in the background are not cancelled.
  • If both url and command are specified, the type must be explicitly defined to avoid ambiguity.
• Multi-User Support:
  • The MCPManager now supports distinct user-level and app-level connections, enabling proper connection management per user.
  • User connections are tracked and managed separately, with proper establishment and cleanup.
  • With Redis enabled, OAuth flow state and the MCP tool catalog are shared across replicas, including Redis Cluster deployments. See OAuth refresh coordination for token refresh across replicas.
  • Use dynamic user field placeholders in headers, URLs, and environment variables:
    • {{LIBRECHAT_USER_ID}} - User's unique identifier
    • {{LIBRECHAT_USER_EMAIL}} - User's email address
    • {{LIBRECHAT_USER_USERNAME}} - User's username
    • {{LIBRECHAT_USER_ROLE}} - User's role (e.g., "user", "admin")
    • And many more fields (see headers section for complete list)
• User Idle Management:
  • User connections are monitored for activity and will be disconnected after 15 minutes of inactivity. Change this with MCP_USER_CONNECTION_IDLE_TIMEOUT (milliseconds).
• Environment Variables:
  • In env (for stdio type): Useful for setting up specific runtime environments or configurations required by the MCP server process.
  • In headers (for sse and streamable-http types): Use ${ENV_VAR} syntax to reference environment variables in header values.
• Dynamic User Fields:
  • User field placeholders are replaced at runtime with the authenticated user's information
  • Only non-sensitive fields are available (passwords and other sensitive data are excluded)
  • Missing fields default to empty strings
  • Boolean fields are converted to string representations ("true" or "false")
• Error Handling (stderr):
  • Configuring stderr allows you to manage how error messages from the MCP server process are handled. The default "inherit" means that the errors will be printed to the parent process's stderr.
• Server Instructions:
  • Instructions are automatically injected into the agent's system message when MCP server tools are used
  • Custom instructions (string values) take precedence over server-provided instructions
  • Multiple MCP servers can each contribute their own instructions to the agent context
  • Instructions are only included when the corresponding MCP server's tools are actually available to the agent
• OAuth Authentication:
  • OAuth2 flow is supported for secure authentication with MCP servers
  • Users will be prompted to authenticate via OAuth before the MCP server can be used

References

• Model Context Protocol (MCP) Documentation
• MCP Transports Specification
• Node.js child_process.spawn

By properly configuring the mcpServers in your librechat.yaml, you can enhance LibreChat's functionality and integrate custom tools and services seamlessly.