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/
  per-user-credentials-example:
    type: streamable-http
    url: "https://example.com/api/"
    headers:
      X-Auth-Token: "{{MY_SERVICE_API_KEY}}"
    customUserVars:
      MY_SERVICE_API_KEY:
        title: "My Service API Key"
        description: "Enter your personal API key for the service. You can generate one at <a href='https://myservice.example.com/developer/keys' target='_blank'>Service Developer Portal</a>."

<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. Supports various placeholder types for dynamic value substitution.
• Placeholder Support:
  • {{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.
  • {{CUSTOM_VARIABLE_NAME}}: Replaced with the value provided by the user for a variable defined in customUserVars (e.g., {{MY_API_KEY}}).
  • ${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.
• Placeholder Support:
  • {{LIBRECHAT_USER_ID}}: Replaced with the current user’s ID.
  • {{LIBRECHAT_USER_*}}: Dynamic user field placeholders (e.g., {{LIBRECHAT_USER_EMAIL}}).
  • {{CUSTOM_VARIABLE_NAME}}: Replaced with the value provided by the user for a variable defined in customUserVars (e.g., {{MY_API_KEY}}).
  • ${ENV_VAR}: Replaced with the value of the server-side environment variable {{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).

customUserVars

• Type: Object (Optional)
• Description: Defines custom variables that users can set for this MCP server. This allows administrators to specify variables (e.g., API keys, URLs) that each user must configure individually. These user-provided values can then be used in headers configuration.
• Structure:
  • The customUserVars object contains keys, where each key represents a variable name (e.g., MY_API_KEY). This name will be used in placeholders like {{MY_API_KEY}}.
  • Each variable name is an object with the following subkeys:
    • title: String (Required) - A user-friendly title for the variable, displayed in the configuration UI.
    • description: String (Optional) - A description or instructions for the variable, also displayed in the UI to guide the user. HTML can be used in this field (e.g., to create a link: <a href="https://example.com" target="_blank">More info</a>).
• Usage in headers and env:
  • Once defined under customUserVars, these variables can be referenced in the headers (for sse and streamable-http types) or env (for stdio type) sections using the {{VARIABLE_NAME}} syntax.
  • Users provide these values through the UI. These settings can be accessed in two ways:
    • From Assistant Chat Input: When selecting MCP tools for an assistant, a settings icon will appear next to configurable MCP servers in the tool selection dropdown. Clicking this icon opens a dialog to manage credentials for that server.
    
    • From Settings Panel: A dedicated “MCP Settings” section in the right panel lists all MCP servers with definable custom variables. Users can click on a server to open the configuration dialog to set or update their credentials for that specific MCP server.
    
  • These user-provided values are stored securely, associated with the individual user and the specific MCP server, and substituted at runtime.
• Example:

  customUserVars:
    MY_SERVICE_API_KEY:
      title: "My Service API Key"
      description: "Your personal API access key for My Service. Find it at <a href='https://myservice.example.com/settings/api' target='_blank'>My Service API Settings</a>."
    SOME_OTHER_VAR:
      title: "Some Other Variable"
      description: "The specific value for some other configuration (e.g., a specific path or identifier)."
  Usage in headers:

  headers:
    X-Auth-Token: "{{MY_SERVICE_API_KEY}}"
    X-Some-Other-Config: "{{SOME_OTHER_VAR}}"

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 Per-User Credentials via customUserVars

my-mcp-server:
  type: streamable-http
  url: "https://api.example-service.com/api/" # Example URL
  headers:
    X-Auth-Token: "{{API_KEY}}" # Uses the API_KEY defined below
  customUserVars:
    API_KEY: # This key will be used as {{API_KEY}} in headers/url
      title: "API Key" # This is the label shown above the input field
      description: "Get your API key <a href='https://example.com/api-keys' target='_blank'>here</a>." # This description appears below the input

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.