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"
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
Number
(Optional) Timeout in milliseconds for MCP server requests. Determines how long to wait for a response for tool requests.
timeout: 30000
initTimeout
Number
(Optional) Timeout in milliseconds for MCP server initialization. Determines how long to wait for the server to initialize.
initTimeout: 10000
env
Object
(Optional, `stdio` type only) Environment variables to use when spawning the process.
env:
NODE_ENV: "production"
requiresOAuth
Boolean
(Optional, `sse` type only) 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.
requiresOAuth: true
stderr
String or Stream or Number
(Optional, `stdio` type only) How to handle `stderr` of the child process. 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.
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://.
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:
Only applicable to sse type MCP servers
Auto-detection occurs during server startup, which may add initialization time
Explicit configuration improves startup performance by skipping detection
Works with MCP OAuth environment variables (MCP_OAUTH_ON_AUTH_ERROR, MCP_OAUTH_DETECTION_TIMEOUT) for enhanced connection management
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>).
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>." SOME_OTHER_VAR: title: "Some Other Variable" description: "The specific value for some other configuration (e.g., a specific path or identifier)."
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"])
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)
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 in mcpSettings.allowedDomains.
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=10000# 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
