部署配置
单实例部署可以不设置MCPHUB_CREDENTIAL_ENCRYPTION_KEY。首次保存绑定时，MCPHub 会生成 32 字节随机密钥，以 0600 权限原子创建配置文件旁的 <MCPHUB_SETTING_PATH>.credentials.key（未指定配置路径时使用默认配置文件旁的路径），重启后继续读取同一文件。密钥文件不进入配置导出、Git 或 Docker 构建上下文。配置目录必须可写；持久化失败时会拒绝保存，不使用临时密钥。
显式设置的环境变量优先，值必须是 32 字节随机数据的 Base64 编码，可用 openssl rand -base64 32 生成。环境变量或密钥文件格式无效时直接报错，不会自动覆盖。若已有加密绑定但密钥文件丢失，必须恢复原文件或原环境密钥，系统不会生成新密钥导致旧绑定无法解密。
请单独备份密钥；Docker 部署需持久化配置目录，仅挂载 JSON 配置文件不会保留旁边的密钥文件。共享数据库的多实例必须设置相同的环境密钥，或读取同一个共享密钥文件，不能各自独立生成。不要将密钥写入服务器定义；子进程不会继承该环境变量。
绑定采用 AES-256-GCM 加密，并将服务器名、用户名作为认证附加数据。JSON 模式保存到 <MCPHUB_SETTING_PATH>.credentials.json（默认路径则位于默认配置文件旁），权限为 0600，写入采用原子替换；数据库模式保存到 credential_bindings 表。常规配置导出不包含绑定。从文件迁移到数据库时复制密文，需继续使用原密钥。JSON 模式适用于单进程写入，多进程部署应使用数据库模式。
声明字段
stdio 使用env；SSE、Streamable HTTP 和 OpenAPI 使用 headers。每个字段仅包含 target、name 和可选 label，最多 32 个。所有字段均为必填，不会回退到组织凭据。凭据按字面值注入，不展开环境变量；HTTP 头需填写完整值，例如包含 Bearer 前缀。个人头优先于静态头、透传头和 OpenAPI 工具参数头，不能与共享上游 OAuth 配置组合使用。
--api-key 参数优先于环境变量。
HTTP 服务器可声明 {"target":"headers","name":"Authorization"}。
管理 API
使用仪表板 JWT（x-auth-token）、OIDC/session 登录或用户 OAuth access token。用户级 MCP bearer key 仅用于 MCP 调用；系统 bearer key 和免登录模式不能管理个人绑定。接口不接受目标用户名。
PUT 请求示例：
运行方式与验证
每次请求读取最新绑定，身份来自当前登录用户或用户级 bearer key 的实际所有者，URL 或请求体中的用户名不参与凭据选择。 声明个人字段的服务器在首次发现或调用时启动。stdio 按(服务器, 用户) 隔离子进程，同一用户跨 MCP 会话复用，优先于 perSessionClient。子进程不作为独立服务器展示。所有活动请求结束后开始空闲计时，idleTimeoutMs 默认为五分钟；长调用期间不会回收。修改或删除绑定立即使本机对应运行实例失效，多进程部署中的其他实例在下次请求时读取最新绑定。
HTTP 客户端也按用户隔离，绑定改变时重新创建。个人工具、提示词和资源仅保存在个人运行实例中，不进入共享向量索引；普通路由可直接调用，向量搜索不索引个人目录。个人上游连接错误详情和 stderr 不对外输出，避免其中包含凭据。未声明个人字段的服务器保留原有行为。
预发布验证应使用不同的 Alice/Bob 真实密钥，并发调用 Tavily/Context7，再替换、删除 Alice 的绑定，确认 Bob 不受影响，同时验证空闲回收和邮箱形式的 OIDC 用户名。自动集成测试使用真实本机 stdio、HTTP、OpenAPI 测试服务器；真实 Tavily/Context7 API 联调需要部署方的测试凭据。