MCP 设置配置

本指南说明如何使用 mcp_settings.json 文件和相关配置在 MCPHub 中配置 MCP 服务器。

配置文件概述

MCPHub 使用几个配置文件：

mcp_settings.json：主要的 MCP 服务器配置
servers.json：服务器元数据和分组
.env：环境变量和密钥

基本 MCP 设置结构

mcp_settings.json

{
  "mcpServers": {
    "server-name": {
      "command": "command-to-run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      },
      "cwd": "/working/directory",
      "timeout": 30000,
      "restart": true
    }
  }
}

示例配置

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"],
      "env": {
        "USER_AGENT": "MCPHub/1.0"
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless"],
      "timeout": 60000
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
        "SLACK_TEAM_ID": "${SLACK_TEAM_ID}"
      }
    }
  }
}

服务器配置选项

必需字段

字段	类型	描述
`command`	string	可执行命令或路径
`args`	array	命令行参数

可选字段

字段	类型	默认值	描述
`env`	object	`{}`	环境变量
`cwd`	string	`process.cwd()`	工作目录
`timeout`	number	`30000`	启动超时（毫秒）
`restart`	boolean	`true`	失败时自动重启
`maxRestarts`	number	`5`	最大重启次数
`restartDelay`	number	`5000`	重启间延迟（毫秒）
`stdio`	string	`pipe`	stdio 配置
`perSessionClient`	boolean	`false`	为每个下游 MCP 会话创建独立的上游客户端，而不是在所有会话间共享同一个连接。适用于 Playwright 等有状态服务器。参见会话级客户端隔离。

`type: "openapi"`

字段	类型	必需	描述
`openapi.url`	string	`url`/`schema` 二选一	MCPHub 将下载的 OpenAPI 文档 URL。
`openapi.schema`	object	`url`/`schema` 二选一	内联的 OpenAPI 文档。
`headers`	object	否	应用于所有出站请求的静态请求头，包括文档下载本身。
`openapi.passthroughHeaders`	string[]	否	从调用方转发到上游的请求头名称。

每个字段的权威定义见 src/types/index.ts 中的 ServerConfig 类型；如需此处未描述的行为，请查阅该类型。

受保护的 openapi.url 会通过 MCPHub 的已认证客户端下载，因此配置的 headers 与 OpenAPI security 凭证（HTTP Basic/Bearer、API Key、OAuth2 令牌）会用于该次拉取的认证。凭证仅作用于文档所在源，不会转发给外部 $ref 解析或跨源重定向。若受保护的文档引用了同样需要认证的外部 $ref，请改用 openapi.schema 内联文档。

常见 MCP 服务器示例

Web 和 API 服务器

Fetch 服务器

{
  "fetch": {
    "command": "uvx",
    "args": ["mcp-server-fetch"],
    "env": {
      "USER_AGENT": "MCPHub/1.0",
      "MAX_REDIRECTS": "10"
    }
  }
}

使用 Playwright 进行网页抓取

{
  "playwright": {
    "command": "npx",
    "args": ["@playwright/mcp@latest", "--headless"],
    "timeout": 60000,
    "env": {
      "PLAYWRIGHT_BROWSERS_PATH": "/tmp/browsers"
    }
  }
}

会话级客户端隔离（有状态服务器）

默认情况下，MCPHub 为每个服务器仅保持一个上游连接，并在所有下游 MCP 会话间共享。对于有状态服务器来说，这意味着所有客户端共享同一份状态——以 Playwright 为例，每个会话都会操作同一个浏览器实例及其标签页。设置 perSessionClient: true 可以让 MCPHub 改为为每个下游会话创建独立的上游客户端。每个会话拥有各自的连接（对于 stdio 服务器，还会拥有各自的子进程），在首次工具调用时惰性创建，并在会话结束时自动销毁。

perSessionClient 是 MCPHub 侧的设置：它控制 MCPHub 打开多少个上游连接。它与 Playwright MCP 自身的 --isolated 标志不同，后者控制 Playwright 侧的浏览器配置隔离。二者天然互补——同时启用即可获得完全隔离的浏览器会话。

{
  "mcpServers": {
    "playwright": {
      "type": "streamable-http",
      "url": "http://playwright-mcp:3000/mcp",
      "perSessionClient": true
    }
  }
}

或者使用本地启动并带有 --isolated 标志的 Playwright MCP：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless", "--isolated"],
      "perSessionClient": true
    }
  }
}

对持有会话级状态或需要旧协议工具 elicitation 转发的服务器启用 perSessionClient。它会让上游连接（以及 stdio 子进程）数量随并发会话数成倍增长，不需要以上功能时请保持关闭。

上游协议协商

Streamable HTTP 上游默认使用 protocolNegotiation: "auto"，先探测 server/discover，支持时使用新版无状态 HTTP，否则按 SDK 规则回退旧版握手。 HTTP 探测超时、网络故障和认证失败可能使连接失败，而不是回退。已知只支持旧版的端点可跳过探测：

{
  "mcpServers": {
    "legacy-gateway": {
      "type": "streamable-http",
      "url": "https://gateway.example.com/mcp",
      "protocolNegotiation": "legacy"
    }
  }
}

该可选字段接受 "auto" 和 "legacy"。"auto" 要求 type: "streamable-http"；stdio 和旧 SSE 保持旧版协商。可通过配置 JSON、JSON 导入或服务器 API 设置；表单编辑和复制会保留该字段。文件、数据库、模板及声明式配置同步均支持，修改会重连服务器。共享、隔离和个人连接使用相同策略，但转发旧版 elicitation 的隔离连接在实现 modern input_required 桥接前仍使用旧版协议。新版上游没有服务端推送流。相关请求会在上游 TTL 到期后刷新列表，并合并并发刷新。 TTL 缺失、为零、无效或列表分页未完成时，下一次相关请求重新获取。健康检查仍需设置 enableKeepAlive；新版连接通过网络 server/discover 探测，不调用 ping。详见兼容矩阵。共享远端 SSE 和 Streamable HTTP 服务在连接失败或连接关闭后会在后台自动重试，无需启用健康检查。重试使用指数退避和随机抖动，首次等待 5–10 秒，最高等待 150–300 秒，不限制重试次数；连接成功后重置。已禁用或等待 OAuth 授权的服务不会重试。关闭健康检查时，故障会在请求失败或连接关闭时被发现。控制台展示下次重试时间及上次重试的时间和次数，对应运行时 recovery 状态中的 attempts、lastAttemptAt 和 nextAttemptAt（时间戳单位为毫秒）。配置 passthroughHeaders 的新版上游按请求隔离 discovery 客户端和快照，不跨透传身份共享。每次相关请求增加一次 discovery 往返，个性化描述不写入全局缓存或向量索引。刷新失败只在当前请求中排除该上游，保留健康结果；部分列表返回零 TTL，后续请求会重试。

MCP 2026-07-28 的路由请求头

新版请求使用 MCP-Protocol-Version: 2026-07-28，并携带与 JSON-RPC 方法一致的 Mcp-Method。tools/call 和 prompts/get 还需要与 params.name 一致的 Mcp-Name；resources/read 则需要与 params.uri 一致。列表方法无需 Mcp-Name。SDK v2 HTTP 客户端会自动设置这些请求头。例如，向 /mcp 调用 params.name 为 my-server-my-tool 的工具时发送：

MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: my-server-my-tool

这些请求头与正常的 JSON-RPC 请求体一起发送，请求体仍需包含新版协议的 params._meta 协议版本与客户端能力信息。请求头不选择分组，也不授予访问权限；可访问的服务器仍由 URL 和 bearer 权限决定。使用服务器专属 URL 时，请求体与请求头都应使用该 URL 下暴露的工具名称。非 ASCII 名称在 Mcp-Name 中使用 SDK 的 =?base64?<UTF-8 Base64>?= 编码。缺失必需请求头、请求头与请求体不一致或名称编码非法时，在执行前返回 HTTP 400 和 JSON-RPC 错误 -32020。旧版 2025-11-25 请求继续使用原有握手与会话机制，无需这些路由请求头。

MCP 2026-07-28 的有状态工具

新版 MCP 请求不创建下游传输会话。调用启用 perSessionClient: true 或 OpenAPI cookieSession: true 的工具时，请开启 bearer 认证，并在同一应用工作流的每个请求中携带客户端生成的 UUID v4：

Authorization: Bearer <your-key>
X-MCPHub-State-Id: 65b523af-e4d0-4d99-8e06-461a62a14967

X-MCPHub-State-Id 是 MCPHub 扩展，与 Mcp-Session-Id 和 MCP 握手独立。只有 bearer 凭据、用户和路由均相同的请求才会复用同一状态标识对应的独立上游客户端和 cookie jar。不同工作流应使用不同 UUID。无法设置该扩展的已认证 OpenAI/ChatGPT 工具调用可以省略它，并使用 ChatGPT 工具调用中客户端声明的 _meta["openai/session"] 会话提示。MCPHub 会先对该值做哈希，再仅用于状态关联；它不会参与认证或授权，复用范围仍由已验证的 bearer 凭据、用户和路由限制。如果显式 X-MCPHub-State-Id 已提供但非法，则直接失败而不会回退。如果两个可用关联值都缺失，有状态工具返回工具错误；其他工具无需状态标识。状态只保存在单个 MCPHub 进程的内存中，空闲 30 分钟后回收，执行中的调用会保留状态直到完成。回收和关闭进程时会关闭独立上游客户端并清空 cookie jar。每个进程最多容纳 1,000 个新版状态作用域，超出时返回工具错误，等待容量释放后可重试。进程重启、状态过期、bearer 更换或路由变化后需要重新建立应用状态。多副本部署需要粘性路由。旧版 2025-11-25 客户端继续使用已有的下游会话生命周期。

文件和系统服务器

文件系统服务器

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
    "env": {
      "ALLOWED_OPERATIONS": "read,write,list"
    }
  }
}

SQLite 服务器

{
  "sqlite": {
    "command": "uvx",
    "args": ["mcp-server-sqlite", "--db-path", "/path/to/database.db"],
    "env": {
      "SQLITE_READONLY": "false"
    }
  }
}

通信服务器

Slack 服务器

{
  "slack": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-slack"],
    "env": {
      "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
      "SLACK_TEAM_ID": "${SLACK_TEAM_ID}",
      "SLACK_APP_TOKEN": "${SLACK_APP_TOKEN}"
    }
  }
}

邮件服务器

{
  "email": {
    "command": "python",
    "args": ["-m", "mcp_server_email"],
    "env": {
      "SMTP_HOST": "smtp.gmail.com",
      "SMTP_PORT": "587",
      "EMAIL_USER": "${EMAIL_USER}",
      "EMAIL_PASSWORD": "${EMAIL_PASSWORD}"
    }
  }
}

开发和 API 服务器

GitHub 服务器

{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
    }
  }
}

Google Drive 服务器

{
  "gdrive": {
    "command": "npx",
    "args": ["-y", "@google/mcp-server-gdrive"],
    "env": {
      "GOOGLE_CLIENT_ID": "${GOOGLE_CLIENT_ID}",
      "GOOGLE_CLIENT_SECRET": "${GOOGLE_CLIENT_SECRET}",
      "GOOGLE_REFRESH_TOKEN": "${GOOGLE_REFRESH_TOKEN}"
    }
  }
}

地图和位置服务

高德地图服务器

{
  "amap": {
    "command": "npx",
    "args": ["-y", "@amap/amap-maps-mcp-server"],
    "env": {
      "AMAP_MAPS_API_KEY": "${AMAP_API_KEY}",
      "AMAP_LANGUAGE": "zh-cn"
    }
  }
}

OpenStreetMap 服务器

{
  "osm": {
    "command": "python",
    "args": ["-m", "mcp_server_osm"],
    "env": {
      "OSM_USER_AGENT": "MCPHub/1.0"
    }
  }
}

高级配置

环境变量替换

MCPHub 支持使用 ${VAR_NAME} 语法进行环境变量替换：

{
  "mcpServers": {
    "api-server": {
      "command": "python",
      "args": ["-m", "api_server"],
      "env": {
        "API_KEY": "${API_KEY}",
        "API_URL": "${API_BASE_URL}/v1",
        "DEBUG": "${NODE_ENV:development}"
      }
    }
  }
}

可以使用 ${VAR_NAME:default} 指定默认值：

{
  "timeout": "${MCP_TIMEOUT:30000}",
  "maxRestarts": "${MCP_MAX_RESTARTS:5}"
}

条件配置

根据环境使用不同配置：

{
  "mcpServers": {
    "database": {
      "command": "python",
      "args": ["-m", "db_server"],
      "env": {
        "DB_URL": "${NODE_ENV:development == 'production' ? DB_URL : DEV_DB_URL}"
      }
    }
  }
}

自定义服务器脚本

本地 Python 服务器

{
  "custom-python": {
    "command": "python",
    "args": ["./servers/custom_server.py"],
    "cwd": "/app/custom-servers",
    "env": {
      "PYTHONPATH": "/app/custom-servers",
      "CONFIG_FILE": "./config.json"
    }
  }
}

本地 Node.js 服务器

{
  "custom-node": {
    "command": "node",
    "args": ["./servers/custom-server.js"],
    "cwd": "/app/custom-servers",
    "env": {
      "NODE_ENV": "production"
    }
  }
}

服务器元数据配置

servers.json

使用服务器元数据补充 mcp_settings.json：

{
  "servers": {
    "fetch": {
      "name": "Fetch 服务器",
      "description": "用于网络请求的 HTTP 客户端",
      "category": "web",
      "tags": ["http", "api", "web"],
      "version": "1.0.0",
      "author": "MCPHub 团队",
      "documentation": "https://docs.mcphub.com/servers/fetch",
      "enabled": true
    },
    "playwright": {
      "name": "Playwright 浏览器",
      "description": "网页自动化和抓取",
      "category": "automation",
      "tags": ["browser", "scraping", "automation"],
      "version": "2.0.0",
      "enabled": true
    }
  },
  "groups": {
    "web-tools": {
      "name": "网页工具",
      "description": "用于网页交互的工具",
      "servers": ["fetch", "playwright"],
      "access": "public"
    },
    "admin-tools": {
      "name": "管理工具",
      "description": "管理实用程序",
      "servers": ["filesystem", "database"],
      "access": "admin"
    }
  }
}

组管理

组配置

{
  "groups": {
    "production": {
      "name": "生产工具",
      "description": "稳定的生产服务器",
      "servers": ["fetch", "slack", "github"],
      "access": "authenticated",
      "rateLimit": {
        "requestsPerMinute": 100,
        "burstLimit": 20
      }
    },
    "experimental": {
      "name": "实验功能",
      "description": "测试版和实验性服务器",
      "servers": ["experimental-ai", "beta-search"],
      "access": "admin",
      "enabled": false
    }
  }
}

访问控制

访问级别	描述
`public`	无需认证
`authenticated`	需要有效的 JWT 令牌
`admin`	需要管理员角色
`custom`	自定义权限逻辑

动态配置

热重载

MCPHub 支持配置热重载：

# 不重启重新加载配置
curl -X POST http://localhost:3000/api/admin/reload-config \
  -H "Authorization: Bearer your-admin-token"

配置验证

MCPHub 在启动和重新加载时验证配置：

{
  "validation": {
    "strict": true,
    "allowUnknownServers": false,
    "requireDocumentation": true
  }
}

工具结果压缩

MCPHub 可以在工具结果返回 MCP 客户端前，透明压缩较大的文本结果。它适合处理大型日志、diff、搜索输出、JSON 数组或长文本，避免这些内容占用过多模型上下文。工具结果压缩默认关闭。可以在 设置 → 工具结果压缩 中实时开关，也可以在 systemConfig.toolResultCompression 下配置：

{
  "systemConfig": {
    "toolResultCompression": {
      "enabled": false,
      "minTokens": 2000,
      "maxOutputTokens": 1200,
      "strategy": "auto"
    }
  }
}

字段	类型	默认值	描述
`enabled`	boolean	`false`	是否对成功的工具结果启用透明压缩。
`minTokens`	number	`2000`	单个文本块的估算 token 数达到或超过该阈值时才会压缩。
`maxOutputTokens`	number	`1200`	每个压缩后文本块的目标 token 预算。
`strategy`	`"auto" \| "json" \| "log" \| "search" \| "diff" \| "text"`	`"auto"`	压缩策略。`auto` 会自动识别常见结构化输出。

压缩只作用于成功的工具响应。带有 isError: true 的响应会原样返回，非文本内容块会被保留，每个文本块会独立判断是否需要压缩。MCPHub 压缩结果时会在文本开头加入类似下面的标记：

[mcphub:compressed-tool-result strategy=log original_tokens=9000 compressed_tokens=1200 omitted_lines=240]

活动日志仍记录上游工具的原始输出，压缩只发生在返回 MCP 客户端之前，因此运维人员仍可在 MCPHub 中查看完整结果。

最佳实践

安全

对敏感数据使用环境变量：

{
  "env": {
    "API_KEY": "${API_KEY}",
    "DATABASE_PASSWORD": "${DB_PASSWORD}"
  }
}

限制服务器权限：

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/restricted/path"],
    "env": {
      "READONLY": "true"
    }
  }
}

性能

设置适当的超时：

{
  "timeout": 30000,
  "maxRestarts": 3,
  "restartDelay": 5000
}

资源限制：

{
  "env": {
    "NODE_OPTIONS": "--max-old-space-size=512",
    "MEMORY_LIMIT": "512MB"
  }
}

监控

启用健康检查：

{
  "healthCheck": {
    "enabled": true,
    "interval": 30000,
    "timeout": 5000
  }
}

日志配置：

{
  "env": {
    "LOG_LEVEL": "info",
    "LOG_FORMAT": "json"
  }
}

故障排除

常见问题

服务器无法启动：检查命令和参数

# 手动测试命令
uvx mcp-server-fetch

找不到环境变量：验证 .env 文件

# 检查环境
printenv | grep API_KEY

权限错误：检查文件权限和路径

# 验证可执行权限
ls -la /path/to/server

调试配置

启用调试模式进行详细日志记录：

{
  "debug": {
    "enabled": true,
    "logLevel": "debug",
    "includeEnv": false,
    "logStartup": true
  }
}

验证错误

常见验证错误和解决方案：

缺少必需字段：添加 command 和 args
无效超时：使用数字，不是字符串
找不到环境变量：检查 .env 文件
找不到命令：验证安装和 PATH

这个全面的指南涵盖了在 MCPHub 中为各种用例和环境配置 MCP 服务器的所有方面。

Stdio 响应缓冲区

将 options.maxBufferSize 设置为以字节为单位的正安全整数，可接收更大的 stdio 响应：

{
  "type": "stdio",
  "command": "node",
  "args": ["server.js"],
  "options": { "maxBufferSize": 268435456 }
}

省略该选项时保留 SDK 默认值 10 MiB（10485760 字节）。上限用于读取包含 MCP 消息封装的序列化数据的缓冲区。响应超过上限会关闭传输连接。提高上限会允许使用更多内存，请按服务器需求设置有限上限。零、负数、小数和非有限值均被拒绝。该选项不会改变 HTTP 传输或 SDK 处理大消息的性能。

Authorization 请求头透传

默认禁止透传 Authorization。管理员如需向可信上游传递每次请求的调用者令牌，必须在文件模式的 mcp_settings.json 中显式配置：

{
  "systemConfig": {
    "routing": {
      "bearerAuthHeaderName": "X-MCP-Authorization",
      "allowAuthorizationPassthrough": true
    }
  }
}

管理员也可在 设置 → 密钥 → 允许透传 Authorization 中开启，开启前需先保存独立的 MCPHub 鉴权头；hosted 模式不显示该开关。数据库模式还可通过仅限管理员的 PUT /api/system-config 提交以下请求体，调用该管理接口时使用当前配置的 MCPHub 鉴权头：

{
  "routing": {
    "bearerAuthHeaderName": "X-MCP-Authorization",
    "allowAuthorizationPassthrough": true
  }
}

同时，在可信服务器的 passthroughHeaders（HTTP MCP）或 openapi.passthroughHeaders（OpenAPI）中列出 Authorization。随后每次 MCP 请求分别发送 X-MCP-Authorization: Bearer <mcphub-key> 和 Authorization: Bearer <upstream-user-token>。 allowAuthorizationPassthrough 默认关闭，已有部署升级后不会自动开始透传。MCPHub 实际使用的鉴权头始终禁止透传；hosted 模式始终禁止透传 Authorization。Cookie、Proxy-Authorization、X-Auth-Token 和 X-Api-Key 也不受此开关影响，列入配置仍不会转发。该开关作用于整个实例，只应对可信上游启用；透传配置仍只允许管理员创建或修改。静态请求头和个人凭据是独立认证方式，不能等价替代每次请求携带的调用者令牌。

放行内网上游网络

管理员可在设置页维护允许访问的上游 CIDR 范围，JSON 存储模式也可配置 systemConfig.network.allowedCidrs：

{
  "systemConfig": {
    "network": {
      "allowedCidrs": ["192.168.1.0/24", "fd00:1234::/64"]
    }
  }
}

默认为空列表。配置后，所有用户的上游 MCP（SSE 和 Streamable HTTP）、OpenAPI 及上游 OAuth 请求均可访问这些范围。公网地址仍可访问，管理员拥有的服务器保留已有的不受限内网访问权限。服务器可见性与共享权限不受影响。每项必须是带前缀长度的 IPv4 或 IPv6 地址，例如 /32 表示单个 IPv4 地址，/128 表示单个 IPv6 地址。系统检查全部 DNS 结果、每次重定向目标及建立连接时的 DNS 结果。删除范围会影响后续请求，但不会关闭已有连接或清除缓存。匿名 OAuth 客户端元数据（CIMD）URL 仍仅允许公网地址。只有管理员可调用 PUT /api/system-config，请求体为 {"network":{"allowedCidrs":["192.168.1.0/24"]}}。传入空数组可清空白名单，非法列表返回 HTTP 400 且不会保存。数据库模式请通过管理界面或 API 配置，该字段持久化到系统配置表。请仅放行必要的最小范围。0.0.0.0/0 或 ::/0 等过大的范围也会放行回环地址、云元数据端点等敏感内网目标。

配合 TUN 路由使用 Fake-IP DNS

管理员可在设置 → 安全 → Fake-IP DNS 例外中选择服务器、填写精确域名，增删规则后保存。服务器选择器保存稳定 ID；删除全部规则并保存可清空例外。对于可信本地 Fake-IP/TUN 环境中的 SSE 和 Streamable HTTP 上游，管理员可以仅允许一个稳定服务器 ID 的精确域名访问 198.18.0.0/15，无需全局放行该网段：

{
  "systemConfig": {
    "network": {
      "fakeIpExceptions": [
        { "serverId": "existing-server-uuid", "hostname": "mcp.example.com" }
      ]
    }
  }
}

使用 GET /api/servers 返回的现有服务器 id，而非显示名称。域名必须是小写 ASCII DNS 名称，不能包含协议、端口、通配符或末尾点；国际化域名使用 punycode。缺少 ID 时不会匹配。数据库模式通过仅管理员可用的 PUT /api/system-config 配置，请求体为 {"network":{"fakeIpExceptions":[{"serverId":"existing-server-uuid","hostname":"mcp.example.com"}]}}。空数组清空例外。更新任一网络列表都会保留另一列表，包括在设置页修改 CIDR。例外适用于通过指定服务器 MCP 传输 fetch 发出的请求，包括复用该 fetch 的 SDK OAuth 请求。初始 DNS、每个重定向目标和建连时的 DNS 均执行同一策略，所有解析结果必须通过检查；不会额外放行回环、私网和元数据地址。IP 字面量 URL、其他域名或其他服务器 ID 均不匹配。跳转到其他域名且解析为 Fake-IP 时，需要独立匹配的例外；公网地址继续遵守普通策略。已有全局 CIDR 白名单和管理员所有者豁免仍然生效；需要此窄范围边界时，应使用非管理员拥有的服务器且不配置宽泛 CIDR。移除例外影响后续请求与解析，不会中止已有流或连接。受保护连接使用直接 socket DNS 校验，绕过配置的 HTTP/HTTPS 代理。系统级 TUN 必须接管并路由这些连接，其 DNS 映射必须与 MCPHub 进程或容器内可见的 DNS 一致。仅放行合成网段并不能建立路由。MCPHub 信任本地 DNS/TUN 映射，无法确认合成地址背后的真实目标；仅对可信端点及可信代理环境配置例外。TLS 仍使用原始域名。本策略不启用显式 HTTP 代理路由，也不为 OpenAPI 请求、独立的 OAuth 发现/令牌/注册 fetch 或匿名 CIMD URL 增加例外，这些请求继续遵守原有 SSRF 策略。使用这些独立 fetch 的 OAuth 配置，仍可能需要端点返回真实 DNS 地址。

按需启动的工具快照

对于 stdio 服务器，startOnDemand: true 让子进程在需要时才启动。MCPHub 会持久化最近一次成功发现的原始工具目录，重启后可直接恢复 tools/list，无需逐个启动所有按需服务器。成功发现的空工具列表也是有效快照。首次工具调用仍连接真实上游并刷新目录，上游已删除的工具不能仅凭快照执行。失败调用会触发目录刷新，但不会重放调用。文件模式将快照保存在设置文件旁的 <settings-path>.capabilities.json，容器替换后仍要保留快照时，请将该目录挂载到持久化存储。数据库模式使用 capability_snapshots表。快照不进入设置导出，也不包含启动配置或凭据；但工具定义可能包含上游私有元数据，请按运行时数据的要求保护其存储。服务器列表和详情 API 提供 capabilityCache.state（fresh、stale、missing）及可用时的 capabilityCache.capturedAt。fresh 表示配置匹配的历史发现结果，不保证上游此刻未发生变化。启动配置、子进程实际环境或个人凭据绑定变更会让快照失效。每次列举工具仍重新应用当前权限及服务器、分组的工具配置。个人快照按认证用户隔离，读取时仍要求有效的凭据绑定和当前服务器访问权限。快照缺失或不兼容时沿用实时发现流程：共享 stdio 服务器在启动时预发现，个人服务器在首次认证使用时发现。不增加全量后台刷新。配置不变时，上游包更新或外部权限变化需要等下次真实连接才能被发现。本阶段不持久化提示词和资源；个人服务器的提示词、资源请求仍连接真实上游。

工具授权策略

运营方可以在文件模式配置 systemConfig.toolPolicies，也可以在任一存储模式通过仅限管理员的 PUT /api/system-config 接口提交 toolPolicies。未配置或使用空数组时保留既有访问行为。管理员也可以在 设置 → 工具访问策略 中新增、编辑或删除规则，然后保存策略集。留空的选择器匹配任意值。保存空策略集会移除策略限制，但既有权限仍然生效。

{
  "systemConfig": {
    "toolPolicies": [
      {
        "id": "agent-read",
        "effect": "allow",
        "keyId": "USER_KEY_ID",
        "groupId": "GROUP_ID",
        "serverId": "SERVER_ID",
        "tool": "read_document"
      },
      {
        "id": "block-delete",
        "effect": "deny",
        "tool": "delete_document"
      }
    ]
  }
}

每条规则包含唯一 id、effect（allow 或 deny），以及可选的精确匹配选择器 username、keyId、groupId、serverId、tool。省略的选择器不作限制，规则内的选择器取交集。tool 使用上游原始工具名，不包含服务器前缀、分组别名或 preserveToolNames 投影。密钥和分组使用既有 ID；管理员可从 GET /api/servers/:name 获取服务器的稳定 data.config.id。没有 ID 的旧文件条目使用确定性生成的 ID，在下一次 DAO 写入时保存，服务器改名后保持不变。新服务器获得新 ID，普通更新不能替换 ID。声明式数据库同步按名称匹配，文件改名不属于普通 DAO 改名：使用策略时，必须将已有 data.config.id 固定到服务器文件条目的 id 中，改名时保留该值；未固定 ID 会创建新身份，旧拒绝规则不再匹配。详见数据库声明式配置。 先按 username 和 keyId 确定主体适用规则，再匹配路由和目标。 完整匹配的 deny 优先。若该主体有任何适用的 allow，当前路由、服务器和工具必须完整匹配至少一条 allow，否则拒绝。多个 allow 取并集；没有适用 allow 且没有匹配 deny 时保留既有行为。策略始终与可见性、密钥范围、分组权限、启用状态及能力选择取交集，管理员名下的用户密钥同样受限。 groupId 约束普通分组端点和 $smart/<group> 解析出的分组。服务器直连、全局端点和裸 $smart 没有分组上下文，因此不能绕过仅允许指定分组的策略。如需通过直连或全局端点访问指定服务器和工具，应另配不含 groupId 的 allow。工具发现和调用共用策略判断。Smart Routing 在向量排序及 top-k 之前限制候选工具，执行前再次检查解析后的目标。被拒绝的调用不会获取个人凭据或调用上游。允许的用户密钥继续使用所有者的个人 OAuth 身份及刷新流程。策略配置出错时拒绝访问。外部 IdP 认证和声明映射不属于本策略模型。活动记录的 policy 对象包含 decision、reason，以及适用时的 policyId、serverId、groupId，并保留调用者、密钥和服务器、工具身份。文件模式将决策写入应用日志；持久化活动历史需要数据库模式。个人凭据调用仍不存储输入输出内容，策略审计元数据不包含凭据值。启用策略后，个人服务器直连端点中可能同时解释为原始名称、带前缀名称或网关包装工具的调用，应先获取工具列表。工具目录尚未消除歧义时，所有可能的目标都必须获得授权，否则在读取凭据前拒绝调用。编辑器会警告在已加载服务器、密钥或分组中找不到的 ID；启动完成数据库同步后也会检查引用并记录警告。警告不会阻止保存，便于预先配置资源。失效的拒绝规则不提供保护；失效的服务器或分组允许规则可能阻止适用主体访问，而失效的密钥选择器通常不会匹配任何主体。警告不能判断有效 ID 对应的规则是否会命中某个实际请求；工具名和用户名不在此次引用检查范围内。管理员可以在 设置 → 系统设置 → 控制台名称 中自定义名称，也可以在 mcp_settings.json 中设置 systemConfig.dashboardName（例如 "dashboardName": "Team MCP"）。名称会显示在侧栏、页头、登录页和浏览器标签中，首尾空格会被去除，长度上限为 100 个字符。保存空值可恢复默认名称。文件和数据库存储模式均支持持久化此设置。

用户组共享

管理员可在 用户 → 编辑 → 用户组 中用英文逗号分隔组名，也可通过 PUT /api/users/:username 提交 userGroups: ["readers"]。组名区分大小写，相同名称代表同一用户组；清空数组会移除该用户的所有成员关系。用户组独立于聚合服务器的 Group。将服务器设为 visibility: "group"，并配置 sharedWithUserGroups: ["readers"]，即可向该组所有成员授予使用权限。服务器与 Group 的共享界面均可选择用户组；共享 Group 路由不会自动授予其底层服务器权限。成员变更在下次认证请求时生效，包括现有用户级 key 和 OAuth 会话。共享不授予配置管理权限，工具 policy 仍可进一步收紧访问。

​MCP 设置配置

​配置文件概述

​基本 MCP 设置结构

​mcp_settings.json

​示例配置

​服务器配置选项

​必需字段

​可选字段

​type: "openapi"

​常见 MCP 服务器示例

​Web 和 API 服务器

​Fetch 服务器

​使用 Playwright 进行网页抓取

​会话级客户端隔离（有状态服务器）

​上游协议协商

​MCP 2026-07-28 的路由请求头

​MCP 2026-07-28 的有状态工具

​文件和系统服务器

​文件系统服务器

​SQLite 服务器

​通信服务器

​Slack 服务器

​邮件服务器

​开发和 API 服务器

​GitHub 服务器

​Google Drive 服务器

​地图和位置服务

​高德地图服务器

​OpenStreetMap 服务器

​高级配置

​环境变量替换

​条件配置

​自定义服务器脚本

​本地 Python 服务器

​本地 Node.js 服务器

​服务器元数据配置

​servers.json

​组管理

​组配置

​访问控制

​动态配置

​热重载

​配置验证

​工具结果压缩

​最佳实践

​安全

​性能

​监控

​故障排除

​常见问题

​调试配置

​验证错误

​Stdio 响应缓冲区

​Authorization 请求头透传

​放行内网上游网络

​配合 TUN 路由使用 Fake-IP DNS

​按需启动的工具快照

​工具授权策略

​用户组共享

MCP 设置配置

配置文件概述

基本 MCP 设置结构

mcp_settings.json

示例配置

服务器配置选项

必需字段

可选字段

`type: "openapi"`

常见 MCP 服务器示例

Web 和 API 服务器

Fetch 服务器

使用 Playwright 进行网页抓取

会话级客户端隔离（有状态服务器）

上游协议协商

MCP 2026-07-28 的路由请求头

MCP 2026-07-28 的有状态工具

文件和系统服务器

文件系统服务器

SQLite 服务器

通信服务器

Slack 服务器

邮件服务器

开发和 API 服务器

GitHub 服务器

Google Drive 服务器

地图和位置服务

高德地图服务器

OpenStreetMap 服务器

高级配置

环境变量替换

条件配置

自定义服务器脚本

本地 Python 服务器

本地 Node.js 服务器

服务器元数据配置

servers.json

组管理

组配置

访问控制

动态配置

热重载

配置验证

工具结果压缩

最佳实践

安全

性能

监控

故障排除

常见问题

调试配置

验证错误

Stdio 响应缓冲区

Authorization 请求头透传

放行内网上游网络

配合 TUN 路由使用 Fake-IP DNS

按需启动的工具快照

工具授权策略

用户组共享