MCP 设置对象结构

概述

mcpSettings 配置提供了有关 MCP (Model Context Protocol) 服务器安全性和行为的全局设置。此配置与 mcpServers 分开，用于控制 MCP 服务器如何连接到特定的域名和 IP 地址。

示例

# Example MCP Settings Configuration
mcpSettings:
  # Strict whitelist mode:
  # allowedDomains:
  #   - "example.com"                    # Specific domain
  #   - "*.example.com"                  # All subdomains using wildcard
  #   - "https://api.example.com:8443"   # With protocol and port
  #   - "http://mcp-server:3000"         # Internal service, explicitly whitelisted

  # Default SSRF mode with private service exemptions:
  allowedAddresses:
    - "host.docker.internal:8080"        # Permit one private host on one port
    - "10.0.0.5:8000"                    # Permit one private IP on one port

配置

子键

安全上下文 (SSRF 保护)

LibreChat 包含 SSRF (Server-Side Request Forgery) 保护，其行为如下：

当未配置 allowedDomains 时：

• 容易受到 SSRF 攻击的目标默认被阻止
• 所有其他外部域名均被允许

当配置了 allowedDomains 时：

• 仅允许列表中的域名
• 可以通过显式地将内部/SSRF目标添加到列表中来允许它们。

被拦截的 SSRF 目标包括：

• Localhost 地址 (localhost, 127.0.0.1, ::1)
• 私有 IP 地址范围 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
• 链路本地地址 (169.254.0.0/16，包含云元数据 IP)
• 内部 TLD (.internal, .local, .localhost)
• 常见的内部服务名称 (redis, mongodb, postgres, api, rag_api 等)

如果您的 MCP 服务器需要连接到内部服务或 Docker 容器，请将它们添加到严格的 allowedDomains 白名单中，或者将 allowedDomains 留空并将具体的私有服务添加到 allowedAddresses 中。

模式格式

allowedDomains 数组支持多种模式格式：

1. 精确域名匹配

   allowedDomains:
     - "example.com"

   仅允许连接到确切的 example.com（任何协议/端口）

2. 通配符子域名匹配

   allowedDomains:
     - "*.example.com"

   允许连接到 example.com 的所有子域名（例如 api.example.com、mcp.example.com）

3. 特定 IP 地址

   allowedDomains:
     - "192.168.1.100"
     - "172.24.1.165"

   允许连接到特定的 IP 地址

4. 本地 Docker 域名

   allowedDomains:
     - "mcp-server"
     - "host.docker.internal"

   允许连接到 Docker 容器名称或特殊的 Docker 域

5. 使用协议和端口

   allowedDomains:
     - "https://api.example.com:8443"
     - "http://internal-mcp:3000"

   限制连接到特定的协议和端口组合

错误消息

如果您看到类似以下的错误：

  error: [MCPServersRegistry] Failed to inspect server "my-mcp": Domain "http://172.24.1.165:8000" is not allowed
  error: [MCP][my-mcp] Failed to initialize: Domain "http://172.24.1.165:8000" is not allowed

这通常表明需要将 MCP 服务器的私有主机和端口添加到 allowedAddresses 中，除非您有意将 allowedDomains 用作严格的白名单：

mcpSettings:
  allowedAddresses:
    - "172.24.1.165:8000"    # Add the private host/IP and MCP port

allowedAddresses

allowedAddresses 是针对 SSRF 私有 IP 拦截的豁免列表，而非域名白名单。当您希望允许访问一两个特定的私有/内部服务，同时又不限制 MCP 服务器对公共互联网的访问范围时，它是最合适的工具。

何时使用它来代替 allowedDomains

allowedDomains 是一个严格的白名单：当设置该项时，仅列出的条目可被访问。在此处添加一个私有 IP 以允许（例如）自托管的 MCP 服务器，也会同时阻止所有你未列出的公共目的地（如 api.example.com、*.googleapis.com 等）。

allowedAddresses 仅在未配置 allowedDomains 时使用。它允许特定的私有 host:port 目标，同时允许通过默认的 SSRF 策略访问其余的公共互联网。常见配置：

mcpSettings:
  allowedAddresses:
    - "host.docker.internal:8080"
    - "10.0.0.5:8000"
  # allowedDomains is intentionally not set — public destinations
  # remain reachable, only listed private host:port services are exempted.

如果配置了 allowedDomains，它将具有权威性：私有服务必须列在其中，而不能依赖 allowedAddresses。

可接受的条目

• 带端口的主机名: host.docker.internal:8080, mcp-server:3000, localhost:3001
• 带有端口的私有 IPv4 字面量: 10.0.0.5:8000, 127.0.0.1:3001, 192.168.1.10:443, 169.254.169.254:80
• 带端口的方括号私有 IPv6 字面量: [::1]:3001, [fc00::1]:8080, [fe80::1]:8080

被拒绝的条目（在配置加载时验证）

• URLs / paths / CIDR ranges: http://10.0.0.5, 10.0.0.0/24, /path
• 裸主机名或 IP：localhost、10.0.0.5、::1、[::1] — 每个条目都必须包含端口
• 无效端口: localhost:0, localhost:65536, localhost:http
• 公网 IP 字面量: 8.8.8.8:53, 1.1.1.1:53, [2001:4860::8888]:443 — 该字段的作用域仅限于私有 IP 空间；公网 IP 不属于 SSRF 攻击目标，因此公网 IP 免除规则没有防御意义。

Hostname trust

主机名条目会信任该主机名在运行时解析到的任何 IP 地址（在指定的端口上）。如果所列主机名的 DNS 被轮换或劫持以指向不同的私有 IP，则该豁免也会随之生效。请仅列出您拥有 DNS 控制权的主机名。在可能的情况下，优先使用具体的 IP 地址。

参考资料

• MCP Servers 配置
• MCP 功能
• Actions allowedAddresses (Actions 的概念类似)