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}"
    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
    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
  streamable-http-server:
    type: streamable-http
    url: https://example.com/api/

<serverName>

Key:

Subkeys

type

• Type: String
• Description: Specifies the connection type to the MCP server. Valid options are "stdio", "websocket", "streamable-http", 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, 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://.
  • For websocket type, the URL must start with ws:// or wss://.

headers

• Type: Object (Optional, for sse and streamable-http types)
• 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:

Note: Missing fields will be replaced with empty strings.

• Example:

  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}"

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)

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:

  # 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)
• 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

• 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).
  • streamable-http: Connects to an external MCP server via HTTP with support for streaming responses.

Examples

stdio MCP Server

puppeteer:
  type: stdio
  command: npx
  args:
    - -y
    - "@modelcontextprotocol/server-puppeteer"
  timeout: 30000
  initTimeout: 10000
  env:
    NODE_ENV: "production"
    USER_EMAIL: "{{LIBRECHAT_USER_EMAIL}}"
    USER_ROLE: "{{LIBRECHAT_USER_ROLE}}"
  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

streamable-http MCP Server

streamable-http-server:
  type: streamable-http
  url: https://example.com/api/
  headers:
    X-User-ID: "{{LIBRECHAT_USER_ID}}"
    X-API-Key: "${SOME_API_KEY}"

MCP Server with Dynamic 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

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

MCP Server with Server 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

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 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.
• 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

• Model Context Protocol (MCP) Documentation
• MCP Transports Specification
• 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.