📚 docs: MCP server Dynamic User Field Placeholders (#326)

- Updated the `mcp_servers.mdx` and `agents.mdx` files to include dynamic user field placeholders for headers, URLs, and environment variables.
- Added detailed descriptions and examples for user field placeholders such as `{{LIBRECHAT_USER_EMAIL}}`, `{{LIBRECHAT_USER_ROLE}}`, and others.
- Improved clarity on the usage of environment variables and their integration with user-specific data.

Author: danny-avila

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

@@ -56,7 +56,7 @@ mcpServers:
     ['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 user ID substitution with `{{LIBRECHAT_USER_ID}}` and environment variables with `${ENV_VAR}`.', 'headers:\n  X-User-ID: "{{LIBRECHAT_USER_ID}}"\n  X-API-Key: "${SOME_API_KEY}"'],
+    ['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'],
     ['timeout', 'Number', '(Optional) Timeout in milliseconds for MCP server requests. Determines how long to wait for a response for tool requests.', 'timeout: 30000'],
@@ -85,7 +85,7 @@ mcpServers:
 #### `url`
 
 - **Type:** String
-- **Description:** (For `websocket`, `streamable-http`, or `sse` type) The URL to connect to the MCP server.
+- **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://`.
@@ -97,11 +97,38 @@ mcpServers:
 - **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}"
   ```
@@ -120,7 +147,7 @@ mcpServers:
 #### `env`
 
 - **Type:** Object (Optional, `stdio` type only)
-- **Description:** Environment variables to use when spawning the process.
+- **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`
 
@@ -168,6 +195,8 @@ puppeteer:
   initTimeout: 10000
   env:
     NODE_ENV: "production"
+    USER_EMAIL: "{{LIBRECHAT_USER_EMAIL}}"
+    USER_ROLE: "{{LIBRECHAT_USER_ROLE}}"
   stderr: inherit
 ```
 
@@ -199,6 +228,20 @@ streamable-http-server:
     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"
@@ -228,12 +271,22 @@ The `mcpServers` configurations allow LibreChat to dynamically interact with var
 - **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 the `{{LIBRECHAT_USER_ID}}` placeholder in headers to identify user-specific connections.
+  - 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`.
 

pages/docs/features/agents.mdx

@@ -220,8 +220,13 @@ MCP servers can be configured to use different transport mechanisms:
 **Multi-User Features**
 - User-level and app-level connections with proper establishment and cleanup
 - MCP Servers can distinguish connections by session ID
-- Custom headers with user ID substitution: `{{LIBRECHAT_USER_ID}}`
-- Environment variable support in headers: `${SOME_API_KEY}`
+- Dynamic user field placeholders in headers, URLs, and environment variables:
+  - `{{LIBRECHAT_USER_ID}}` - User's unique identifier
+  - Basic fields: `{{LIBRECHAT_USER_EMAIL}}`, `{{LIBRECHAT_USER_USERNAME}}`, `{{LIBRECHAT_USER_NAME}}`, `{{LIBRECHAT_USER_ROLE}}`, `{{LIBRECHAT_USER_PROVIDER}}`
+  - Provider IDs: `{{LIBRECHAT_USER_GOOGLEID}}`, `{{LIBRECHAT_USER_OPENIDID}}`, `{{LIBRECHAT_USER_SAMLID}}`, `{{LIBRECHAT_USER_LDAPID}}`, etc.
+  - Boolean fields: `{{LIBRECHAT_USER_EMAILVERIFIED}}`, `{{LIBRECHAT_USER_TWOFACTORENABLED}}`, `{{LIBRECHAT_USER_TERMSACCEPTED}}`
+  - See [MCP Servers documentation](/docs/configuration/librechat_yaml/object_structure/mcp_servers#headers) for complete field list
+- Environment variable support: `${SOME_API_KEY}`
 - User idle timeout management for efficient resource usage
 
 **Example Configuration:**
@@ -232,14 +237,25 @@ mcpServers:
     url: https://mcp.composio.dev/googlesheets/some-endpoint
     headers:
       X-User-ID: "{{LIBRECHAT_USER_ID}}"
+      X-User-Email: "{{LIBRECHAT_USER_EMAIL}}"
       X-API-Key: "${SOME_API_KEY}"
 
   streamable-http-example:
     type: streamable-http
-    url: https://example.com/mcp/
+    url: https://example.com/mcp/users/{{LIBRECHAT_USER_USERNAME}}
     headers:
       X-User-ID: "{{LIBRECHAT_USER_ID}}"
+      X-User-Role: "{{LIBRECHAT_USER_ROLE}}"
       Authorization: "Bearer ${API_TOKEN}"
+  
+  user-context-server:
+    type: stdio
+    command: node
+    args: ["server.js"]
+    env:
+      USER_EMAIL: "{{LIBRECHAT_USER_EMAIL}}"
+      USER_PROVIDER: "{{LIBRECHAT_USER_PROVIDER}}"
+      API_KEY: "${MCP_API_KEY}"
 ```
 
 LibreChat is at the forefront of implementing flexible, scalable MCP server integrations to support diverse usage scenarios.