部署配置
JSON 模式的单实例部署可以不设置MCPHUB_CREDENTIAL_ENCRYPTION_KEY。首次保存绑定时，MCPHub 会生成 32 字节随机密钥，以 0600 权限原子创建配置文件旁的 <MCPHUB_SETTING_PATH>.credentials.key（未指定配置路径时使用默认配置文件旁的路径），重启后继续读取同一文件。密钥文件不进入配置导出、Git 或 Docker 构建上下文。配置目录必须可写；持久化失败时会拒绝保存，不使用临时密钥。
数据库模式不会自动生成本地密钥。保存个人凭据或发起个人上游 OAuth 前，需配置 MCPHUB_CREDENTIAL_ENCRYPTION_KEY，否则操作会在写入绑定前失败。为兼容已有部署，仍支持读取已有的本地密钥文件。迁移时请保留原密钥，并将其值设置到环境变量中。如果容器重建导致密钥丢失，仅恢复数据库备份无法恢复凭据。
显式设置的环境变量优先，值必须是 32 字节随机数据的 Base64 编码，可用 openssl rand -base64 32 生成。环境变量或密钥文件格式无效时直接报错，不会自动覆盖。若已有加密绑定但密钥文件丢失，必须恢复原文件或原环境密钥，系统不会生成新密钥导致旧绑定无法解密。
请单独备份密钥；Docker 部署需持久化配置目录，仅挂载 JSON 配置文件不会保留旁边的密钥文件。共享数据库的多实例必须设置相同的环境密钥，或读取同一个共享密钥文件，不能各自独立生成。不要将密钥写入服务器定义；子进程不会继承该环境变量。
绑定采用 AES-256-GCM 加密，并将服务器名、用户名作为认证附加数据。JSON 模式保存到 <MCPHUB_SETTING_PATH>.credentials.json（默认路径则位于默认配置文件旁），权限为 0600，写入采用原子替换；数据库模式保存到 credential_bindings 表。常规配置导出不包含绑定。从文件迁移到数据库时复制密文，需继续使用原密钥。JSON 模式适用于单进程写入，多进程部署应使用数据库模式。
已有部署更换容器前，或升级后绑定无法使用时，请参照凭据密钥升级与恢复。
声明字段
stdio 使用env 或 args；SSE、Streamable HTTP 和 OpenAPI 使用 headers。每个字段包含 target、name 和可选 label，URL 槽还需提供 allowed 列表，最多 32 个字段。所有字段均为必填，不会回退到组织凭据。凭据按字面值注入，不展开环境变量；HTTP 头需填写完整值，例如包含 Bearer 前缀。个人头优先于静态头、透传头和 OpenAPI 工具参数头，不能与共享上游 OAuth 配置组合使用。
--api-key 参数优先于环境变量。
HTTP 服务器可声明 {"target":"headers","name":"Authorization"}。
仅支持命令行参数的凭据
对于只接受命令行参数凭据的 CLI，声明args 字段，并在参数中使用 {{args.API_KEY}}。将 API_KEY 替换为字段名（区分大小写，使用字母、数字或下划线，以字母或下划线开头）。在仪表板中选择“参数”作为凭据目标，每个参数使用一个独立输入框。
args.API_KEY 绑定值。占位符可以重复使用，也可以嵌入 --api-key={{args.API_KEY}} 这样的参数；每次都使用同一个个人值。所有 args 字段必须被引用，未知或格式错误的引用会被拒绝。env 和 args 字段可使用同一个名称，目标类型会区分它们。
MCPHub 在启动子进程时、普通环境变量展开和代理参数清洗完成后替换个人值。值中的空格、引号、$ 和类似占位符的文本按原样传入，不会递归展开，无需 shell 包装。不要把个人占位符放入 shell 脚本或其他可执行代码中，否则解释器会执行替换后的文本。即使 hub 日志和公开配置响应不含凭据，操作系统进程检查工具仍可能看到参数中的凭据。个人上游 OAuth 使用下文介绍的独立身份模式。
已有 POSIX shell 包装仍可使用。env 字段必须使用 "$my_api_key" 这样的无花括号小写引用：$MY_API_KEY 和 ${my_api_key} 可能在注入个人凭据之前被展开并清空。使用 sh -c 时，在仪表板中将 -c 和完整脚本分别放入两个参数输入框。
管理 API
自助接口使用仪表板 JWT（x-auth-token）、OIDC/session 登录，仅管理当前用户的绑定。用户级 MCP bearer key 仅用于 MCP 调用；系统 bearer key 不能使用自助接口。免登录模式不能管理个人绑定。
管理员可在 Credentials 页面选择用户，或从 Users 页的凭据操作进入。以下接口仅接受已认证管理员或
accessType: 'all' 的系统 bearer key：
目标用户必须已有本地记录，否则返回 404；不支持为尚未首次登录的 SSO 用户保存待绑定凭据。写入和删除要求服务器声明凭据模板且目标用户可发现该服务器，否则返回 404。普通用户和免登录 guest 返回 403。管理员能够改变目标用户使用的上游身份；已有值仍不返回。个人 OAuth 授权仍由用户本人完成。管理员代配不改变运行时身份：全权限系统 key 仍不能使用个人凭据。
PUT 请求示例：
复制凭据
已保存凭据的卡片默认展示脱敏值。选择“更新凭据”后填写全部字段进行替换，或选择“从其他服务器复制”展开复制操作。不可用来源仍会显示，并说明缺少字段、尚未配置凭据或 URL 允许值不兼容等原因。“更多操作 → 删除绑定”需要确认，并提示后续请求需要重新配置凭据。 在目标服务器的凭据卡片选择“从其他服务器复制”，再选择已配置且兼容的来源。来源和目标必须对同一目标用户可见。复制后两份绑定独立保存，修改或删除来源不会影响目标。复制密钥前请确认目标服务器可信。目标已有绑定时，需要明确确认覆盖。POST /api/credentials/:name/copy 复制当前用户的绑定；管理员可通过 POST /api/users/:username/credentials/:name/copy 复制指定用户自己的绑定。请求体为 { "sourceServer": "source-name", "overwrite": false }，成功返回 { "success": true }，不返回密钥。设置 overwrite: true 允许覆盖目标；若复制期间目标被并发修改，操作会失败，需要刷新后重试。
目标每个字段都必须在来源中有相同的 target 和 name（HTTP 请求头名称忽略大小写），来源多余字段不会复制。URL 值必须符合目标允许列表；页面保守地仅列出允许值全部被目标接受的来源。不支持跨字段映射、token 前缀转换、跨用户复制或个人 OAuth 复制。
运行方式与验证
每次请求读取最新绑定，身份来自当前登录用户或用户级 bearer key 的实际所有者，URL 或请求体中的用户名不参与凭据选择。 声明个人字段的服务器在首次发现或调用时启动。stdio 按(服务器, 用户) 隔离子进程，同一用户跨 MCP 会话复用，优先于 perSessionClient。子进程不作为独立服务器展示。所有活动请求结束后开始空闲计时，idleTimeoutMs 默认为五分钟；长调用期间不会回收。修改或删除绑定立即使本机对应运行实例失效，多进程部署中的其他实例在下次请求时读取最新绑定。
HTTP 客户端也按用户隔离，绑定改变时重新创建。个人工具、提示词和资源仅保存在个人运行实例中，不进入共享向量索引；普通路由可直接调用，向量搜索不索引个人目录。个人上游连接错误详情和 stderr 不对外输出，避免其中包含凭据。未声明个人字段的服务器保留原有行为。
预发布验证应使用不同的 Alice/Bob 真实密钥，并发调用 Tavily/Context7，再替换、删除 Alice 的绑定，确认 Bob 不受影响，同时验证空闲回收和邮箱形式的 OIDC 用户名。自动集成测试使用真实本机 stdio、HTTP、OpenAPI 测试服务器；真实 Tavily/Context7 API 联调需要部署方的测试凭据。
个人上游 OAuth
对于需要 OAuth 的 HTTP MCP 服务，配置oauth.identityMode: "personal"，或在 Dashboard 中选择「每位用户独立授权」。未设置此字段时保留共享 OAuth 行为。个人 OAuth 与手动凭据 slots 分开使用；个人模式的服务声明不能携带共享 token 或待授权状态。
/mcp/<group> 聚合入口；共享/系统 key 和匿名调用不支持个人 OAuth。未授权时返回「Personal authorization required」，不会回退到共享 token。
授权 MCP 客户端访问 MCPHub 不会连接用户的上游账号。用户需要先在 Dashboard → 服务器 中单独完成个人上游 OAuth，再重试工具发现。如果缺少个人授权导致 tools/list 没有工具可返回，MCPHub 返回 JSON-RPC 错误（-32000），其中 data.code 为 "PERSONAL_AUTHORIZATION_REQUIRED"，data.servers 列出需要授权的连接器。分组中存在其他可用工具时，仍正常返回这些工具。私有 broker 授权 relay 只转发已经创建的个人授权流程，不会从客户端的 MCPHub 同意流程中启动个人授权。
MCP SDK 自动发现 OAuth 端点，并为用户绑定动态注册客户端。上游禁用动态注册时，配置预注册的 oauth.clientId（机密客户端还需 oauth.clientSecret） 和回调 URI。自建 HTTP 环境继续使用管理员控制的 allowInsecureTokenEndpoint 例外；默认使用 HTTPS。
私有上游与授权服务器地址分离时，可用显式授权服务器元数据覆盖 SDK 授权服务器发现，保留个人存储和自动刷新。上游必须接受该授权服务器签发的 token 和 SDK 的 resource indicator。
token、客户端注册和 PKCE/state 加密保存到现有个人绑定存储，需备份前文所述加密密钥。待授权流程十分钟过期，期间可在重启后恢复，仅可使用一次；重新发起会替代旧流程。修改服务器定义会使原有个人授权失效，需要重新连接。
断开后立即删除本地授权并使当前用户的运行实例失效，不影响其他用户；知道撤销端点时尝试撤销上游 token。撤销失败不会恢复本地绑定，旧刷新或回调结果也不能重新写回。文件模式要求同一设置目录由单个 hub 进程管理；数据库模式使用条件写入拒绝过期版本。
以下接口仅供 Dashboard 登录身份使用，始终操作当前用户：
共用的
/oauth/callback 根据已保存的随机 state 确认流程归属，不能通过请求参数选择其他用户。
个人 HTTP 端点
SSE 和 Streamable HTTP 支持 URL 凭据槽，用同一服务器定义连接不同区域或租户：url.region 与其他槽一起绑定。URL 槽不能与 OAuth 同时使用。
占位符必须占满一个主机标签或路径段，不能用于协议、端口、用户信息、查询参数或片段。主机标签仅支持 ASCII 字母、数字和内部连字符，最多 63 个字符；路径段支持 ASCII 字母、数字、_、-、.、~，但不能是 . 或 ..。不接受编码或自由输入。每个 URL 槽都必须被引用；允许列表包含 1–256 个不重复的值，每个值最多 256 个字符。
保存绑定及每次获取用户运行实例时都会校验当前允许列表。移除选项后，旧绑定显示为未配置，下次请求会被拒绝，即使已有缓存连接；已在执行中的调用不会被追溯取消。带 URL 槽的服务器始终启用 SSRF 防护，包括管理员拥有的服务器；连接和重定向仍遵守 network.allowedCidrs。