新手必读:MCPHub的mcp_settings.json配置文件逐行详解
新手必读:MCPHub的mcp_settings.json配置文件逐行详解
MCPHub 是一款开源、自托管的 MCP 网关与控制平面,而 mcp_settings.json 就是它的"心脏":一个 JSON 文件,决定连接哪些 MCP 服务器、给每个服务器传什么环境变量、是否开启 OAuth 认证。本文用仓库自带的示例配置(mcp_settings.json)逐块带你读懂每个字段,看完即可上手修改自己的配置。
上图是配置生效后的效果:mcp_settings.json 里声明的 4 个服务器(amap、playwright、fetch、slack)全部在线,并生成了可直接复制的 MCP 端点。
配置文件在哪里?
MCPHub 的存储默认就是文件模式,核心是三个文件(说明见 docs/zh/configuration/mcp-settings.mdx):
| 文件 | 作用 |
|---|---|
mcp_settings.json |
主配置:MCP 服务器、系统设置、用户与密钥 |
| servers.json | 内置的服务器"商品目录",Market 页面的数据来源 |
.env |
环境变量和密钥(推荐存放 API Key) |
用 Docker 部署时,文件位于挂载的 ./data 目录下(即 data/mcp_settings.json);首次启动前创建它,就能"带服务器启动"。
文件整体结构:6 个顶层字段
先看仓库示例配置的骨架,一眼看清全貌:
{
"mcpServers": { "amap": { ... }, "playwright": { ... }, "fetch": { ... }, "slack": { ... } },
"users": [],
"systemConfig": { "oauthServer": { ... } },
"bearerKeys": [],
"prompts": [],
"resources": []
}
各字段含义(权威定义见 src/types/index.ts 中的 McpSettings 接口):
| 字段 | 是否必填 | 说明 |
|---|---|---|
mcpServers |
✅ 必填 | 要运行的 MCP 服务器列表,文章的"主角" |
users |
否 | 本地账号列表(admin 始终内置) |
systemConfig |
否 | 全局设置:路由认证、OAuth 服务端、智能路由、压缩等 |
bearerKeys |
否 | Bearer 访问密钥,客户端调用 MCP 端点时用 |
prompts / resources |
否 | 配置驱动的内置 Prompt 模板与静态资源 |
新手阶段只需关心前两个:mcpServers 和(可选的)systemConfig。
核心详解:mcpServers 逐个字段说明
mcpServers 是一个"服务器名 → 配置"的字典,每个条目对应一个要运行的 MCP 服务器。
1. stdio 服务器:command / args / env
本地进程型(stdio)服务器只需要三样东西,以示例中的高德地图服务器为例:
"amap": {
"command": "npx",
"args": ["-y", "@amap/amap-maps-mcp-server"],
"env": {
"AMAP_MAPS_API_KEY": "your-api-key"
}
}
逐行解读:
- 服务器名(
amap):自定义的短名,会出现在工具名前缀(如amap-maps_geo)和控制台里。建议用小写英文,便于拼路由地址/mcp/amap。 command:要执行的命令。npx表示"用 npm 即席运行",uvx表示"用 Python/uv 即席运行",也可以写python、node等本地解释器。args:命令参数数组。-y是"自动确认安装"的意思,@playwright/mcp@latest中的@latest表示固定取最新版本。env:传给子进程的环境变量,最常见的用途就是填 API Key。
💡 安全最佳实践:
env的值支持${变量名}语法,会优先从 MCPHub 进程的环境变量中取值。把AMAP_MAPS_API_KEY写成"${AMAP_API_KEY}"并放进.env,配置文件就可以安全地提交到版本库而不泄露密钥。
2. 四种服务器类型:type 字段
type 决定 MCPHub 如何连接上游,共四种(详见 ServerConfig 类型定义):
| type | 连接方式 | 关键字段 |
|---|---|---|
stdio(默认) |
本地子进程 | command + args |
sse |
远程 HTTP 长连接 | url |
streamable-http |
远程 HTTP(MCP 新版推荐) | url |
openapi |
把 OpenAPI 文档变成 MCP 工具 | openapi.url 或 openapi.schema |
省略 type 且写了 command 时默认按 stdio 处理,所以新手可以不管它。接入远程服务器示例:
"remote": {
"type": "streamable-http",
"url": "https://example.com/mcp",
"headers": { "Authorization": "Bearer ${REMOTE_TOKEN}" },
"enableKeepAlive": true
}
3. 常用可选字段速查
| 字段 | 默认 | 用途 |
|---|---|---|
enabled |
true |
设为 false 可保留配置但暂停连接,随时一键恢复 |
description |
无 | 显示在控制台卡片上的备注 |
visibility |
private |
非管理员可见性:private / group / public |
sharedWithUsers |
无 | visibility 为 group 时,允许访问的用户名列表 |
enableKeepAlive |
关 | 远程服务器的心跳保活与自动重连,默认 60 秒检查一次 |
perSessionClient |
false |
为每个下游会话开独立上游连接,适合 Playwright 等有状态服务器 |
options.maxBufferSize |
10 MiB | stdio 响应缓冲区上限(字节),大文件型服务器可调大 |
proxy |
无 | stdio 服务器走代理(proxychains4,仅 Linux/macOS) |
配置里的服务器可以在控制台的 Groups 页面随意编排成分组,再按分组路由端点。
4. 工具级开关:tools / prompts / resources
想屏蔽某个服务器里不安全的工具?不必卸载,在条目里加一层覆盖即可(一般通过控制台操作,也可手写):
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"],
"tools": {
"post_url": { "enabled": false }
}
}
systemConfig:全局开关一次看懂
示例配置里的 systemConfig 只开了一个子项——把 MCPHub 自己变成 OAuth 2.0 授权服务器:
"systemConfig": {
"oauthServer": {
"enabled": true,
"accessTokenLifetime": 3600,
"refreshTokenLifetime": 1209600,
"authorizationCodeLifetime": 300,
"requireClientSecret": false,
"allowedScopes": ["read", "write"],
"dynamicRegistration": { "enabled": true, "clientTtl": 2592000 }
}
}
| 字段 | 含义(秒) |
|---|---|
accessTokenLifetime |
访问令牌有效期,默认 3600(1 小时) |
refreshTokenLifetime |
刷新令牌有效期,默认 1209600(14 天) |
authorizationCodeLifetime |
授权码有效期,默认 300(5 分钟) |
requireClientSecret |
是否强制客户端密钥,默认 false(走 PKCE 更轻) |
dynamicRegistration |
开启 RFC 7591 动态客户端注册;clientTtl 是空闲客户端清理周期 |
新手可以整个删掉这段,全部走默认值。另外两个高频子项:
routing:enableBearerAuth控制 MCP 端点是否强制 Bearer 密钥(默认开启,生产环境建议保持);skipAuth免掉控制台登录,仅限受信任环境。toolResultCompression:透明压缩超大工具返回,省 token,默认关闭。
users / bearerKeys:认证三件套
users:本地账号数组,[]表示仅使用内置admin。数据库模式下更推荐在控制台里管理用户。bearerKeys:调用/mcp端点用的密钥列表,每个密钥可限定只能访问特定分组/服务器(accessType:all/groups/servers/custom)。控制台生成的密钥也会持久化到这里。- OAuth:上一节的
oauthServer开启后,客户端可以走标准 OAuth 2.0 流程拿令牌,替代裸 Bearer Key。
配置改完要重启吗?
不需要。文件模式下 MCPHub 会监听 mcp_settings.json 的变化(机制见 docs/zh/configuration/mcp-settings.mdx 的"热重载"一节):
- 服务器定义与凭据 → 点控制台的 reload 按钮(或
mcphub servers reload <name>)即生效; systemConfig大部分项 → 下次读取自动生效;- 仅端口、
skipAuth、环境变量相关项需要重启进程。
配置生效后,AI 客户端即可直接调用 amap 服务器的地图工具,无需逐个接入。
常见问题排查清单
- 服务器起不来:先在终端手动跑一遍
command + args(如uvx mcp-server-fetch),确认环境没问题。 - 密钥未生效:检查
.env是否加载、${VAR}拼写是否一致。 - JSON 报错:确保是合法 JSON(无注释、无尾逗号);
timeout等数值必须是数字而非字符串。 - 端点 401:MCP 端点默认要求 Bearer 认证,携带控制台生成的密钥,或按需调整
systemConfig.routing。
小结
| 你想做的事 | 改哪里 |
|---|---|
| 添加 MCP 服务器 | mcpServers 里加一个条目(command/args/env 或 type+url) |
| 填 API Key | env,推荐用 ${VAR} 指向 .env |
| 暂停某服务器 | 该条目的 enabled: false |
| 端点加认证 | systemConfig.routing.enableBearerAuth + bearerKeys |
| 客户端走 OAuth | systemConfig.oauthServer |
记住三句话:mcpServers 管"连谁",env 管"带什么钥匙",systemConfig 管"怎么守门"。掌握这三层,mcp_settings.json 就已完全读懂。更多服务器写法(Playwright、Slack、GitHub、代理等)可参考官方文档 docs/zh/configuration/mcp-settings.mdx 与示例文件 examples/mcp_settings_with_env_vars.json。


