> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcphub.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 个人凭据

> 一个共享 MCP 服务器定义，为每位用户绑定独立凭据

管理员或服务器所有者声明个人凭据字段，用户在**凭据**页面或服务器卡片入口绑定自己的值。共享用户可以查看字段名和显示名称，无法读取服务器连接配置，也无法读取其他用户的绑定。保存后的值无法回读，只能替换或删除。

## 部署配置

单实例部署可以不设置 `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 配置组合使用。

```json theme={null}
{
  "mcpServers": {
    "tavily": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "tavily-mcp"],
      "owner": "admin",
      "visibility": "public",
      "idleTimeoutMs": 300000,
      "credentialTemplate": [
        { "target": "env", "name": "TAVILY_API_KEY", "label": "Tavily API key" }
      ]
    },
    "context7": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "owner": "admin",
      "visibility": "public",
      "credentialTemplate": [
        { "target": "env", "name": "CONTEXT7_API_KEY", "label": "Context7 API key" }
      ]
    }
  }
}
```

环境变量来自 [Tavily 官方说明](https://github.com/tavily-ai/tavily-mcp)和 [Context7 开发指南](https://github.com/upstash/context7/blob/master/docs/resources/developer.mdx)。迁移时移除命令行中的旧凭据：Context7 的 `--api-key` 参数优先于环境变量。

HTTP 服务器可声明 `{"target":"headers","name":"Authorization"}`。

## 管理 API

使用仪表板 JWT（`x-auth-token`）、OIDC/session 登录或用户 OAuth access token。用户级 MCP bearer key 仅用于 MCP 调用；系统 bearer key 和免登录模式不能管理个人绑定。接口不接受目标用户名。

| 方法     | 路径                       | 行为                                                            |
| ------ | ------------------------ | ------------------------------------------------------------- |
| GET    | `/api/credentials`       | 返回可见服务器的字段元数据、`configured`、`configuredSlots`、`updatedAt`，不返回值 |
| PUT    | `/api/credentials/:name` | 替换当前用户的完整绑定                                                   |
| DELETE | `/api/credentials/:name` | 删除当前用户的绑定                                                     |

PUT 请求示例：

```json theme={null}
{ "values": { "env.TAVILY_API_KEY": "your-personal-api-key" } }
```

替换时需要填写全部字段，未声明字段会被拒绝。重新打开页面时输入框保持空白。删除用户或服务器会删除对应绑定；重命名服务器会删除旧名称下的绑定，用户需重新绑定。新增必填字段后也需重新填写完整绑定。

## 运行方式与验证

每次请求读取最新绑定，身份来自当前登录用户或用户级 bearer key 的实际所有者，URL 或请求体中的用户名不参与凭据选择。

声明个人字段的服务器在首次发现或调用时启动。stdio 按 `(服务器, 用户)` 隔离子进程，同一用户跨 MCP 会话复用，优先于 `perSessionClient`。子进程不作为独立服务器展示。所有活动请求结束后开始空闲计时，`idleTimeoutMs` 默认为五分钟；长调用期间不会回收。修改或删除绑定立即使本机对应运行实例失效，多进程部署中的其他实例在下次请求时读取最新绑定。

HTTP 客户端也按用户隔离，绑定改变时重新创建。个人工具、提示词和资源仅保存在个人运行实例中，不进入共享向量索引；普通路由可直接调用，向量搜索不索引个人目录。个人上游连接错误详情和 stderr 不对外输出，避免其中包含凭据。未声明个人字段的服务器保留原有行为。

预发布验证应使用不同的 Alice/Bob 真实密钥，并发调用 Tavily/Context7，再替换、删除 Alice 的绑定，确认 Bob 不受影响，同时验证空闲回收和邮箱形式的 OIDC 用户名。自动集成测试使用真实本机 stdio、HTTP、OpenAPI 测试服务器；真实 Tavily/Context7 API 联调需要部署方的测试凭据。