Cấu trúc đối tượng MCP Servers

Ví dụ

# 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
    requiresOAuth: true
    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
    # The “wrench” icon shows up if no icon is provided as it is the default rendering.
  mcp-obsidian:
    command: npx
    args:
      - -y
      - 'mcp-obsidian'
      - /path/to/obsidian/vault
  streamable-http-server:
    type: streamable-http
    url: https://example.com/api/
    proxy: '${MCP_PROXY_URL}'
  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>."
        sensitive: true
      MY_SERVICE_PROJECT:
        title: 'Project ID'
        description: 'Enter the project ID used by this service.'
        sensitive: false
  oauth-example:
    type: streamable-http
    url: https://api.example.com/mcp/
    oauth:
      authorization_url: https://example.com/oauth/authorize
      token_url: https://example.com/oauth/token
      client_id: your_client_id
      client_secret: your_client_secret
      redirect_uri: http://localhost:3080/api/mcp/oauth-example/oauth/callback
      scope: 'read execute'
  obo-example:
    type: streamable-http
    url: https://api.example.com/mcp/
    obo:
      scopes: 'api://mcp-server-id/Mcp.Tools.ReadWrite'

<serverName>

Khóa:

Subkeys

title

• Loại: Chuỗi (Tùy chọn)
• Mô tả: Tên hiển thị tùy chỉnh cho máy chủ MCP trong giao diện người dùng. Nếu không được chỉ định, tên khóa máy chủ sẽ được sử dụng.
• Ví dụ:

  my-server:
    title: 'File System Access'
    command: npx
    args: ['-y', '@modelcontextprotocol/server-filesystem']

description

• Loại: Chuỗi (Tùy chọn)
• Description: Mô tả của MCP server, được hiển thị trong giao diện người dùng để giúp người dùng hiểu mục đích và các khả năng của nó.
• Ví dụ:

  my-server:
    title: 'File System Access'
    description: 'Provides read/write access to local files and directories'
    command: npx
    args: ['-y', '@modelcontextprotocol/server-filesystem']

type

• Loại: String
• Mô tả: Chỉ định loại kết nối tới máy chủ MCP. Các tùy chọn hợp lệ là "stdio", "websocket", "streamable-http", hoặc "sse".
• Giá trị mặc định: Được xác định dựa trên sự hiện diện và định dạng của url hoặc command.

command

• Loại: String
• Mô tả: (Dành cho loại stdio) Lệnh hoặc tệp thực thi cần chạy để khởi động máy chủ MCP.

args

• Loại: Mảng các Chuỗi (Array of Strings)
• Mô tả: (Đối với loại stdio) Các đối số dòng lệnh để truyền vào command.

url

• Loại: String
• Description: (Dành cho loại websocket, streamable-http, hoặc sse) URL để kết nối với máy chủ MCP. Hỗ trợ các trình giữ chỗ trường người dùng động ({{LIBRECHAT_USER_*}}) và thay thế biến môi trường (${ENV_VAR}).
• Ghi chú:
  • Đối với loại sse, URL phải bắt đầu bằng http:// hoặc https://.
  • Đối với loại streamable-http, URL phải bắt đầu bằng http:// hoặc https://.
  • Đối với loại websocket, URL phải bắt đầu bằng ws:// hoặc wss://.

proxy

• Loại: Chuỗi (Tùy chọn, cho các loại sse và streamable-http)
• Mô tả: URL proxy gửi đi cho máy chủ MCP từ xa này. Giá trị có thể tham chiếu đến các biến môi trường bằng ${ENV_VAR}.
• Các giao thức được hỗ trợ: http://, https://, socks://, và socks5://
• Lưu ý về bảo mật: proxy được kiểm soát bởi quản trị viên. Nó phân giải các biến môi trường, nhưng không phân giải các trình giữ chỗ do người dùng kiểm soát như {{LIBRECHAT_USER_ID}} hoặc customUserVars.
• Ví dụ:

  mcpServers:
    remote-api:
      type: streamable-http
      url: https://api.example.com/mcp
      proxy: '${MCP_PROXY_URL}'

headers

• Loại: Object (Tùy chọn, dành cho các loại sse và streamable-http)
• Mô tả: Các tiêu đề tùy chỉnh để gửi kèm với yêu cầu. Hỗ trợ nhiều loại trình giữ chỗ (placeholder) khác nhau để thay thế giá trị động.
• Hỗ trợ Placeholder:
  • {{LIBRECHAT_USER_ID}}: Sẽ được thay thế bằng ID của người dùng hiện tại, cho phép hỗ trợ đa người dùng.
  • {{LIBRECHAT_USER_*}}: Các trình giữ chỗ trường người dùng động. Thay thế * bằng phiên bản VIẾT HOA của bất kỳ trường nào được cho phép.
  • {{LIBRECHAT_OPENID_*}}: Các trình giữ chỗ (placeholder) cho token/phiên OpenID dành cho các máy chủ được định nghĩa trong YAML.
  • {{LIBRECHAT_GRAPH_*}}: Các trình giữ chỗ token Microsoft Graph cho các máy chủ được định nghĩa trong YAML.
  • {{LIBRECHAT_BODY_*}}: Các trình giữ chỗ (placeholder) cho phần thân yêu cầu (request body) đối với các máy chủ được định nghĩa bằng YAML, chẳng hạn như conversationId, parentMessageId, hoặc messageId hiện tại.
  • {{CUSTOM_VARIABLE_NAME}}: Được thay thế bằng giá trị do người dùng cung cấp cho một biến được định nghĩa trong customUserVars (ví dụ: {{MY_API_KEY}}).
  • ${ENV_VAR}: Sẽ được thay thế bằng giá trị của biến môi trường {{ENV_VAR}}.

Các trình giữ chỗ trường người dùng khả dụng:

Lưu ý: Các trường bị thiếu sẽ được thay thế bằng chuỗi trống.

Các trình giữ chỗ {{LIBRECHAT_BODY_*}} có phạm vi theo yêu cầu (request-scoped). LibreChat tạo kết nối MCP cho lượt chạy hiện tại, tái sử dụng kết nối đó trong các lệnh gọi công cụ (tool calls) trong lượt chạy đó và dọn dẹp kết nối khi yêu cầu kết thúc. Các máy chủ có phạm vi theo yêu cầu bị loại trừ khỏi bộ nhớ đệm công cụ cố định (persistent tool cache) để các tiêu đề và URL cụ thể của yêu cầu không bị tái sử dụng bên ngoài lượt chạy hiện tại. Các trình giữ chỗ {{LIBRECHAT_USER_*}}, {{LIBRECHAT_OPENID_*}} và {{LIBRECHAT_GRAPH_*}} vẫn làm cho máy chủ có phạm vi theo người dùng (user-scoped), nhưng các phương thức truyền tải HTTP sẽ làm mới các tiêu đề đã phân giải trước mỗi lệnh gọi công cụ mà không tự buộc phải kết nối lại.

• Ví dụ:

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

apiKey

• Loại: Object (Tùy chọn, dành cho các loại sse và streamable-http)

• Mô tả: Cấu hình xác thực khóa API cho máy chủ MCP. Cung cấp một cách có cấu trúc để thiết lập xác thực dựa trên khóa API.

• Các khóa phụ:

  • source: String - Nơi lấy API key. Các tùy chọn:
    • "admin": Khóa API được cấu hình bởi quản trị viên (trong các biến môi trường hoặc tệp cấu hình)
    • "user": API key được người dùng cung cấp thông qua giao diện người dùng (UI)
  • authorization_type: Chuỗi - Cách khóa API được gửi trong các yêu cầu. Các tùy chọn:
    • "bearer": Được gửi dưới dạng Authorization: Bearer <key>
    • "basic": Được gửi dưới dạng Authorization: Basic <key>
    • "custom": Được gửi trong một header tùy chỉnh (yêu cầu custom_header)
  • custom_header: String - (Bắt buộc khi authorization_type là "custom") Tên tiêu đề (header) được sử dụng cho khóa API

• Ví dụ:

  # Admin-provided API key with Bearer auth
  my-server:
    type: streamable-http
    url: https://api.example.com/mcp
    apiKey:
      source: 'admin'
      authorization_type: 'bearer'
  
  # User-provided API key with custom header
  another-server:
    type: sse
    url: https://api.example.com/sse
    apiKey:
      source: 'user'
      authorization_type: 'custom'
      custom_header: 'X-API-Key'

iconPath

• Loại: Chuỗi (Tùy chọn)
• Mô tả: Xác định biểu tượng hiển thị của công cụ trong hộp thoại chọn công cụ.

chatMenu

• Loại: Boolean (Tùy chọn)
• Mô tả: Khi được đặt thành false, sẽ loại trừ máy chủ MCP khỏi menu thả xuống của khu vực trò chuyện (MCPSelect) để truy cập nhanh chóng và dễ dàng.
• Giá trị mặc định: true (Máy chủ MCP sẽ được bao gồm trong menu thả xuống của chatarea)

serverInstructions

• Loại: Boolean hoặc String (Tùy chọn)

• Mô tả: Kiểm soát cách các chỉ dẫn máy chủ MCP được đưa vào ngữ cảnh của tác nhân (agent). Các chỉ dẫn máy chủ cung cấp hướng dẫn sử dụng cấp cao cho toàn bộ máy chủ MCP, bổ sung cho các mô tả công cụ riêng lẻ.

• Các tùy chọn:

  • undefined (mặc định): Không có hướng dẫn nào được bao gồm
  • true: Sử dụng hướng dẫn do máy chủ cung cấp (nếu có) - lý tưởng cho các máy chủ có tài liệu đầy đủ với hướng dẫn toàn diện
  • false: Tắt hướng dẫn một cách rõ ràng - hữu ích để tiết kiệm token ngữ cảnh hoặc khi các công cụ đã tự giải thích rõ ràng
  • string: Sử dụng các hướng dẫn tùy chỉnh (ghi đè lên các hướng dẫn do máy chủ cung cấp) - phù hợp nhất cho các quy trình làm việc cụ thể của ứng dụng hoặc khi các hướng dẫn từ máy chủ không đủ đáp ứng

• Giá trị mặc định: undefined (không bao gồm hướng dẫn)

• Ghi chú:

  • Các hướng dẫn sẽ được tự động chèn vào khi serverInstructions được cấu hình và các công cụ của máy chủ khả dụng cho tác nhân.
  • Nhiều máy chủ có thể đóng góp các hướng dẫn vào ngữ cảnh của tác nhân (agent context)

• Ví dụ:

  # 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

• Loại: Object (Tùy chọn, chỉ dành cho loại stdio)
• Mô tả: Các biến môi trường để sử dụng khi khởi tạo tiến trình.
• Hỗ trợ Placeholder:
  • {{LIBRECHAT_USER_ID}}: Được thay thế bằng ID của người dùng hiện tại.
  • {{LIBRECHAT_USER_*}}: Các trình giữ chỗ trường người dùng động (ví dụ: {{LIBRECHAT_USER_EMAIL}}).
  • {{CUSTOM_VARIABLE_NAME}}: Được thay thế bằng giá trị do người dùng cung cấp cho một biến được định nghĩa trong customUserVars (ví dụ: {{MY_API_KEY}}).
  • ${ENV_VAR}: Được thay thế bằng giá trị của biến môi trường phía máy chủ {{ENV_VAR}}.

timeout

• Loại: Số nguyên (Tùy chọn)
• Mô tả: Thời gian chờ tính bằng mili giây cho các yêu cầu máy chủ MCP. Phải là một số nguyên không âm.
• Giá trị mặc định: 30000 (30 giây)

initTimeout

• Loại: Số nguyên (Tùy chọn)
• Mô tả: Thời gian chờ tính bằng mili giây để khởi tạo máy chủ MCP. Phải là một số nguyên không âm.
• Giá trị mặc định: 10000 (10 giây)

requiresOAuth

• Loại: Boolean (Tùy chọn, chỉ dành cho các phương thức truyền tải từ xa: sse, streamable-http, websocket)
• Mô tả: Liệu máy chủ này có yêu cầu xác thực OAuth hay không. Nếu không được chỉ định, giá trị này sẽ được tự động phát hiện trong quá trình khởi động máy chủ. Mặc dù là tùy chọn, nhưng tốt nhất bạn nên đặt giá trị này một cách rõ ràng nếu bạn biết máy chủ có yêu cầu OAuth hay không.
• Giá trị mặc định: Tự động phát hiện nếu không được chỉ định
• Ghi chú:
  • Áp dụng cho các phương thức truyền tải từ xa (dựa trên URL): sse, streamable-http, và websocket. Nó không có tác dụng đối với các máy chủ stdio, vốn không có URL để xác thực.
  • Tính năng tự động phát hiện diễn ra trong quá trình khởi động máy chủ, điều này có thể làm tăng thời gian khởi tạo.
  • Cấu hình tường minh giúp cải thiện hiệu suất khởi động bằng cách bỏ qua quá trình phát hiện.
  • Đặt requiresOAuth: false cho các máy chủ chỉ được bảo vệ bằng tiêu đề Authorization tĩnh (ví dụ: khóa API Bearer). Tính năng tự động phát hiện sẽ thăm dò máy chủ mà không có các tiêu đề đã cấu hình của bạn, vì vậy một máy chủ phản hồi 401 kèm theo yêu cầu WWW-Authenticate: Bearer có thể bị phân loại sai là được bảo vệ bằng OAuth; cờ này sẽ bỏ qua quá trình thăm dò đó và cho phép tiêu đề tĩnh của bạn xác thực kết nối một cách bình thường.
  • Hoạt động với các biến môi trường MCP OAuth (MCP_OAUTH_ON_AUTH_ERROR, MCP_OAUTH_DETECTION_TIMEOUT, MCP_OAUTH_HANDLING_TIMEOUT, MCP_OAUTH_FLOW_TTL) để tăng cường quản lý kết nối

stderr

• Loại: Chuỗi hoặc Số nguyên (Tùy chọn, chỉ dành cho loại stdio)
• Mô tả: Cách xử lý stderr của tiến trình con. Điều này khớp với ngữ nghĩa của child_process.spawn trong Node. Các giá trị chuỗi hợp lệ: "pipe", "ignore", "inherit". Ngoài ra, một số nguyên không âm có thể được sử dụng làm bộ mô tả tệp (file descriptor).
• Giá trị mặc định: "inherit" (các thông báo gửi đến stderr sẽ được in ra stderr của tiến trình cha).

customUserVars

• Loại: Đối tượng (Tùy chọn)
• Mô tả: Xác định các biến tùy chỉnh mà người dùng có thể thiết lập cho máy chủ MCP này. Điều này cho phép quản trị viên chỉ định các biến (ví dụ: khóa API, URL) mà mỗi người dùng phải tự cấu hình riêng. Các giá trị do người dùng cung cấp này sau đó có thể được sử dụng trong cấu hình headers hoặc env. Các máy chủ có customUserVars sẽ tự động bị loại trừ khỏi các kết nối ở cấp ứng dụng, đảm bảo thông tin xác thực của từng người dùng luôn được phân giải tại thời điểm chạy.
• Cấu trúc:
  • Đối tượng customUserVars chứa các khóa, trong đó mỗi khóa đại diện cho một tên biến (ví dụ: MY_API_KEY). Tên này sẽ được sử dụng trong các trình giữ chỗ như {{MY_API_KEY}}.
  • Mỗi tên biến là một đối tượng với các khóa phụ sau:
    • title: String (Bắt buộc) - Một tiêu đề thân thiện với người dùng cho biến, được hiển thị trong giao diện cấu hình.
    • 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>).
    • sensitive: Boolean (Tùy chọn) - Kiểm soát xem giá trị có được coi là bí mật và bị ẩn trong giao diện người dùng (UI) hay không. Mặc định là hành vi ẩn/bí mật khi bị bỏ qua; hãy đặt thành false cho các trường không phải là bí mật như ID dự án hoặc URL cơ sở.
• Sử dụng trong headers và env:
  • Sau khi được xác định trong customUserVars, các biến này có thể được tham chiếu trong các phần headers (đối với các loại sse và streamable-http) hoặc env (đối với loại stdio) bằng cách sử dụng cú pháp {{VARIABLE_NAME}}.
  • Người dùng cung cấp các giá trị này thông qua giao diện người dùng (UI). Các cài đặt này có thể được truy cập theo hai cách:
    • Từ Đầu vào Trò chuyện của Trợ lý: Khi chọn các công cụ MCP cho một trợ lý, một biểu tượng cài đặt sẽ xuất hiện bên cạnh các máy chủ MCP có thể cấu hình trong menu thả xuống chọn công cụ. Nhấp vào biểu tượng này sẽ mở ra một hộp thoại để quản lý thông tin xác thực cho máy chủ đó.
    • Từ Bảng Cài đặt: Một phần "MCP Settings" chuyên dụng trong bảng điều khiển bên phải liệt kê tất cả các máy chủ MCP với các biến tùy chỉnh có thể xác định. Người dùng có thể nhấp vào một máy chủ để mở hộp thoại cấu hình nhằm thiết lập hoặc cập nhật thông tin xác thực cho máy chủ MCP cụ thể đó.
  • Các giá trị do người dùng cung cấp này được lưu trữ an toàn, gắn liền với từng người dùng cụ thể và máy chủ MCP cụ thể, đồng thời được thay thế tại thời điểm chạy (runtime).
• Ví dụ:

  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>."
      sensitive: true
    SOME_OTHER_VAR:
      title: 'Some Other Variable'
      description: 'The specific value for some other configuration (e.g., a specific path or identifier).'
      sensitive: false

  Sử dụng trong headers:

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

  Cách sử dụng trong env (cho loại stdio):

  env:
    API_KEY: '{{MY_SERVICE_API_KEY}}'

obo

• Loại: Object (Tùy chọn, chỉ dành cho các loại sse và streamable-http)
• Mô tả: Cấu hình trao đổi token On-Behalf-Of OAuth 2.0 cho một MCP server. LibreChat thực hiện trao đổi token truy cập OpenID của người dùng đã đăng nhập để lấy token ủy quyền hạ nguồn với các phạm vi (scopes) đã cấu hình, sau đó chuyển tiếp token đó đến MCP server dưới dạng header Authorization: Bearer ....
• Các khóa con bắt buộc:
  • scopes: Chuỗi - Các phạm vi (scopes) không rỗng được yêu cầu cho việc trao đổi token hạ nguồn.
• Xác thực:
  • obo chỉ hợp lệ cho các máy chủ MCP sse và streamable-http.
  • obo bị từ chối đối với các máy chủ stdio và websocket.
  • Người dùng cần quyền MCP_SERVERS.CONFIGURE_OBO để cấu hình trường này. Hãy khởi tạo nó bằng interface.mcpServers.configureObo hoặc quản lý nó từ bảng điều khiển quản trị.
• Điều kiện tiên quyết:
  • Xác thực OpenID phải được cấu hình với các access token có thể tái sử dụng.
  • Nhà cung cấp danh tính và ứng dụng hạ nguồn của bạn phải cho phép phạm vi được ủy quyền đã yêu cầu.
• Ví dụ:

  mcpServers:
    enterprise-tools:
      type: streamable-http
      url: https://api.example.com/mcp/
      obo:
        scopes: 'api://mcp-server-id/Mcp.Tools.ReadWrite'

Xem OpenID Connect Token Reuse và SharePoint Integration để biết các thiết lập liên quan đến việc sử dụng lại token và token được ủy quyền.

oauth

• Loại: Đối tượng (Tùy chọn)
• Mô tả: Cấu hình OAuth2 để xác thực với máy chủ MCP. Khi được cấu hình, người dùng sẽ được nhắc xác thực thông qua luồng OAuth trước khi máy chủ MCP có thể được sử dụng. Nếu không cung cấp client id & client secret, Dynamic Client Registration (DCR) sẽ được sử dụng.
• Các khóa con bắt buộc:
  • authorization_url: String - URL của endpoint ủy quyền OAuth
  • token_url: String - URL của endpoint token OAuth
  • client_id: String - Định danh khách hàng OAuth
  • client_secret: Chuỗi - OAuth client secret
  • redirect_uri: String - OAuth redirect URI (ví dụ: http://localhost:3080/api/mcp/${serverName}/oauth/callback)
  • scope: String - Các phạm vi OAuth (phân cách bằng dấu cách)
• Các khóa con tùy chọn:
  • grant_types_supported: Mảng các Chuỗi - Các loại grant được hỗ trợ (mặc định là ["authorization_code", "refresh_token"])
  • token_endpoint_auth_methods_supported: Mảng các Chuỗi - Các phương thức xác thực điểm cuối token được hỗ trợ (mặc định là ["client_secret_basic", "client_secret_post"])
  • token_exchange_method: String - Phương thức yêu cầu trao đổi token. Sử dụng default_post cho các nhà cung cấp yêu cầu thông tin xác thực OAuth client trong phần thân POST.
  • response_types_supported: Mảng các Chuỗi - Các loại phản hồi được hỗ trợ (mặc định là ["code"])
  • code_challenge_methods_supported: Mảng các Chuỗi - Các phương thức thử thách mã PKCE được hỗ trợ (mặc định là ["S256", "plain"])
  • skip_code_challenge_check: Boolean - Bỏ qua việc kiểm tra xem nhà cung cấp OAuth có quảng bá hỗ trợ PKCE hay không. Hữu ích cho các nhà cung cấp như AWS Cognito hỗ trợ S256 nhưng không quảng bá điều đó trong siêu dữ liệu của họ. (mặc định là false)
• Các biến môi trường: Các trường URL OAuth được định nghĩa trong YAML, bao gồm authorization_url, token_url, redirect_uri và revocation_endpoint, có thể sử dụng các tham chiếu ${ENV_VAR}. LibreChat sẽ phân giải giá trị môi trường trước khi xác thực URL. Các URL điểm cuối OAuth do người dùng quản lý được gửi thông qua giao diện người dùng phải là các URL cố định và sẽ từ chối các trình giữ chỗ ${ENV_VAR}.
• Ví dụ:

  oauth-api-server:
    authorization_url: https://api.example.com/oauth/authorize
    token_url: https://api.example.com/oauth/token
    client_id: your_client_id
    client_secret: your_client_secret
    redirect_uri: http://localhost:3080/api/mcp/oauth-api-server/oauth/callback
    scope: 'read execute'
    grant_types_supported: ['authorization_code', 'refresh_token']
    token_endpoint_auth_methods_supported: ['client_secret_post']
    token_exchange_method: default_post
    response_types_supported: ['code']
    code_challenge_methods_supported: ['S256', 'plain']

oauth_headers

• Loại: Đối tượng (Tùy chọn)
• Mô tả: Các header được sử dụng cụ thể cho các yêu cầu luồng OAuth. Các header này được sử dụng trong quá trình xác thực OAuth, chẳng hạn như đăng ký client động và trao đổi token, và không được gửi trong quá trình giao tiếp thông thường với MCP server.
• Các trường hợp sử dụng phổ biến:
  • Thêm xác thực vào các endpoint đăng ký client động, ví dụ như Authorization: Bearer ${DCR_API_KEY}
  • Bao gồm các tiêu đề (headers) tùy chỉnh dành riêng cho nhà cung cấp cần thiết cho các luồng OAuth
  • Thiết lập các header cần thiết cho các endpoint token OAuth
• Các khác biệt chính so với headers:
  • headers: Được gửi kèm với các yêu cầu MCP server thông thường sau khi quá trình xác thực hoàn tất
  • oauth_headers: Chỉ được gửi trong các luồng xác thực OAuth
• Ví dụ:

  oauth_headers:
    Authorization: "Bearer ${DCR_API_KEY}"
    X-Custom-Header: "custom_value"

startup

• Loại: Boolean (Tùy chọn)
• Mô tả: Khi được đặt thành false, máy chủ MCP này sẽ không được kết nối khi khởi động ứng dụng. Điều này hữu ích cho các máy chủ yêu cầu người dùng nhập liệu hoặc cấu hình trước khi kết nối, hoặc cho các trường hợp bạn muốn kiểm soát thời điểm máy chủ được khởi tạo.
• Giá trị mặc định: true
• Ví dụ:

  mcpServers:
    my-mcp-server:
      type: streamable-http
      url: 'https://api.example.com/mcp/'
      startup: false

Ghi chú

• Suy luận kiểu:
  • Nếu type bị bỏ qua:
    • Nếu url được chỉ định và bắt đầu bằng http:// hoặc https://, type sẽ mặc định là sse.
    • Nếu url được chỉ định và bắt đầu bằng ws:// hoặc wss://, type sẽ mặc định là websocket.
    • Nếu command được chỉ định, type sẽ mặc định là stdio.
• Các loại kết nối:
  • stdio: Khởi chạy một MCP server dưới dạng tiến trình con (child process) và giao tiếp thông qua đầu vào/đầu ra tiêu chuẩn (standard input/output).
  • websocket: Kết nối tới một máy chủ MCP bên ngoài thông qua WebSocket.
  • sse: Kết nối tới một máy chủ MCP bên ngoài thông qua Server-Sent Events (SSE).
  • streamable-http: Kết nối tới một máy chủ MCP bên ngoài thông qua HTTP với hỗ trợ phản hồi dạng luồng (streaming).
• Các địa chỉ nội bộ/cục bộ:
  • Quan trọng: Các máy chủ MCP sử dụng địa chỉ IP nội bộ (ví dụ: 172.24.1.165, 192.168.1.100) hoặc tên miền cục bộ (ví dụ: mcp-server, host.docker.internal) phải được cho phép một cách rõ ràng. Hãy sử dụng mcpSettings.allowedAddresses cho các dịch vụ host:port riêng tư cụ thể khi bạn muốn các đích đến công khai vẫn có thể truy cập được, hoặc mcpSettings.allowedDomains khi bạn muốn thiết lập danh sách trắng nghiêm ngặt.
  • Xem MCP Settings để biết chi tiết cấu hình.

Các ví dụ

Cấu hình với các địa chỉ nội bộ

Khi sử dụng các máy chủ MCP nội bộ/cục bộ và không cần danh sách trắng tên miền nghiêm ngặt, hãy cấu hình mcpSettings.allowedAddresses với chính xác host và port:

# MCP Settings - Required for internal/local addresses
mcpSettings:
  allowedAddresses:
    - '172.24.1.165:8000' # Internal IP and port
    - 'mcp-prod:8001' # Docker container and port
    - 'host.docker.internal:8080' # Docker host and port

# MCP Servers - Individual configurations
mcpServers:
  prod-mcp:
    type: streamable-http
    url: http://172.24.1.165:8000/mcp
    timeout: 120000

  test-mcp:
    type: streamable-http
    url: http://mcp-prod:8001/mcp
    timeout: 120000

Máy chủ MCP stdio

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

Máy chủ MCP sse

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

Máy chủ MCP websocket

myWebSocketServer:
  url: ws://localhost:8080

Máy chủ MCP streamable-http

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

Máy chủ MCP với các trường người dùng động

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

Máy chủ MCP với thông tin xác thực theo người dùng thông qua 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

LƯU Ý Xem MCP Server Initialization để biết thêm thông tin về khởi tạo server dựa trên giao diện người dùng.

MCP Server với biểu tượng tùy chỉnh

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 với xác thực OAuth

oauth-api-server:
  type: streamable-http
  url: https://api.example.com/mcp/
  oauth:
    authorization_url: https://api.example.com/oauth/authorize
    token_url: https://api.example.com/oauth/token
    client_id: your_client_id
    client_secret: your_client_secret
    redirect_uri: http://localhost:3080/api/mcp/oauth-api-server/oauth/callback
    scope: 'read execute'
  oauth_headers:
    X-Custom-Header: 'custom_value'

MCP Server với 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

Máy chủ MCP hỗ trợ OAuth (Legacy requiresOAuth)

composio-googlesheets:
  type: sse
  url: https://mcp.composio.dev/googlesheets/sse-endpoint
  requiresOAuth: true
  headers:
    X-User-ID: '{{LIBRECHAT_USER_ID}}'
    X-API-Key: '${COMPOSIO_API_KEY}'
  timeout: 45000
  initTimeout: 15000

Các biến môi trường liên quan (Tùy chọn):

# OAuth configuration for MCP servers
MCP_OAUTH_ON_AUTH_ERROR=true
MCP_OAUTH_DETECTION_TIMEOUT=10000
MCP_OAUTH_HANDLING_TIMEOUT=600000
MCP_OAUTH_FLOW_TTL=900000

# API key for the service
COMPOSIO_API_KEY=your_composio_api_key_here

Nhập cấu hình MCP Server

Các cấu hình mcpServers cho phép LibreChat tương tác linh hoạt với nhiều máy chủ MCP khác nhau, vốn có thể thực hiện các tác vụ chuyên biệt hoặc cung cấp các chức năng cụ thể trong ứng dụng. Cách tiếp cận theo mô-đun này giúp việc mở rộng các khả năng của ứng dụng trở nên dễ dàng hơn bằng cách chỉ cần thêm hoặc sửa đổi các cấu hình máy chủ.

Thông tin bổ sung

• Hành vi mặc định:
  • Quá trình khởi tạo diễn ra khi khởi động và ứng dụng phải được khởi động lại để các thay đổi có hiệu lực.
  • Nếu cả url và command đều được chỉ định, type phải được xác định rõ ràng để tránh gây nhầm lẫn.
• Hỗ trợ đa người dùng:
  • MCPManager hiện đã hỗ trợ các kết nối riêng biệt ở cấp người dùng và cấp ứng dụng, cho phép quản lý kết nối phù hợp cho từng người dùng.
  • Các kết nối người dùng được theo dõi và quản lý riêng biệt, với quy trình thiết lập và dọn dẹp phù hợp.
  • Sử dụng các trình giữ chỗ trường người dùng động trong tiêu đề, URL và biến môi trường:
    • {{LIBRECHAT_USER_ID}} - Định danh duy nhất của người dùng
    • {{LIBRECHAT_USER_EMAIL}} - Địa chỉ email của người dùng
    • {{LIBRECHAT_USER_USERNAME}} - Tên người dùng của người dùng
    • {{LIBRECHAT_USER_ROLE}} - Vai trò của người dùng (ví dụ: "user", "admin")
    • Và nhiều trường khác (xem phần headers để biết danh sách đầy đủ)
• Quản lý trạng thái chờ của người dùng:
  • Các kết nối của người dùng được giám sát hoạt động và sẽ bị ngắt sau 15 phút không hoạt động.
• Các biến môi trường:
  • Trong env (đối với loại stdio): Hữu ích để thiết lập các môi trường chạy hoặc cấu hình cụ thể cần thiết cho tiến trình máy chủ MCP.
  • Trong headers (đối với các loại sse và streamable-http): Sử dụng cú pháp ${ENV_VAR} để tham chiếu đến các biến môi trường trong giá trị tiêu đề.
• Các trường người dùng động:
  • Các trình giữ chỗ (placeholders) cho trường người dùng sẽ được thay thế tại thời điểm chạy bằng thông tin của người dùng đã xác thực.
  • Chỉ các trường không nhạy cảm mới khả dụng (mật khẩu và các dữ liệu nhạy cảm khác đã được loại trừ)
  • Các trường bị thiếu sẽ mặc định là chuỗi rỗng
  • Các trường Boolean được chuyển đổi thành các biểu diễn chuỗi ("true" hoặc "false")
• Xử lý lỗi (stderr):
  • Việc cấu hình stderr cho phép bạn quản lý cách xử lý các thông báo lỗi từ tiến trình MCP server. Giá trị mặc định "inherit" có nghĩa là các lỗi sẽ được in ra stderr của tiến trình cha.
• Hướng dẫn Máy chủ:
  • Các hướng dẫn sẽ được tự động chèn vào tin nhắn hệ thống của tác nhân (agent) khi các công cụ máy chủ MCP được sử dụng.
  • Các hướng dẫn tùy chỉnh (giá trị chuỗi) sẽ được ưu tiên hơn các hướng dẫn do máy chủ cung cấp
  • Nhiều MCP server có thể đóng góp các hướng dẫn riêng của chúng vào ngữ cảnh của agent
  • Các hướng dẫn chỉ được bao gồm khi các công cụ của máy chủ MCP tương ứng thực sự khả dụng cho tác nhân.
• Xác thực OAuth:
  • Luồng OAuth2 được hỗ trợ để xác thực bảo mật với các máy chủ MCP.
  • Người dùng sẽ được yêu cầu xác thực thông qua OAuth trước khi có thể sử dụng máy chủ MCP.

Tài liệu tham khảo

• Tài liệu Model Context Protocol (MCP)
• Đặc tả giao thức truyền tải MCP
• Node.js child_process.spawn

Bằng cách định cấu hình đúng mcpServers trong librechat.yaml của bạn, bạn có thể nâng cao chức năng của LibreChat và tích hợp các công cụ cũng như dịch vụ tùy chỉnh một cách liền mạch.