MCP

Model Context Protocol (MCP) là một giao thức mở giúp tiêu chuẩn hóa cách các ứng dụng cung cấp ngữ cảnh cho các Mô hình Ngôn ngữ Lớn (LLMs). Hãy coi MCP như là "USB-C của AI" - cũng giống như USB-C cung cấp một tiêu chuẩn kết nối phổ quát cho các thiết bị điện tử, MCP cung cấp một cách thức tiêu chuẩn hóa để kết nối các mô hình AI với nhiều công cụ, nguồn dữ liệu và dịch vụ đa dạng.

LibreChat tận dụng MCP để mở rộng đáng kể khả năng của các AI agent, cho phép bạn tích hợp mọi thứ từ quyền truy cập hệ thống tệp, trình duyệt web, các API chuyên dụng, cho đến các công cụ kinh doanh tùy chỉnh.

Tại sao MCP lại quan trọng

Các LLM bị giới hạn bởi các khả năng tích hợp sẵn của chúng. Với MCP, LibreChat phá vỡ những rào cản này bằng cách:

• Kết nối với bất kỳ công cụ hoặc dịch vụ nào cung cấp máy chủ MCP
• Chuẩn hóa các tích hợp để bạn không cần phải chỉnh sửa mã nguồn của LibreChat cho từng công cụ
• Hỗ trợ môi trường đa người dùng với xác thực và cách ly phù hợp
• Cung cấp một hệ sinh thái đang phát triển gồm các tích hợp năng động, sẵn sàng sử dụng

Cách MCP hoạt động trong LibreChat

LibreChat cung cấp hai cách để sử dụng các máy chủ MCP, đó là trong khu vực trò chuyện hoặc với các tác nhân (agents).

Bạn có thể cấu hình các máy chủ MCP theo cách thủ công trong tệp librechat.yaml của mình hoặc sử dụng smithery.ai để tìm và cài đặt các máy chủ MCP vào librechat.yaml (xem ví dụ bên dưới). Bất cứ khi nào bạn thêm hoặc chỉnh sửa một máy chủ MCP, bạn sẽ cần khởi động lại LibreChat để khởi tạo các kết nối.

URL gọi lại OAuth

Đối với các máy chủ MCP được kích hoạt OAuth, URL callback của LibreChat là:

${DOMAIN_SERVER}/api/mcp/<server-name>/oauth/callback

<server-name> là khóa được sử dụng trong mcpServers trong librechat.yaml hoặc tên máy chủ được tạo trong giao diện Cài đặt MCP. Ví dụ, một máy chủ có tên salesforce với DOMAIN_SERVER=https://chat.example.com sẽ sử dụng https://chat.example.com/api/mcp/salesforce/oauth/callback.

Đăng ký chính xác URL callback này với nhà cung cấp OAuth. Các bản cài đặt Docker cục bộ thường sử dụng http://localhost:3080 làm URL cơ sở.

Trong Khu vực Trò chuyện

LibreChat hiển thị các MCP server đã cấu hình trực tiếp trong khu vực trò chuyện khi sử dụng các endpoint truyền thống (OpenAI, Anthropic, Google, Bedrock, v.v.):

• Trước tiên, hãy chọn bất kỳ endpoint nào không phải là agent và một model tương thích với tool
• Các máy chủ MCP xuất hiện trong một menu thả xuống ở giao diện trò chuyện bên dưới phần nhập văn bản của bạn
• Khi được chọn, tất cả các công cụ từ máy chủ đó sẽ trở nên khả dụng cho model hiện tại của bạn
• Truy cập nhanh các công cụ MCP mà không cần tạo agent, cho phép sử dụng nhiều máy chủ cùng một lúc

Để vô hiệu hóa việc các MCP server xuất hiện trong menu thả xuống của khung chat (chỉ giữ lại cho agent), hãy đặt chatMenu: false trong cấu hình của bạn:

mcpServers:
  internal-tools:
    command: npx
    args: ['-y', 'internal-mcp-server']
    chatMenu: false # Only available in agent builder

Với Agents

Các MCP server tích hợp liền mạch với các LibreChat Agents:

1. Tạo hoặc chỉnh sửa một agent
2. Nhấp vào "Add MCP Server Tools" để mở Hộp thoại Công cụ từ bảng điều khiển Agent Builder
3. Chọn các MCP servers sau khi đã thêm, mỗi server sẽ xuất hiện dưới dạng một mục riêng lẻ
4. Tinh chỉnh các khả năng của tác nhân (agent) bằng cách bật/tắt từng công cụ riêng lẻ sau khi thêm.
5. Lưu tác nhân của bạn

Cách tổ chức cấp cao này giúp giao diện trở nên dễ quản lý hơn - ngay cả các máy chủ có hơn 20 công cụ (như Spotify) cũng xuất hiện dưới dạng các mục đơn lẻ mà bạn có thể mở rộng để kiểm soát chi tiết.

Cấu hình cơ bản

Thêm các máy chủ MCP vào tệp librechat.yaml của bạn theo cách thủ công:

mcpServers:
  # ClickHouse Cloud
  clickhouse-cloud:
    type: streamable-http
    url: https://mcp.clickhouse.cloud/mcp

  # File system access
  filesystem:
    command: npx
    args:
      - -y
      - '@modelcontextprotocol/server-filesystem'
      - /path/to/your/documents

  # Web browser automation
  puppeteer:
    command: npx
    args:
      - -y
      - '@modelcontextprotocol/server-puppeteer'

  # Production-ready cloud service
  business-api:
    type: streamable-http
    url: https://api.yourbusiness.com/mcp
    headers:
      X-User-ID: '{{LIBRECHAT_USER_ID}}'
      Authorization: 'Bearer ${API_TOKEN}'
    timeout: 30000
    serverInstructions: true

Thêm MCP Servers trong giao diện người dùng

Bạn cũng có thể thêm và cấu hình các máy chủ MCP trực tiếp từ giao diện LibreChat mà không cần chỉnh sửa bất kỳ tệp cấu hình nào hoặc khởi động lại máy chủ.

Bước 1: Mở Bảng Cài đặt MCP

Điều hướng đến bảng MCP Settings từ thanh bên phải. Bạn sẽ thấy bất kỳ máy chủ MCP hiện có nào được liệt kê tại đây cùng với nút + để thêm máy chủ mới.

Bước 2: Điền chi tiết máy chủ

Nhấn nút + và điền tên máy chủ MCP, mô tả, URL, loại giao thức truyền tải và phương thức xác thực của bạn, sau đó nhấp vào Create.

Máy chủ mới của bạn sẽ xuất hiện trong bảng MCP Settings cùng với một thông báo xác nhận.

Bước 3: Kiểm tra trạng thái kết nối và xác thực

Xem chỉ báo trạng thái kết nối cho máy chủ mới của bạn. Nếu máy chủ yêu cầu xác thực OAuth, trạng thái sẽ hiển thị là đã ngắt kết nối. Nhấp vào nút xác thực/kết nối của máy chủ (bạn có thể thực hiện việc này bằng cách nhấp vào chính máy chủ MCP trong menu thả xuống của cuộc trò chuyện hoặc nhấp vào biểu tượng kết nối trước để được đưa đến hộp thoại có thêm thông tin về trạng thái kết nối) để bắt đầu quy trình xác thực.

Sau khi bắt đầu, chỉ báo trạng thái sẽ cập nhật để hiển thị rằng quá trình xác thực đang diễn ra.

Bước 4: Tiếp tục trong tab OAuth

Một tab trình duyệt mới sẽ mở ra cho nhà cung cấp OAuth. Hãy xác minh URL callback và nhấp vào Continue để ủy quyền cho LibreChat.

Bước 5: Xác thực thành công

Sau khi xác thực, bạn sẽ thấy thông báo xác nhận thành công. Cửa sổ này sẽ tự động đóng và chuyển hướng bạn quay lại LibreChat.

Bước 6: Máy chủ đã sẵn sàng để sử dụng

LibreChat xác nhận xác thực thành công và tự động chọn máy chủ MCP để sử dụng trong cuộc trò chuyện của bạn. Máy chủ hiện hiển thị chỉ báo trạng thái đã kết nối và được đánh dấu trong menu thả xuống MCP Servers.

Máy chủ MCP mới của bạn cũng khả dụng trong Agent Builder, nơi bạn có thể thêm các công cụ của nó vào bất kỳ agent nào và tùy chỉnh tập hợp con các công cụ được phép sử dụng.

Các biến thông tin xác thực cho các máy chủ được tạo từ giao diện người dùng

Khi thêm một MCP server thông qua giao diện người dùng, bạn có thể yêu cầu người dùng cung cấp API key của riêng họ. Trong phần Authentication của hộp thoại MCP Server Builder, hãy chọn "API Key" và tích vào "User provides key". Chọn định dạng header (Bearer, Basic, hoặc Custom) và lưu server lại.

Ở phía sau, LibreChat tự động tạo một mục customUserVars có tên là MCP_API_KEY và cấu hình mẫu tiêu đề (header template) phù hợp (ví dụ: Authorization: Bearer {{MCP_API_KEY}}). Mỗi người dùng sẽ cung cấp khóa riêng của họ thông qua Hộp thoại Chọn Công cụ MCP (MCP Tool Select Dialog) khi cấu hình một agent — đây cũng chính là giao diện được sử dụng cho customUserVars được định nghĩa trong YAML.

Thêm MCP Servers bằng Smithery

Smithery.ai cung cấp một cách hợp lý để khám phá và cài đặt các MCP server cho LibreChat. Hãy làm theo các bước sau để bắt đầu:

Bước 1: Tìm kiếm các MCP Servers

Truy cập smithery.ai và tìm kiếm máy chủ MCP mà bạn muốn thêm vào instance LibreChat của mình.

Bước 2: Chọn MCP Server của bạn

Nhấp vào máy chủ MCP từ kết quả tìm kiếm để xem chi tiết và các công cụ khả dụng.

Bước 3: Cấu hình cho LibreChat

Điều hướng đến tab Auto trong phần Connect và chọn LibreChat làm client mong muốn của bạn.

Bước 4: Cài đặt MCP Server

Sao chép và chạy lệnh đã tạo trong terminal của bạn để cài đặt MCP server.

Bước 5: Khởi động lại và Xác minh

Máy chủ MCP của bạn hiện đã được cài đặt và có thể cấu hình trong librechat.yaml. Hãy khởi động lại LibreChat để khởi tạo các kết nối và bắt đầu sử dụng máy chủ MCP mới của bạn.

Máy chủ MCP đã được cài đặt thông qua smithery.ai và sẵn sàng để sử dụng trong LibreChat

Để biết các tùy chọn cấu hình chi tiết và ví dụ, hãy xem:

• Hướng dẫn về MCP Server
• Cấu hình MCP Servers
• Cấu hình Agent
• Các tính năng tác nhân nâng cao

Quản lý MCP Server

LibreChat cung cấp các công cụ toàn diện để quản lý kết nối máy chủ MCP với tính năng theo dõi trạng thái kết nối cùng hỗ trợ xác thực và khởi tạo OAuth ngay trong giao diện người dùng (UI).

Các chỉ báo trạng thái kết nối

LibreChat hiển thị các biểu tượng trạng thái động cho biết trạng thái hiện tại của mỗi MCP server trong menu thả xuống của cuộc trò chuyện và bảng cài đặt:

Các loại trạng thái:

• Đã kết nối (bánh răng màu xanh lá cây): Máy chủ đã được kết nối và có các customUserVars có thể định cấu hình
• Yêu cầu OAuth (khóa màu hổ phách): Máy chủ yêu cầu xác thực OAuth
• Đã ngắt kết nối (phích cắm màu cam): Kết nối máy chủ bị lỗi hoặc bị mất
• Đang khởi tạo (thanh tải màu xanh dương): Máy chủ đang khởi động hoặc kết nối lại
• Lỗi (hình tam giác màu đỏ): Máy chủ gặp lỗi
• Hủy bỏ (dấu x màu đỏ): Luồng OAuth đang bị hủy bỏ

Khởi tạo máy chủ

Bạn có thể khởi tạo hoặc khởi tạo lại các MCP server trực tiếp từ giao diện:

Một cú nhấp chuột:

• Khởi tạo chỉ với một cú nhấp chuột từ menu thả xuống chọn máy chủ MCP

  Khởi tạo MCP bằng một cú nhấp chuột

Từ MCPConfigDialog:

• Nhấp vào biểu tượng trạng thái bên cạnh máy chủ MCP trong Chat Dropdown để mở MCPConfigDialog

• Cấu hình các biến người dùng tùy chỉnh và nhấp vào nút Authenticate/Initialize tùy thuộc vào loại xác thực của máy chủ

  Hộp thoại cấu hình xác thực MCP

  Từ Bảng Cài đặt MCP:

• Nhấp vào bất kỳ máy chủ nào trong phần danh sách máy chủ của Bảng Cài đặt MCP để truy cập các điều khiển cấu hình và khởi tạo

• Cấu hình các biến người dùng tùy chỉnh và nhấp vào nút Authenticate/Initialize tùy thuộc vào loại xác thực của máy chủ

  Khởi tạo bảng cài đặt MCP

Khả năng hiển thị bảng cài đặt MCP

Bảng Cài đặt MCP xuất hiện ở thanh bên phải khi LibreChat phát hiện các máy chủ MCP có thể yêu cầu người dùng can thiệp trong quá trình khởi tạo. Bảng này sẽ hiển thị khi bất kỳ máy chủ nào được cấu hình đáp ứng một trong các tiêu chí sau:

• Biến người dùng tùy chỉnh (Custom User Variables): Máy chủ có định nghĩa customUserVars có thể chứa các thông tin xác thực do người dùng cung cấp
• OAuth Authentication: Máy chủ được phát hiện là yêu cầu xác thực OAuth trong quá trình khởi động
• Khởi tạo thủ công: Server đã được cấu hình startup: false, yêu cầu phải khởi tạo thủ công

Các tính năng đặc thù của LibreChat

Việc triển khai MCP của LibreChat được thiết kế cho các môi trường đa người dùng, thực tế và có khả năng tùy chỉnh cao.

Các kết nối dành riêng cho người dùng

• Mỗi người dùng có kết nối riêng biệt tới các máy chủ MCP
• Xác thực người dùng và quyền truy cập được tuân thủ
• Dữ liệu cá nhân và ngữ cảnh vẫn được giữ riêng tư

Chia sẻ MCP Servers

Các MCP server tham gia vào hệ thống kiểm soát truy cập chi tiết của LibreChat. Ngoài các server được định nghĩa trong librechat.yaml (vốn được quản trị viên quản lý và chịu sự điều chỉnh của các quyền tính năng interface.mcpServers), các MCP server do người dùng tạo có ACL riêng và có thể được chia sẻ với các người dùng, nhóm, vai trò cụ thể hoặc công khai, với cấp độ Người xem (Viewer), Người chỉnh sửa (Editor) hoặc Chủ sở hữu (Owner).

Các cờ tính năng USE, CREATE, SHARE và SHARE_PUBLIC trong interface.mcpServers kiểm soát việc ai được phép tạo và chia sẻ MCP servers. Xem Access Control để biết cách các lớp quyền được cấu thành như thế nào.

Ngữ cảnh người dùng động

Các MCP server có thể truy cập thông tin người dùng thông qua các placeholder trong URL và header (đối với các phương thức truyền tải SSE và Streamable HTTP):

mcpServers:
  user-api:
    type: streamable-http
    url: https://api.example.com/users/{{LIBRECHAT_USER_USERNAME}}/mcp
    headers:
      X-User-ID: '{{LIBRECHAT_USER_ID}}'
      X-User-Email: '{{LIBRECHAT_USER_EMAIL}}'
      X-User-Role: '{{LIBRECHAT_USER_ROLE}}'
      Authorization: 'Bearer ${API_TOKEN}'

Các trình giữ chỗ (placeholders) khả dụng bao gồm:

• {{LIBRECHAT_USER_ID}} - Định danh người dùng duy nhất
• {{LIBRECHAT_USER_EMAIL}} - Địa chỉ email của người dùng
• {{LIBRECHAT_USER_ROLE}} - Vai trò người dùng (admin, user, v.v.)
• {{LIBRECHAT_USER_USERNAME}} - Tên người dùng
• Và nhiều hơn thế nữa (xem Cấu hình MCP Servers để biết danh sách đầy đủ)

Các máy chủ MCP được định nghĩa bằng YAML cũng có thể sử dụng các trình giữ chỗ {{LIBRECHAT_OPENID_*}}, {{LIBRECHAT_GRAPH_*}} và {{LIBRECHAT_BODY_*}}. Các giá trị {{LIBRECHAT_BODY_*}} có phạm vi theo yêu cầu (request-scoped), vì vậy LibreChat tạo các kết nối cho lần chạy đang hoạt động, tái sử dụng chúng trong các lệnh gọi công cụ trong lần chạy đó và dọn dẹp chúng 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 khỏi bộ nhớ đệm công cụ cố định để 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ần chạy đang hoạt động. Các trình giữ chỗ User, OpenID và Graph có phạm vi theo người dùng (user-scoped); các phương thức truyền tải HTTP sẽ làm mới các tiêu đề đã phân giải của chúng trước mỗi lệnh gọi công cụ mà không yêu cầu tự kết nối lại.

Hướng dẫn Máy chủ

serverInstructions là một tính năng của LibreChat giúp tự động thêm các hướng dẫn đã cấu hình khi bất kỳ công cụ nào từ máy chủ MCP đó được chọn:

mcpServers:
  filesystem:
    command: npx
    args: ['-y', '@modelcontextprotocol/server-filesystem', '/docs']
    serverInstructions: |
      When accessing files:
      - Always check file permissions first
      - Use absolute paths for reliability
      - Handle errors gracefully

Các tùy chọn:

• true: Sử dụng hướng dẫn do máy chủ cung cấp
• false: Vô hiệu hóa hướng dẫn
• string: Các hướng dẫn tùy chỉnh (hiển thị ở trên)

Cấu hình thời gian chờ (Timeout)

Đối với các thao tác MCP chạy trong thời gian dài, hãy định cấu hình thời gian chờ (timeout) phù hợp cho cả quá trình khởi tạo và các thao tác công cụ.

mcpServers:
  data-processor:
    type: streamable-http
    url: https://api.example.com/mcp
    initTimeout: 15000 # 15 seconds for server initialization
    timeout: 60000 # 60 seconds for tool operations

Lưu ý: Nếu các thao tác vẫn bị ngắt quãng, hãy kiểm tra cấu hình proxy của bạn (ví dụ: nginx, traefik, v.v.) vì chúng có thể đang ngắt kết nối sớm do các thiết lập thời gian chờ (timeout) mặc định.

Thông tin xác thực do người dùng cung cấp

Bạn có thể cho phép người dùng cung cấp thông tin xác thực của riêng họ cho các máy chủ MCP thông qua customUserVars. Điều này cho phép xác thực bảo mật, dành riêng cho từng người dùng mà không cần lưu trữ thông tin xác thực trong các tệp cấu hình.

mcpServers:
  my-api-server:
    type: streamable-http
    url: 'https://api.example.com/mcp'
    headers:
      X-Auth-Token: '{{MY_API_KEY}}' # Uses the user-provided value
    customUserVars:
      MY_API_KEY:
        title: 'API Key'
        description: "Enter your personal API key from <a href='https://example.com/keys' target='_blank'>your account settings</a>"

Người dùng có thể cấu hình các thông tin xác thực này:

• Từ Khu vực Trò chuyện: Nhấp vào biểu tượng cài đặt bên cạnh các máy chủ MCP có thể định cấu hình trong menu thả xuống chọn công cụ
• Từ Bảng Cài đặt MCP: Truy cập "MCP Settings" ở bảng bên phải để quản lý thông tin xác thực cho tất cả các máy chủ đã được cấu hình

Khởi tạo lại các MCP Server với thông tin xác thực của người dùng

Đối với các MCP server yêu cầu thông tin xác thực cụ thể của người dùng trước khi có thể sử dụng (ví dụ: PAT_TOKEN trong MCP server chính thức của GitHub), LibreChat cho phép người dùng cung cấp các thông tin xác thực này và sau đó khởi tạo lại MCP server ngay từ giao diện người dùng mà không cần khởi động lại toàn bộ ứng dụng:

1. Khi bạn chọn một MCP sử dụng customUserVars, bạn sẽ có thể Lưu (Save) hoặc Thu hồi (Revoke) giá trị của customUserVar cho máy chủ MCP đã chọn ngay từ bên trong Bảng điều khiển MCP (MCP Panel).
2. Sau khi lưu giá trị cho một customUserVar, hãy nhấp vào nút khởi tạo lại (biểu tượng có các mũi tên xoay vòng bên cạnh mỗi tên máy chủ trong Bảng điều khiển MCP).
3. LibreChat sẽ cố gắng kết nối với máy chủ bằng thông tin xác thực bạn đã cung cấp và thông báo cho bạn qua một toast về việc liệu quá trình khởi tạo lại đã thành công hay thất bại.

Mẹo: Nếu bạn biết một máy chủ sẽ yêu cầu thông tin xác thực không có sẵn khi khởi động lần đầu, bạn có thể thêm startup: false vào cấu hình của máy chủ đó. Điều này yêu cầu LibreChat không cố gắng kết nối với máy chủ đó cho đến khi nó được khởi tạo lại theo cách thủ công trong giao diện người dùng (UI).

Ví dụ:

mcpServers:
  github-mcp:
    type: streamable-http
    url: 'https://api.githubcopilot.com/mcp/'
    headers:
      Authorization: '{{PAT_TOKEN}}'
    customUserVars:
      PAT_TOKEN:
        title: 'GitHub PAT Token'
        description: 'GitHub Personal Access Token'
    startup: false

Xác thực OAuth

LibreChat hỗ trợ xác thực OAuth cho các máy chủ MCP, tuân theo khuyến nghị của Anthropic về các kết nối MCP an toàn. OAuth cung cấp một phương thức xác thực tiêu chuẩn, an toàn mà không cần lưu trữ thông tin xác thực có thời hạn dài.

Các luồng OAuth được hỗ trợ

Các máy chủ MCP của LibreChat hỗ trợ OAuth 2.0 với:

• Authorization Code Flow with PKCE: Được khuyến nghị để đạt mức bảo mật tối đa
• Khám phá Client: Tự động đăng ký client khi được nhà cung cấp OAuth hỗ trợ
• Refresh Tokens: Tự động làm mới token khi có sẵn

Các ví dụ về cấu hình

mcpServers:
  # Public remote MCP server for PayPal, uses OAuth Client Discovery
  # ❌ Refresh Tokens: you may need to re-authenticate periodically
  # More info: https://developer.paypal.com/tools/mcp-server/
  paypal:
    type: 'sse'
    initTimeout: 150000 # higher timeout to allow for initial authentication
    url: 'https://mcp.paypal.com/sse'

  # Example self-hosted remote MCP server for Spotify, uses OAuth Client Discovery
  # ✅ Refresh Tokens: refreshes token for authentication automatically
  # Hosted on Cloudflare Workers, more info: https://github.com/LibreChat-AI/spotify-mcp
  spotify:
    type: 'streamable-http'
    initTimeout: 150000
    url: 'https://mcp-spotify-oauth-example.account.workers.dev/mcp'

Quy trình xác thực OAuth

Khi bạn cấu hình lần đầu một máy chủ MCP có hỗ trợ OAuth:

1. Kết nối ban đầu: LibreChat cố gắng kết nối với máy chủ MCP
2. Yêu cầu xác thực: Nếu không có token hợp lệ, bạn sẽ thấy chỉ báo xác thực OAuth trong menu thả xuống của cuộc trò chuyện cho máy chủ đó.
3. Giao diện nút: Nhấp vào nút chỉ báo xác thực để mở MCPConfigDialog và bắt đầu quy trình OAuth
4. Config Dialog: Nhấp vào nút Authenticate trong MCPConfigDialog để mở trang xác thực OAuth trong trình duyệt của bạn
5. Chuyển hướng trình duyệt: LibreChat mở nhà cung cấp OAuth trong trình duyệt của bạn
6. Xử lý phản hồi: LibreChat tự động xử lý callback OAuth sau khi bạn đã xác thực thành công
7. Lưu trữ Token: LibreChat lưu trữ các token một cách an toàn để sử dụng trong tương lai
8. Kết nối đã được thiết lập: Sau khi bạn đã xác thực, máy chủ MCP sẽ được kết nối và bạn có thể sử dụng nó trong cuộc trò chuyện của mình

URL phản hồi OAuth

Khi một MCP server sử dụng OAuth, LibreChat sẽ hiển thị một endpoint callback mà nhà cung cấp OAuth sẽ chuyển hướng đến sau khi xác thực thành công.

URL callback phải tuân theo định dạng này:

${baseUrl}/api/mcp/${serverName}/oauth/callback

Trong đó ${serverName} là khóa máy chủ MCP được xác định trong cấu hình librechat.yaml của bạn. LibreChat xử lý việc chuyển hướng tại endpoint này, hoàn tất quá trình trao đổi token và liên kết thông tin xác thực với máy chủ MCP tương ứng.

mcpServers:
  # Example self-hosted remote MCP server for Spotify, uses OAuth Client Discovery
  # ✅ Refresh Tokens: refreshes token for authentication automatically
  # Hosted on Cloudflare Workers, more info: https://github.com/LibreChat-AI/spotify-mcp
  spotify:
    type: 'streamable-http'
    initTimeout: 150000
    url: 'https://mcp-spotify-oauth-example.account.workers.dev/mcp'

Lưu ý:

• URL callback phải được đăng ký chính xác với nhà cung cấp OAuth để luồng hoạt động.
• Các đường dẫn khác như /api/oauth/callback hoặc /api/oauth/openid/callback không hợp lệ cho các luồng MCP OAuth.

Quản lý Token

LibreChat xử lý các token OAuth một cách thông minh:

• Lưu trữ bảo mật: Các token được mã hóa và lưu trữ an toàn
• Tự động làm mới: Khi có sẵn refresh token, LibreChat sẽ tự động gia hạn các access token đã hết hạn
• Khôi phục 401 ẩn: Nếu kết nối MCP OAuth nhận được lỗi 401 giữa phiên làm việc và có sẵn refresh token, LibreChat sẽ cố gắng làm mới ẩn trước khi hiển thị lời nhắc xác thực mới.
• Quản lý phiên: Mỗi người dùng duy trì các phiên OAuth riêng cho môi trường đa người dùng

Mỗi người dùng sẽ được yêu cầu xác thực bằng thông tin đăng nhập OAuth của riêng họ khi họ sử dụng máy chủ MCP có bật OAuth lần đầu tiên. Điều này đảm bảo rằng các chi tiết kết nối và xác thực là duy nhất cho từng người dùng, duy trì tính bảo mật và quyền riêng tư trong môi trường đa người dùng.

Thời gian OAuth

Việc hoàn tất MCP OAuth sử dụng thời gian chờ (timeout) được cấu hình riêng trên máy chủ thay vì sử dụng lại initTimeout của máy chủ MCP. Theo mặc định, LibreChat chờ tối đa 10 phút để người dùng hoàn tất MCP OAuth và giữ trạng thái luồng trong 15 phút.

Sử dụng các biến môi trường này khi một nhà cung cấp OAuth hoặc quy trình làm việc của người dùng cần nhiều thời gian hơn:

MCP_OAUTH_HANDLING_TIMEOUT=600000
MCP_OAUTH_FLOW_TTL=900000

MCP_OAUTH_FLOW_TTL được giới hạn để có thời gian tồn tại lâu hơn MCP_OAUTH_HANDLING_TIMEOUT, nhờ đó các callback gần thời hạn vẫn có thể tìm thấy trạng thái luồng của chúng. Cửa sổ thăm dò (polling window) của thẻ máy chủ MCP tuân theo thời gian chờ xử lý đã cấu hình.

Lưu ý: Các token hiển thị trong quá trình khởi động ứng dụng chỉ dành cho việc khởi tạo ở cấp độ ứng dụng và không được sử dụng cho các kết nối người dùng riêng lẻ.

Ví dụ về tự động làm mới token:

[MCP][spotify] Access token missing
[MCP][spotify] Attempting to refresh token
[MCP][spotify] Successfully refreshed and stored OAuth tokens
[MCP][spotify] ✓ Initialized

Các phương pháp tốt nhất

1. Sử dụng OAuth khi có sẵn: Ưu tiên OAuth thay vì API keys để tăng cường bảo mật
2. Cấu hình thời gian chờ (timeout) phù hợp: Sử dụng MCP_OAUTH_HANDLING_TIMEOUT và MCP_OAUTH_FLOW_TTL cho các cửa sổ hoàn tất OAuth; sử dụng initTimeout cho việc khởi tạo server.
3. Theo dõi hết hạn token: Kiểm tra nhật ký để tìm các vấn đề về xác thực
4. Kế hoạch xác thực lại: Một số nhà cung cấp không hỗ trợ refresh token

Lưu ý: Cấu hình OAuth dựa trên giao diện người dùng sẽ sớm ra mắt, giúp đơn giản hóa quy trình xác thực trực tiếp từ giao diện LibreChat.

Server Transports

Các MCP servers có thể được cấu hình để sử dụng các cơ chế truyền tải khác nhau:

Máy chủ STDIO

• Hoạt động tốt cho các môi trường cục bộ, đơn người dùng
• Không thể mở rộng cho các triển khai từ xa hoặc trên đám mây

Các máy chủ Server-Sent Events (SSE)

• Cơ chế truyền tải từ xa nhưng không được khuyến nghị cho môi trường sản xuất

Máy chủ HTTP có thể truyền phát (Streamable)

• Sử dụng HTTP POST để gửi tin nhắn và hỗ trợ phản hồi dạng streaming
• Hoạt động như một tiến trình độc lập có khả năng xử lý nhiều kết nối máy khách cùng lúc
• Hỗ trợ cả yêu cầu cơ bản và truyền phát dữ liệu thông qua Server-Sent Events (SSE)
• Giải pháp thay thế hiệu quả hơn cho phương thức truyền tải HTTP+SSE cũ
• Hỗ trợ các cấu hình máy chủ đa người dùng phù hợp

Đối với môi trường production, chỉ các MCP server sử dụng "Streamable HTTP" transports mới được khuyến nghị. Không giống như SSE duy trì các kết nối chạy dài, Streamable HTTP cung cấp các tùy chọn không trạng thái (stateless) phù hợp hơn cho các triển khai có khả năng mở rộng và hỗ trợ nhiều người dùng.

LibreChat đi đầu trong việc triển khai các tích hợp máy chủ MCP linh hoạt, có khả năng mở rộng để hỗ trợ nhiều kịch bản sử dụng đa dạng và giúp bạn xây dựng các quy trình làm việc AI của tương lai.

Bạn đã sẵn sàng mở rộng khả năng AI của mình chưa? Hãy bắt đầu bằng việc cấu hình máy chủ MCP đầu tiên và khám phá cách LibreChat có thể kết nối với hầu như mọi công cụ hoặc dịch vụ mà tổ chức của bạn cần.