MCP Server Instructions set to true does not work as per documentation (true is taken as a string)

[fstadt]

What happened?

Version: LibreChat v0.8.0-rc3

MCP-Server-Config:

  myserver:
    type: streamable-http
    url: "http://host.docker.internal:3000/mcp"
    serverInstructions: true
    oauth:
      ...

When I ask the llm in a chat, it claims (most of the time) that the server instructions for this mcp server are "true" and sometimes also lists summaries of the tool descriptions. When not setting the serverInstructions config key, it will never give that answer. In any case, it never returns the server description field from the mcp server.

Looking at the source code, it seems to me that when the server instructions are not a string, then a function is called to fetch them. This function is then taking the instructions which were previously rejected and returns them.

As per the documentation, serverInstructions set to true should retrieve the instructions from the mcp server - probably the server description field.

Version Information

sha256:96dee0822f1fc6639dcb966d8501363fe5f1d6790eb8b65fdadd1a2da98e7ea8

Steps to Reproduce

1. Set up an mcp server with a description
2. Configure that mcp server in librechat and set serverInstructions to true
3. While the mcp is enabled in the conversation, ask the llm about the server Instructions.

What browsers are you seeing the problem on?

No response

Relevant log output

2025-09-18 23:40:08 2025-09-18 21:40:08 info: [MCP][myserver] -------------------------------------------------┐
2025-09-18 23:40:08 2025-09-18 21:40:08 info: [MCP][myserver] URL: http://host.docker.internal:3000/mcp
2025-09-18 23:40:08 2025-09-18 21:40:08 info: [MCP][myserver] OAuth Required: true
2025-09-18 23:40:08 2025-09-18 21:40:08 info: [MCP][myserver] Capabilities: undefined
2025-09-18 23:40:08 2025-09-18 21:40:08 info: [MCP][myserver] Tools: undefined
2025-09-18 23:40:08 2025-09-18 21:40:08 info: [MCP][myserver] Server Instructions: true
2025-09-18 23:40:08 2025-09-18 21:40:08 info: [MCP][myserver] -------------------------------------------------┘

Screenshots

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

[danny-avila]

It is working as intended for me. For example, an MCP server without instructions, but using serverInstructions: true:

  tavily-search:
    serverInstructions: true
    type: streamable-http
    url: "https://mcp.tavily.com/mcp/?tavilyApiKey=${TAVILY_API_KEY}"
    initTimeout: 20000
    timeout: 120000

server output:

2025-09-18 18:56:57 warn: [MCP][tavily-search] No server instructions available
2025-09-18 18:56:59 info: [MCP][tavily-search] -------------------------------------------------┐
2025-09-18 18:56:59 info: [MCP][tavily-search] URL: https://mcp.tavily.com/mcp/
2025-09-18 18:56:59 info: [MCP][tavily-search] OAuth Required: false
2025-09-18 18:56:59 info: [MCP][tavily-search] Capabilities: {"experimental":{},"prompts":{"listChanged":true},"resources":{"subscribe":false,"listChanged":true},"tools":{"listChanged":true}}
2025-09-18 18:56:59 info: [MCP][tavily-search] Tools: tavily_search, tavily_extract, tavily_crawl, tavily_map
2025-09-18 18:56:59 info: [MCP][tavily-search] Server Instructions: undefined
2025-09-18 18:56:59 info: [MCP][tavily-search] -------------------------------------------------┘

---

Now one with instructions, also using serverInstructions: true (this is my own custom server):

  customMCP:
    serverInstructions: true
    type: http
    url: "http://localhost:3001/mcp"
    timeout: 1900000
    initTimeout: 1800000

2025-09-18 19:03:26 info: [MCP][customMCP] -------------------------------------------------┐
2025-09-18 19:03:26 info: [MCP][customMCP] URL: http://localhost:3001/mcp
2025-09-18 19:03:26 info: [MCP][customMCP] OAuth Required: false
2025-09-18 19:03:26 info: [MCP][customMCP] Capabilities: {"tools":{}}
2025-09-18 19:03:26 info: [MCP][customMCP] Tools: hello_world, get_server_info, long_running_test, slow_test
2025-09-18 19:03:26 info: [MCP][customMCP] Server Instructions: A simple test MCP server implemented with Streamable HTTP transport. Supports basic tools and long-running operations with progress updates.
2025-09-18 19:03:26 info: [MCP][customMCP] -------------------------------------------------┘

We can see it fetched here in the code:

---

---

How are you setting the LC yaml-based config? Depending on how/where it's getting configured, it's possible the true field is being interpreted as a string. By default, using a regular yaml file will interpret the above settings as boolean, however.

Are you using a librechat.yaml file, fetching the config, or using an alternative deployment template?

That will help understand the root of the issue.

We can also look into preventing the edge case altogether by coercing "true" (string) to true (boolean)

[fstadt]

I'm setting it using a librechat.yaml file with a bind mount into the docker container. Pretty standard setup with the docker-compose and .override provided - my override just contains this:

services:

# # USE LIBRECHAT CONFIG FILE
   api:
     volumes:
     - type: bind
       source: ./librechat.yaml
       target: /app/librechat.yaml
     env_file:
       - .env

I can also confirm that the bind mount works and the config file arrives as expected.

Am I correct in that the "description" field of the mcp server is used as server instructions? The docs are not very precise about that. If not, maybe that is the issue - the issue would be in the implementation of my mcp server then.

I was trying to look that up in the code but was a bit confused because the part you showed from the MCPServerRegistry used the client to fetch it, but that code then looks it up in the MCPServerRegistry, which is what triggered the fetch in the first case because of the value being true. Didn't feel like I fully understood the code structure there though.

I didn't check yet with a simpler mcp server without oauth though, I can check with that once I get around to it just to narrow things down.

[danny-avila]

Am I correct in that the "description" field of the mcp server is used as server instructions?

No, there's a specific instructions field for MCP server definition: https://modelcontextprotocol.io/specification/2025-06-18/schema#initializeresult

On MCP-server-side, and in TypeScript, you define it like this:

  const server = new Server(
    {
      name: "simple-streamable-http-mcp-server",
      version: "1.0.0",
    },
    {
      instructions: "A simple test MCP server implemented with Streamable HTTP transport. Supports basic tools and long-running operations with progress updates.",
      capabilities: {
        tools: {}
      }
    }
  );

Try now by updating your instance, since #9703 should help resolve this for you if the value becomes "true" as string for whatever reason.

[fstadt]

I tried updating my instance, even compiled from source to make sure I'm running a version with your fix. I also added the instructions into the instructions field (cannot believe I overlooked that when browsing the sdk while specifically looking for where to put server instructions...).

Strangely, I still get "true" for mcp server instructions. Maybe I should check against some sort of reference mcp server implementation to ensure it's not my code? Maybe my oauth implementation (basically return 401 if no valid bearer token is presented - librechat is doing all the oauth flow in advance) or the session handling code is messing things up somehow.

[mnaser]

I'm running into the same issue, the MCP server is built using the MCP TypeScript SDK. It does use OAuth so I suspect that's the common thing, I'm trying to identify if i can figure out where the issue is in the code.

[mnaser]

I have fixed this in #11193

[joelw]

One other issue I just came across - if you have startup: false set in the MCP configuration for whatever reason, it seems like it does not fetch the instructions at startup, nor later on.

Easy workaround is to not specify startup!