librechat.ai/pages/docs/configuration/librechat_yaml/object_structure/mcp_servers.mdx

# MCP Servers Object Structure

## Example

```yaml filename="MCP Servers Object Structure"
# 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
    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/
  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>."
```

## `<serverName>`

**Key:**
<OptionTable
  options={[
    ['<serverName>', '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.', ''],
  ]}
/>

### Subkeys

<OptionTable
  options={[
    ['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`.', 'args: ["-y", "@modelcontextprotocol/server-puppeteer"]'],
    ['url', 'String', '(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}`.', 'headers:\n  X-User-ID: "{{LIBRECHAT_USER_ID}}"\n  X-API-Key: "${SOME_API_KEY}"'],
    ['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\n# or\nserverInstructions: "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:\n  NODE_ENV: "production"'],
    ['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:\n  API_KEY:\n    title: "API Key"\n    description: "Your personal API key."'],
    ['startup', 'Boolean', '(Optional) When set to false, this MCP server will not be connected at application startup.', 'startup: false'],
  ]}
/>

#### `type`

- **Type:** String
- **Description:** Specifies the connection type to the MCP server. Valid options are `"stdio"`, `"websocket"`, `"streamable-http"`, or `"sse"`.
- **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`.

#### `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://`.

#### `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.
  - `{{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:**

| Placeholder | User Field | Type | Description |
|------------|------------|------|-------------|
| `{{LIBRECHAT_USER_NAME}}` | `name` | String | User's display name |
| `{{LIBRECHAT_USER_USERNAME}}` | `username` | String | User's username |
| `{{LIBRECHAT_USER_EMAIL}}` | `email` | String | User's email address |
| `{{LIBRECHAT_USER_PROVIDER}}` | `provider` | String | Authentication provider (e.g., "email", "google", "github") |
| `{{LIBRECHAT_USER_ROLE}}` | `role` | String | User's role (e.g., "user", "admin") |
| `{{LIBRECHAT_USER_GOOGLEID}}` | `googleId` | String | Google account ID |
| `{{LIBRECHAT_USER_FACEBOOKID}}` | `facebookId` | String | Facebook account ID |
| `{{LIBRECHAT_USER_OPENIDID}}` | `openidId` | String | OpenID account ID |
| `{{LIBRECHAT_USER_SAMLID}}` | `samlId` | String | SAML account ID |
| `{{LIBRECHAT_USER_LDAPID}}` | `ldapId` | String | LDAP account ID |
| `{{LIBRECHAT_USER_GITHUBID}}` | `githubId` | String | GitHub account ID |
| `{{LIBRECHAT_USER_DISCORDID}}` | `discordId` | String | Discord account ID |
| `{{LIBRECHAT_USER_APPLEID}}` | `appleId` | String | Apple account ID |
| `{{LIBRECHAT_USER_EMAILVERIFIED}}` | `emailVerified` | Boolean → String | Email verification status ("true" or "false") |
| `{{LIBRECHAT_USER_TWOFACTORENABLED}}` | `twoFactorEnabled` | Boolean → String | 2FA status ("true" or "false") |
| `{{LIBRECHAT_USER_TERMSACCEPTED}}` | `termsAccepted` | Boolean → String | Terms acceptance status ("true" or "false") |

**Note:** Missing fields will be replaced with empty strings.

- **Example:**
  ```yaml
  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}"
  ```

#### `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`, excludes the MCP server from the chatarea dropdown (MCPSelect) for quick and easy access.
- **Default Value:** `true` (The MCP server will be included in the chatarea dropdown)

#### `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
- **Example:**
  ```yaml
  # 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:** Number (Optional)
- **Description:** Timeout in milliseconds for MCP server requests. Determines how long to wait for a response for tool requests.
- **Default Value:** `30000` (30 seconds)

#### `initTimeout`

- **Type:** Number (Optional)
- **Description:** Timeout in milliseconds for MCP server initialization. Determines how long to wait for the server to initialize.
- **Default Value:** `10000` (10 seconds)

#### `stderr`

- **Type:** String or Stream or Number (Optional, `stdio` type only)
- **Description:** How to handle `stderr` of the child process. This matches the semantics of Node's [`child_process.spawn`](https://nodejs.org/api/child_process.html#child_processspawncommand-args-options).
- **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` configuration.
- **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.
    <img src="/images/mcp/mcp_per_user_vars_assistant.png" alt="MCP Per-User Variables Configuration - Assistant Access" width={600} />
    <img src="/images/mcp/mcp_per_user_vars_assistant_dialog.png" alt="MCP Per-User Variables Configuration - Assistant Access Dialog" width={800} />
    - **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.
    <img src="/images/mcp/mcp_per_user_vars_side_panel.png" alt="MCP Per-User Variables Configuration - Settings Panel Access" width={300} />
  - These user-provided values are stored securely, associated with the individual user and the specific MCP server, and substituted at runtime.
- **Example:**
  ```yaml
  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)."
  ```
  Usage in `headers`:
  ```yaml
  headers:
    X-Auth-Token: "{{MY_SERVICE_API_KEY}}"
    X-Some-Other-Config: "{{SOME_OTHER_VAR}}"
  ```

#### `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:**
  ```yaml
  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.

## Examples

### `stdio` MCP Server

```yaml filename="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

```yaml filename="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

```yaml filename="websocket MCP Server"
myWebSocketServer:
  url: ws://localhost:8080
```

### `streamable-http` MCP Server

```yaml filename="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

```yaml filename="MCP Server with 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`

```yaml filename="MCP Server with 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
```

### MCP Server with Custom Icon

```yaml filename="MCP Server with 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 chatarea dropdown
```

### MCP Server with Server Instructions

```yaml filename="MCP Server with 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
```

---

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

## References

- [Model Context Protocol (MCP) Documentation](https://github.com/modelcontextprotocol)
- [MCP Transports Specification](https://modelcontextprotocol.io/specification/draft/basic/transports)
- [Node.js child_process.spawn](https://nodejs.org/api/child_process.html#child_processspawncommand-args-options)

---

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