diff --git a/pages/docs/configuration/librechat_yaml/object_structure/mcp_servers.mdx b/pages/docs/configuration/librechat_yaml/object_structure/mcp_servers.mdx index d6ea79b61..d642b3a06 100644 --- a/pages/docs/configuration/librechat_yaml/object_structure/mcp_servers.mdx +++ b/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`. diff --git a/pages/docs/features/agents.mdx b/pages/docs/features/agents.mdx index 094abb981..1b25aecab 100644 --- a/pages/docs/features/agents.mdx +++ b/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.