新手必读:MCPHub的mcp_settings.json配置文件逐行详解

原创2026-10-17 15:29:501,370 阅读
文章标签:人工智能LLM 网关MCP 服务后端API网关认证鉴权

新手必读:MCPHub的mcp_settings.json配置文件逐行详解

MCPHub 是一款开源、自托管的 MCP 网关与控制平面,而 mcp_settings.json 就是它的"心脏":一个 JSON 文件,决定连接哪些 MCP 服务器、给每个服务器传什么环境变量、是否开启 OAuth 认证。本文用仓库自带的示例配置(mcp_settings.json)逐块带你读懂每个字段,看完即可上手修改自己的配置。

MCPHub 控制台仪表盘

上图是配置生效后的效果: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、环境变量相关项需要重启进程。

amap 服务器工具调用结果

配置生效后,AI 客户端即可直接调用 amap 服务器的地图工具,无需逐个接入。

常见问题排查清单

  1. 服务器起不来:先在终端手动跑一遍 command + args(如 uvx mcp-server-fetch),确认环境没问题。
  2. 密钥未生效:检查 .env 是否加载、${VAR} 拼写是否一致。
  3. JSON 报错:确保是合法 JSON(无注释、无尾逗号);timeout 等数值必须是数字而非字符串。
  4. 端点 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。

登录后查看全文
mcphub