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.
(Optional) Custom display name for the MCP server in the UI. If not specified, the server key name is used.
title: "My Custom Server"
description
String
(Optional) Description of the MCP server, displayed in the UI to help users understand its purpose.
description: "Provides file system access"
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`.
type: "stdio"
command
String
(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 `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.
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) API key authentication configuration for the MCP server.
See apiKey section below
iconPath
String
(Optional) Defines the tool's display icon shown in the tool selection dialog.
iconPath: "/path/to/icon.svg"
chatMenu
Boolean
(Optional) When set to `false`, excludes the MCP server from the chatarea dropdown (MCPSelect) for quick and easy access. Defaults to `true`.
chatMenu: false
serverInstructions
Boolean or String
(Optional) 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.
serverInstructions: true
# or
serverInstructions: "Custom instructions"
timeout
Integer
(Optional) Timeout in milliseconds for MCP server requests. Must be a non-negative integer.
timeout: 30000
initTimeout
Integer
(Optional) Timeout in milliseconds for MCP server initialization. Must be a non-negative integer.
initTimeout: 10000
env
Object
(Optional, `stdio` type only) Environment variables to use when spawning the process.
env:
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.
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"`.
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.
customUserVars:
API_KEY:
title: "API Key"
description: "Your personal API key."
oauth
Object
(Optional) OAuth2 configuration for authenticating with the MCP server. When configured, users will be prompted to authenticate via OAuth flow.
(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.
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']
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://.
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.
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. {{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.
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
Example:
# Use server-provided instructionsserverInstructions: true# Use custom instructionsserverInstructions: | When using this filesystem server: 1. Always use absolute paths for file operations 2. Check file permissions before attempting write operations# Explicitly disable instructionsserverInstructions: false
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
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).
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 (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: <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 provide these values through the UI. These settings can be accessed in two ways:
From Assistant Chat Input: When selecting MCP tools for an assistant, a settings icon will appear next to configurable MCP servers in the tool selection dropdown. Clicking this icon opens a dialog to manage credentials for that server.
From Settings Panel: A dedicated "MCP Settings" section in the right panel lists all MCP servers with definable custom variables. Users can click on a server to open the configuration dialog to set or update their credentials for that specific MCP server.
These user-provided values are stored securely, associated with the individual user and the specific MCP server, and substituted at runtime.
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
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.
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:
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)
Optional 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 - Token exchange request method. Use default_post for providers that expect the OAuth client credentials in the POST body.
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)
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.
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.
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.
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.
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
# Server that uses its own provided instructionsweb-search: type: streamable-http url: https://example.com/mcp/search serverInstructions: true# Server with instructions explicitly disabledfilesystem: command: npx args: - -y - '@modelcontextprotocol/server-filesystem' - /home/user/documents/ serverInstructions: false# Server with custom instructionspuppeteer: 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 configuration for MCP serversMCP_OAUTH_ON_AUTH_ERROR=trueMCP_OAUTH_DETECTION_TIMEOUT=10000MCP_OAUTH_HANDLING_TIMEOUT=600000MCP_OAUTH_FLOW_TTL=900000# API key for the serviceCOMPOSIO_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.
Initialization happens at startup, and the app must be restarted for changes to take effect.
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.
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.
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
By properly configuring the mcpServers in your librechat.yaml, you can enhance LibreChat's functionality and integrate custom tools and services seamlessly.
LibreChat
