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
  mcp-obsidian:
    command: npx
    args:
      - -y
      - "mcp-obsidian"
      - /path/to/obsidian/vault
  streamable-http-server:
    type: streamable-http
    url: https://example.com/api/
```

## `<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"'],
  ]}
/>

#### `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.
- **Special Values:**
  - `{{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.
  - `${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. Supports the same dynamic user field placeholders as headers (`{{LIBRECHAT_USER_*}}`) and environment variable substitution (`${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`).

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