MCP Servers Object Structure

Example

# Example MCP Servers Object Structure
mcpServers:
  everything:
    # type: sse # type can optionally be omitted
    url: http://localhost:3001/sse
  googlesheets:
    type: sse
    url: https://mcp.composio.dev/googlesheets/some-endpoint
    headers:
      X-User-ID: "{{LIBRECHAT_USER_ID}}"
      X-API-Key: "${SOME_API_KEY}"
  puppeteer:
    type: stdio
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-puppeteer"
  filesystem:
    # type: stdio
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-filesystem"
      - /home/user/LibreChat/
    iconPath: /home/user/LibreChat/client/public/assets/logo.svg
  mcp-obsidian:
    command: npx
    args:
      - -y
      - "mcp-obsidian"
      - /path/to/obsidian/vault

<serverName>

Key:

Subkeys

type

• Type: String
• Description: Specifies the connection type to the MCP server. Valid options are "stdio", "websocket", or "sse".
• Default Value: Determined based on the presence and format of url or command.

command

• Type: String
• Description: (For stdio type) The command or executable to run to start the MCP server.

args

• Type: Array of Strings
• Description: (For stdio type) Command line arguments to pass to the command.

url

• Type: String
• Description: (For websocket or sse type) The URL to connect to the MCP server.
• Notes:
  • For sse type, the URL must start with http:// or https://.
  • For websocket type, the URL must start with ws:// or wss://.

headers

• Type: Object (Optional, sse type only)
• Description: Custom headers to send with the SSE request.
• Special Values:
  • {{LIBRECHAT_USER_ID}}: Will be replaced with the current user’s ID, enabling multi-user support.
  • ${ENV_VAR}: Will be replaced with the value of the environment variable ENV_VAR.
• Example:

  headers:
    X-User-ID: "{{LIBRECHAT_USER_ID}}"
    X-API-Key: "${SOME_API_KEY}"
    Authorization: "Bearer ${SOME_AUTH_TOKEN}"

iconPath

• Type: String (Optional)
• Description: Defines the tool’s display icon shown in the tool selection dialog.

chatMenu

• Type: Boolean (Optional)
• 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)

env

• Type: Object (Optional, stdio type only)
• Description: Environment variables to use when spawning the process.

timeout

• Type: Number (Optional)
• Description: Timeout in milliseconds for MCP server requests. Determines how long to wait for a response for tool requests.
• Default Value: 30000 (30 seconds)

initTimeout

• Type: Number (Optional)
• Description: Timeout in milliseconds for MCP server initialization. Determines how long to wait for the server to initialize.
• Default Value: 10000 (10 seconds)

stderr

• Type: String or Stream or Number (Optional, stdio type only)
• Description: How to handle stderr of the child process. This matches the semantics of Node’s child_process.spawn.
• Default Value: "inherit" (messages to stderr will be printed to the parent process’s stderr).

Notes

• Type Inference:
  • If type is omitted:
    • If url is specified and starts with http:// or https://, type defaults to sse.
    • If url is specified and starts with ws:// or wss://, type defaults to websocket.
    • If command is specified, type defaults to stdio.
• Connection Types:
  • stdio: Starts an MCP server as a child process and communicates via standard input/output.
  • websocket: Connects to an external MCP server via WebSocket.
  • sse: Connects to an external MCP server via Server-Sent Events (SSE).

Examples

stdio MCP Server

puppeteer:
  type: stdio
  command: npx
  args:
    - -y
    - "@modelcontextprotocol/server-puppeteer"
  timeout: 30000
  initTimeout: 10000
  env:
    NODE_ENV: "production"
  stderr: inherit

sse MCP Server

everything:
  url: http://localhost:3001/sse
  headers:
    X-User-ID: "{{LIBRECHAT_USER_ID}}"
    X-API-Key: "${SOME_API_KEY}"

websocket MCP Server

myWebSocketServer:
  url: ws://localhost:8080

MCP Server with Custom Icon

filesystem:
  command: npx
  args:
    - -y
    - "@modelcontextprotocol/server-filesystem"
    - /home/user/LibreChat/
  iconPath: /home/user/LibreChat/client/public/assets/logo.svg
  chatMenu: false  # Exclude from chatarea dropdown

Importing MCP Server Configurations

The mcpServers configurations allow LibreChat to dynamically interact with various MCP servers, which can perform specialized tasks or provide specific functionalities within the application. This modular approach facilitates extending the application’s capabilities by simply adding or modifying server configurations.

Additional Information

• Default Behavior:
  • Initialization happens at startup, and the app must be restarted for changes to take effect.
  • If both url and command are specified, the type must be explicitly defined to avoid ambiguity.
• 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.
• 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 type): 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.

References

• Model Context Protocol (MCP) Documentation
• Node.js child_process.spawn

By properly configuring the mcpServers in your librechat.yaml, you can enhance LibreChat’s functionality and integrate custom tools and services seamlessly.