MCP

Model Context Protocol (MCP) 是一种开放协议，旨在标准化应用程序向大语言模型 (LLMs) 提供上下文的方式。可以将 MCP 视为 “AI 界的 USB-C” —— 正如 USB-C 为电子设备提供了通用的连接标准一样，MCP 也提供了一种标准化的方式，将 AI 模型连接到各种工具、数据源和服务。

LibreChat 利用 MCP 极大地扩展了您的 AI 智能体的能力，使您能够集成从文件系统访问、网络浏览器、专用 API 到自定义业务工具等一切内容。

为什么 MCP 很重要

LLMs 仅限于其内置能力。通过 MCP，LibreChat 打破了这些壁垒，实现了：

• 连接到任何提供 MCP server 的工具或服务
• 标准化集成，这样您就不需要为每个工具编辑 LibreChat 的代码
• 支持多用户环境，并具备适当的身份验证和隔离机制
• 提供一个不断增长的生态系统，包含动态、即插即用的集成

LibreChat 中 MCP 的工作原理

LibreChat 提供了两种使用 MCP 服务器的方式，既可以在聊天区域中使用，也可以与智能体（agents）配合使用。

您可以在 librechat.yaml 文件中手动配置 MCP 服务器，或者使用 smithery.ai 来查找并将 MCP 服务器安装到 librechat.yaml 中（见下方示例）。每当您添加或编辑 MCP 服务器时，都需要重启 LibreChat 以初始化连接。

OAuth 回调 URL

对于启用了 OAuth 的 MCP 服务器，LibreChat 回调 URL 为：

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

<server-name> 是 librechat.yaml 中 mcpServers 下使用的键，或者是 MCP 设置 UI 中创建的服务器名称。例如，一个名为 salesforce 且配置了 DOMAIN_SERVER=https://chat.example.com 的服务器，其回调地址为 https://chat.example.com/api/mcp/salesforce/oauth/callback。

请将此确切的回调 URL 注册到 OAuth 提供商。本地 Docker 安装通常使用 http://localhost:3080 作为基础 URL。

在聊天区域中

当使用传统 endpoint（OpenAI、Anthropic、Google、Bedrock 等）时，LibreChat 会直接在聊天区域显示已配置的 MCP 服务器：

• 首先选择任何非 Agent endpoint，以及一个兼容工具的模型
• MCP servers 会显示在聊天界面文本输入框下方的下拉菜单中
• 选中后，来自该服务器的所有工具都将可供您当前的模型使用
• 无需创建智能体即可快速访问 MCP 工具，并允许同时使用多个服务器

若要禁止 MCP 服务器出现在聊天下拉菜单中（仅保留在智能体中使用），请在您的配置中设置 chatMenu: false：

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

使用 Agents

MCP servers 可以与 LibreChat Agents 无缝集成：

1. 创建或编辑一个 Agent
2. 点击“Add MCP Server Tools”以从 Agent Builder 面板打开工具对话框
3. 选择已添加的 MCP 服务器，每个服务器将显示为一个单独的条目
4. 通过在添加后启用/禁用单个工具，微调您的智能体功能。
5. 保存您的智能体

这种更高级别的组织方式使界面易于管理——即使是拥有 20 多个工具的服务器（例如 Spotify）也会显示为单个条目，可以展开以进行精细控制。

基础配置

手动将 MCP 服务器添加到您的 librechat.yaml 文件中：

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

在 UI 中添加 MCP 服务器

您也可以直接从 LibreChat 界面添加和配置 MCP 服务器，而无需编辑任何配置文件或重启服务器。

第 1 步：打开 MCP 设置面板

从右侧边栏导航至 MCP Settings 面板。你将在此处看到所有现有的 MCP 服务器列表，以及用于添加新服务器的 + 按钮。

第 2 步：填写服务器详细信息

点击 + 按钮并填写您的 MCP 服务器名称、描述、URL、传输类型和身份验证方法，然后点击 Create。

您的新服务器将出现在 MCP Settings 面板中，并伴有确认提示。

第 3 步：检查连接状态并进行身份验证

查看新服务器的 connection status indicator。如果服务器需要 OAuth 身份验证，状态将显示为已断开连接。点击服务器的身份验证/连接按钮（你可以通过在聊天下拉菜单中点击 MCP 服务器本身，或者先点击连接图标以进入包含更多连接状态信息的对话框来执行此操作）以开始身份验证流程。

一旦启动，状态指示器将更新以显示身份验证正在进行中。

第 4 步：在 OAuth 选项卡中继续

OAuth 提供商的新浏览器标签页将会打开。请验证回调 URL 并点击 Continue 以授权 LibreChat。

第 5 步：身份验证成功

身份验证成功后，您将看到确认信息。此窗口将自动关闭并重定向回 LibreChat。

第 6 步：服务器准备就绪

LibreChat 会确认认证成功，并自动选择 MCP 服务器以供您在对话中使用。此时，服务器会显示已连接的状态指示器，并在 MCP Servers 下拉菜单中被勾选。

您新的 MCP 服务器也可在 Agent Builder 中使用，您可以在其中将工具添加到任何 Agent，并自定义允许使用的工具子集。

UI 创建服务器的凭据变量

通过 UI 添加 MCP 服务器时，您可以要求用户提供他们自己的 API 密钥。在 MCP 服务器构建器对话框的 Authentication 部分，选择 "API Key" 并勾选 "User provides key"。选择标头格式（Bearer、Basic 或 Custom）并保存服务器。

在后台，LibreChat 会自动创建一个名为 MCP_API_KEY 的 customUserVars 条目，并配置相应的标头模板（例如 Authorization: Bearer {{MCP_API_KEY}}）。每位用户在配置智能体时，都会通过 MCP 工具选择对话框（MCP Tool Select Dialog）提供他们自己的密钥——这与用于 YAML 定义的 customUserVars 的 UI 相同。

使用 Smithery 添加 MCP 服务器

Smithery.ai 为发现和安装 LibreChat 的 MCP 服务器提供了一种简化的方式。请按照以下步骤开始：

第 1 步：搜索 MCP Servers

访问 smithery.ai 并搜索您想要添加到 LibreChat 实例的 MCP 服务器。

第 2 步：选择您的 MCP Server

从搜索结果中点击 MCP 服务器，以查看详细信息和可用工具。

第 3 步：为 LibreChat 进行配置

导航至 Connect 部分中的 Auto 选项卡，并选择 LibreChat 作为您所需的客户端。

第 4 步：安装 MCP Server

复制并运行生成的命令到你的终端以安装 MCP server。

第 5 步：重启并验证

您的 MCP 服务器现已安装，并可在 librechat.yaml 中进行配置。请重启 LibreChat 以初始化连接并开始使用您的新 MCP 服务器。

通过 smithery.ai 安装的 MCP server，现已可在 LibreChat 中使用

有关详细的配置选项和示例，请参阅：

• MCP Server Guides
• MCP Servers 配置
• Agent 配置
• 高级智能体功能

MCP Server Management

LibreChat 提供了全面的工具来管理 MCP 服务器连接，并在 UI 中支持连接状态跟踪以及 OAuth 身份验证和初始化。

连接状态指示器

LibreChat 会在聊天下拉菜单和设置面板中显示动态状态图标，以展示每个 MCP server 的当前状态：

状态类型：

• 已连接 (绿色齿轮)：服务器已连接并具有可配置的 customUserVars
• OAuth Required (amber key): 服务器需要 OAuth 身份验证
• 已断开连接（橙色插头图标）：服务器连接失败或丢失
• 初始化中 (蓝色加载器)：服务器正在启动或重新连接
• 错误（红色三角形）：服务器遇到错误
• 取消（红色 x）：OAuth 流程正在被取消

服务器初始化

您可以直接从界面初始化或重新初始化 MCP 服务器：

一键：

• 从 MCP 服务器选择下拉菜单中一键初始化

  一键 MCP 初始化

来自 MCPConfigDialog：

• 点击聊天下拉菜单中 MCP 服务器旁边的状态图标，即可打开 MCPConfigDialog。

• 配置自定义用户变量，并根据服务器身份验证类型点击 Authenticate/Initialize 按钮

  MCP 配置对话框身份验证

  来自 MCP 设置面板：

• 点击 MCP 设置面板中服务器列表部分的任意服务器，即可访问配置和初始化控件。

• 配置自定义用户变量，并根据服务器身份验证类型点击 Authenticate/Initialize 按钮

  MCP 设置面板初始化

MCP 设置面板可见性

当 LibreChat 检测到 MCP 服务器在初始化过程中可能需要用户干预时，MCP 设置面板会出现在右侧边栏中。当任何已配置的服务器满足以下条件之一时，该面板将可见：

• 自定义用户变量 (Custom User Variables)：服务器定义了 customUserVars，其中可能包含用户提供的凭据
• OAuth Authentication: 服务器在启动时被检测到需要 OAuth 身份验证
• 手动初始化：服务器已配置 startup: false，需要手动进行初始化

LibreChat 特有功能

LibreChat 的 MCP 实现专为高度可配置、真实世界的多用户环境而设计。

用户特定连接

• 每个用户都拥有各自独立的 MCP 服务器连接
• 用户身份验证和权限受到尊重
• 个人数据和上下文保持私密

共享 MCP Servers

MCP 服务器参与 LibreChat 的 granular access control 系统。除了在 librechat.yaml 中定义的服务器（由管理员管理并受 interface.mcpServers 功能权限控制）之外，用户创建的 MCP 服务器拥有自己的 ACL，并可以以查看者 (Viewer)、编辑者 (Editor) 或所有者 (Owner) 级别与特定的用户、组、角色或公开共享。

interface.mcpServers 下的 USE、CREATE、SHARE 和 SHARE_PUBLIC 功能标志控制了谁被允许创建和共享 MCP 服务器。请参阅 Access Control 以了解权限层级是如何组合的。

动态用户上下文

MCP 服务器可以通过 URL 和标头中的占位符访问用户信息（适用于 SSE 和 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}'

可用的占位符包括：

• {{LIBRECHAT_USER_ID}} - 唯一用户标识符
• {{LIBRECHAT_USER_EMAIL}} - 用户的电子邮件地址
• {{LIBRECHAT_USER_ROLE}} - 用户角色 (admin, user 等)
• {{LIBRECHAT_USER_USERNAME}} - 用户名
• 以及更多（请参阅 MCP Servers Configuration 获取完整列表）

YAML 定义的 MCP 服务器也可以使用 {{LIBRECHAT_OPENID_*}}、{{LIBRECHAT_GRAPH_*}} 和 {{LIBRECHAT_BODY_*}} 占位符。{{LIBRECHAT_BODY_*}} 的值是请求作用域的，因此 LibreChat 会为当前运行创建连接，在运行期间的工具调用中复用它们，并在请求结束时进行清理。请求作用域的服务器会被排除在持久化工具缓存之外，以确保请求特定的标头和 URL 不会在当前运行之外被复用。用户、OpenID 和 Graph 占位符是用户作用域的；HTTP 传输会在每次工具调用前刷新其解析后的标头，而无需自行重新连接。

服务器指令

serverInstructions 是 LibreChat 的一项功能，当选中来自该 MCP server 的任何工具时，它会自动动态添加已配置的指令：

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

选项：

• true：使用服务器提供的指令
• false：禁用指令
• string: 自定义指令（显示在上方）

超时配置

对于长时间运行的 MCP 操作，请为初始化和工具操作配置适当的超时时间。

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

注意：如果操作仍然被中断，请检查您的代理配置（例如 nginx、traefik 等），这些配置可能会因默认超时设置而过早断开连接。

用户提供的凭据

您可以通过 customUserVars 允许用户为 MCP 服务器提供他们自己的凭据。这实现了安全、特定于用户的身份验证，而无需将凭据存储在配置文件中。

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

用户可以配置这些凭据：

• 从聊天区域：点击工具选择下拉菜单中可配置 MCP 服务器旁边的设置图标
• 从 MCP 设置面板：在右侧面板中访问“MCP Settings”以管理所有已配置服务器的凭据

使用用户凭据重新初始化 MCP Servers

对于在使用前需要用户特定凭据的 MCP 服务器（例如 GitHub 官方 MCP 服务器 中的 PAT_TOKEN），LibreChat 允许用户在 UI 界面内提供这些凭据，并重新初始化 MCP 服务器，而无需重启整个应用程序：

1. 当您选择一个使用 customUserVars 的 MCP 时，您将能够在 MCP 面板中为所选的 MCP 服务器 保存 (Save) 或 撤销 (Revoke) customUserVar 的值。
2. 在保存 customUserVar 的值后，请点击重新初始化按钮（MCP 面板中每个服务器名称旁带有循环箭头的图标）。
3. LibreChat 将尝试使用您提供的凭据连接到服务器，并通过提示消息通知您重新初始化过程是成功还是失败。

提示：如果您知道某个服务器在首次启动时无法获取所需的凭据，可以在其配置中添加 startup: false。这会告知 LibreChat 在 UI 中手动重新初始化该服务器之前，不要尝试连接它。

示例：

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

OAuth 身份验证

LibreChat 支持为 MCP 服务器进行 OAuth 身份验证，遵循 Anthropic 关于安全 MCP 连接的建议。OAuth 提供了一种标准化的安全方式来进行身份验证，而无需存储长期凭据。

支持的 OAuth 流程

LibreChat MCP 服务器支持以下 OAuth 2.0：

• Authorization Code Flow with PKCE：推荐用于实现最高安全性
• 客户端发现 (Client Discovery)：在 OAuth 提供商支持时自动进行客户端注册
• Refresh Tokens: 当可用时自动更新令牌

配置示例

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'

OAuth 身份验证流程

当你首次配置启用了 OAuth 的 MCP 服务器时：

1. 初始连接: LibreChat 尝试连接到 MCP 服务器
2. 需要身份验证：如果不存在有效的令牌，您将在该服务器的聊天下拉菜单中看到一个 OAuth 身份验证指示器。
3. 按钮界面：点击认证指示器按钮以打开 MCPConfigDialog 并开始 OAuth 流程
4. 配置对话框 (Config Dialog)：点击 MCPConfigDialog 中的 Authenticate 按钮，即可在浏览器中打开 OAuth 认证页面。
5. 浏览器重定向: LibreChat 会在您的浏览器中打开 OAuth 提供商
6. 返回处理: 一旦您完成身份验证，LibreChat 会自动处理 OAuth 回调。
7. Token Storage: LibreChat 安全地存储令牌以供将来使用
8. 连接已建立：一旦您完成身份验证，MCP server 将会连接，您就可以在聊天中使用它了

OAuth 回调 URL

当 MCP server 使用 OAuth 时，LibreChat 会暴露一个回调 endpoint，OAuth 提供商在授权成功后会重定向到该地址。

回调 URL 必须遵循以下格式：

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

其中 ${serverName} 是你在 librechat.yaml 配置文件中定义的 MCP 服务器键名。LibreChat 会在此 endpoint 处理重定向，完成令牌交换，并将凭据与相应的 MCP 服务器关联。

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'

注意：

• 必须在 OAuth 提供商处准确注册回调 URL，流程才能正常工作。
• 其他路径（例如 /api/oauth/callback 或 /api/oauth/openid/callback）不适用于 MCP OAuth 流程。

令牌管理

LibreChat 会智能处理 OAuth 令牌：

• 安全存储：令牌经过加密并安全存储
• 自动刷新：当存在刷新令牌时，LibreChat 会自动更新过期的访问令牌
• 静默 401 恢复：如果 OAuth MCP 连接在会话期间收到 401 错误且有可用的刷新令牌，LibreChat 会尝试进行静默刷新，然后再弹出新的身份验证提示。
• 会话管理：在多用户环境中，每个用户维护其各自的 OAuth 会话

当用户首次使用启用了 OAuth 的 MCP 服务器时，系统会提示每位用户使用其自己的 OAuth 登录信息进行身份验证。这确保了连接和身份验证详细信息对每位用户都是唯一的，从而在多用户环境中维护了安全性和隐私。

OAuth 时序

MCP OAuth 完成过程使用其自身服务器配置的超时时间，而不是复用 MCP 服务器的 initTimeout。默认情况下，LibreChat 会等待最多 10 分钟以供用户完成 MCP OAuth，并将流程状态保留 15 分钟。

当 OAuth 提供商或用户工作流需要更多时间时，请使用这些环境变量：

MCP_OAUTH_HANDLING_TIMEOUT=600000
MCP_OAUTH_FLOW_TTL=900000

MCP_OAUTH_FLOW_TTL 的值会被强制设定为大于 MCP_OAUTH_HANDLING_TIMEOUT，以确保在截止时间附近的回调仍能找到其流程状态。MCP 服务器卡片轮询窗口遵循配置的处理超时时间。

注意：应用启动期间显示的 token 仅用于应用级别的初始化，不会用于单个用户连接。

自动令牌刷新的示例：

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

最佳实践

1. 尽可能使用 OAuth：优先选择 OAuth 而非 API 密钥，以获得更好的安全性
2. 配置适当的超时时间：使用 MCP_OAUTH_HANDLING_TIMEOUT 和 MCP_OAUTH_FLOW_TTL 来设置 OAuth 完成窗口；使用 initTimeout 来设置服务器初始化超时。
3. 监控令牌过期: 检查日志以查找身份验证问题
4. 重新认证计划：部分提供商不支持刷新令牌

注意：基于 UI 的 OAuth 配置即将推出，它将直接从 LibreChat 界面简化身份验证流程。

Server Transports

MCP servers 可以配置为使用不同的传输机制：

STDIO 服务器

• 适用于本地单用户环境
• 不适用于远程或云端部署的扩展

Server-Sent Events (SSE) 服务器

• 远程传输机制，但不建议在生产环境中使用

可流式传输的 HTTP 服务器

• 使用 HTTP POST 发送消息并支持流式响应
• 作为一个可以处理多个客户端连接的独立进程运行
• 支持基础请求以及通过服务器发送事件 (SSE) 进行流式传输
• 比旧版 HTTP+SSE 传输性能更高的替代方案
• 支持适当的多用户服务器配置

对于生产环境，仅推荐使用具有 "Streamable HTTP" 传输方式 的 MCP 服务器。与维持长连接的 SSE 不同，Streamable HTTP 提供了更适合可扩展、多用户部署的无状态选项。

LibreChat 处于实现灵活、可扩展的 MCP 服务器集成的最前沿，旨在支持多样化的使用场景，并帮助您构建未来的 AI 工作流。

准备好扩展您的 AI 能力了吗？ 首先配置您的第一个 MCP 服务器，探索 LibreChat 如何连接到您组织所需的几乎任何工具或服务。