From 6144d7eea5933c45d8c87af31a5258c0f0e6adc1 Mon Sep 17 00:00:00 2001 From: Ben Verhees Date: Sat, 7 Jun 2025 16:39:26 +0200 Subject: [PATCH] Add documentation for MCP Server instructions --- .../object_structure/config.mdx | 3 + .../object_structure/mcp_servers.mdx | 72 ++++++++++++++++++- 2 files changed, 74 insertions(+), 1 deletion(-) diff --git a/pages/docs/configuration/librechat_yaml/object_structure/config.mdx b/pages/docs/configuration/librechat_yaml/object_structure/config.mdx index aa5274ebc..bb394e6ee 100644 --- a/pages/docs/configuration/librechat_yaml/object_structure/config.mdx +++ b/pages/docs/configuration/librechat_yaml/object_structure/config.mdx @@ -377,6 +377,7 @@ see: [Model Specs Object Structure](/docs/configuration/librechat_yaml/object_st - Additional configuration options include: - `timeout`: Timeout in milliseconds for MCP server requests. Determines how long to wait for a response for tool requests. - `initTimeout`: Timeout in milliseconds for MCP server initialization. Determines how long to wait for the server to initialize. + - `serverInstructions`: Controls whether server instructions are included in agent context. Can be `true` (use server-provided), `false` (disabled), or a custom string (overrides server-provided). - see: [MCP Servers Object Structure](/docs/configuration/librechat_yaml/object_structure/mcp_servers) **Example:** @@ -388,6 +389,7 @@ mcpServers: url: http://localhost:3001/sse timeout: 30000 initTimeout: 10000 + serverInstructions: true # Use server-provided instructions puppeteer: type: stdio command: npx @@ -396,6 +398,7 @@ mcpServers: - "@modelcontextprotocol/server-puppeteer" timeout: 30000 initTimeout: 10000 + serverInstructions: "Do not access any local files or local/internal IP addresses" filesystem: # type: stdio command: npx 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..179d4e665 100644 --- a/pages/docs/configuration/librechat_yaml/object_structure/mcp_servers.mdx +++ b/pages/docs/configuration/librechat_yaml/object_structure/mcp_servers.mdx @@ -14,12 +14,14 @@ mcpServers: 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 @@ -59,6 +61,7 @@ mcpServers: ['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}"'], ['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"'], @@ -117,6 +120,34 @@ mcpServers: - **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) @@ -212,6 +243,40 @@ filesystem: 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** @@ -236,6 +301,11 @@ The `mcpServers` configurations allow LibreChat to dynamically interact with var - **In `headers` (for `sse` and `streamable-http` types):** Use `${ENV_VAR}` syntax to reference environment variables in header values. - **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 @@ -245,4 +315,4 @@ The `mcpServers` configurations allow LibreChat to dynamically interact with var --- -By properly configuring the `mcpServers` in your `librechat.yaml`, you can enhance LibreChat's functionality and integrate custom tools and services seamlessly. \ No newline at end of file +By properly configuring the `mcpServers` in your `librechat.yaml`, you can enhance LibreChat's functionality and integrate custom tools and services seamlessly.