💉 feat: Optionally Inject MCP Server Instructions

[benverhees]

Summary

This PR introduces functionality to dynamically inject MCP server instructions into the system context of an agent. This supports both ephemeral agents and standard agents with MCP tool associations. The instructions are retrieved from the MCP server through the client API in the MCPManager and injected in the system content.

MCP server instructions provide high-level context about how to effectively use an entire MCP server - including usage patterns, workflows, and general guidance about the server's capabilities. This is distinct from tool descriptions, which are the specific function-level documentation that describes individual tools' parameters and return values.

This change ensures that comprehensive server-level instructions are automatically available to the agent at runtime, complementing the existing tool descriptions with broader contextual guidance. This improves overall tool usability by providing both the "what" (individual tool descriptions) and the "how" (server usage instructions), reducing the need for hardcoded context-specific behavior.

The serverInstructions configuration option provides unified control over instruction behavior:

• Not set/undefined (default): No instructions will be included
• true: Use server-provided instructions
• string: Use custom instructions (overrides server-provided)
• false: Explicitly disable (same as not setting)

When to Use Each Option

serverInstructions: true

Use when the server provides good default instructions:

• Well-documented servers: The server provides comprehensive tool usage guidance
• Standard workflows: The server's instructions match your typical use cases
• Quick setup: You want to get started without writing custom instructions

serverInstructions: "custom instructions"

Use when you need specific guidance:

• Tailored workflows: Instructions specific to your application or domain
• Enhanced clarity: You can write clearer instructions than the server provides
• Missing context: The server instructions lack important details for your use case
• Compliance requirements: You need specific formatting or safety guidelines

serverInstructions: false or not set (default)

Use when you prefer minimal context:

• Simple tools: The tools are self-explanatory and don't need guidance
• Context optimization: You want to minimize token usage in conversations
• Manual control: You prefer to provide guidance through conversation rather than system context

Change Type

Please delete any irrelevant options.

• New feature (non-breaking change which adds functionality)

Testing

This feature was manually tested by triggering both ephemeral and standard agents with associated MCP tools and verifying that:

• Relevant MCP instructions are injected into the context.
• No instructions are injected if none are available or applicable.
• Proper logging appears for debugging and observability.
• The agent’s systemContent reflects the expected formatting.

Test Configuration:

Environment: Local development with mocked MCP server connections and instructions

Checklist

Please delete any irrelevant options.

• My code adheres to this project's style guidelines
• I have performed a self-review of my own code
• I have commented in any complex areas of my code
• I have made pertinent documentation changes
• My changes do not introduce new warnings
• I have written tests demonstrating that my changes are effective or that my feature works
• Local unit tests pass with my changes
• Any changes dependent on mine have been merged and published in downstream modules.
• A pull request for updating the documentation has been submitted.

[benverhees]

@danny-avila I see you marked this PR as work in progress, is there anything that needs to be done to move this forward?

[danny-avila]

Hi @benverhees

Yes, in my opinion, this should be a configurable pattern, rather than including instructions every time. In fact, I would even make the instructions configurable. The function definitions are already adding a lot to the context.

[benverhees]

@danny-avila I have added a serverInstructions attribute to the MCPOptionsSchema which can be configured as a string or a boolean.

The serverInstructions configuration option provides unified control over instruction behavior:

• Not set/undefined (default): No instructions will be included
• true: Use server-provided instructions
• string: Use custom instructions (overrides server-provided)
• false: Explicitly disable (same as not setting)

When to Use Each Option

serverInstructions: true

Use when the server provides good default instructions:

• Well-documented servers: The server provides comprehensive tool usage guidance
• Standard workflows: The server's instructions match your typical use cases
• Quick setup: You want to get started without writing custom instructions

serverInstructions: "custom instructions"

Use when you need specific guidance:

• Tailored workflows: Instructions specific to your application or domain
• Enhanced clarity: You can write clearer instructions than the server provides
• Missing context: The server instructions lack important details for your use case
• Compliance requirements: You need specific formatting or safety guidelines

serverInstructions: false or not set (default)

Use when you prefer minimal context:

• Simple tools: The tools are self-explanatory and don't need guidance
• Context optimization: You want to minimize token usage in conversations
• Manual control: You prefer to provide guidance through conversation rather than system context

[benverhees]

@danny-avila if this looks good to you, I'll make a pull request in the docs repo for this.

[benverhees]

@danny-avila is this something you would consider merging, or are there still some things that need improvement?

[danny-avila]

@benverhees this is definitely aligned to what I had in mind, thank you! Reviewing now.

[Copilot]

Pull Request Overview

This PR introduces the optional injection of MCP server instructions into the agent’s system context, supporting both ephemeral agents and standard agents with MCP tool associations. Key changes include:

• Adding new logic in MCPManager to store, retrieve, and format MCP server instructions.
• Updating the configuration schema in the data-provider to include the new serverInstructions option.
• Modifying the agent client to extract MCP server names and inject formatted instructions into the system context.

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
packages/mcp/src/manager.ts	Implements storage, retrieval, and formatting of server instructions
packages/data-provider/src/mcp.ts	Updates configuration schema with the serverInstructions field
api/server/controllers/agents/client.js	Incorporates injection of MCP instructions into agent systemContent

Comments suppressed due to low confidence (1)

api/server/controllers/agents/client.js:376

• [nitpick] Consider renaming 'mcpServers' to 'mcpServerNames' to better indicate that it holds server name values, which may improve clarity.

let mcpServers = [];

[danny-avila]

Looks good to me, I will merge to the dev branch but would kindly ask if appropriate docs could be updated:

https://github.com/LibreChat-AI/librechat.ai/blob/main/pages/docs/configuration/librechat_yaml/object_structure/mcp_servers.mdx

[benverhees]

Looks good to me, I will merge to the dev branch but would kindly ask if appropriate docs could be updated:

https://github.com/LibreChat-AI/librechat.ai/blob/main/pages/docs/configuration/librechat_yaml/object_structure/mcp_servers.mdx

Thanks! I will create a PR in the docs repo!

[benverhees]

@danny-avila documentation is in LibreChat-AI/librechat.ai#321