Clarity

mcp

API 密钥与安全

Clarity 如何在使用 MCP 时保护您的项目和数据。

API 密钥的工作原理

当您在 设置 → MCP / API 中创建 API 密钥时，Clarity 会：

  1. 1使用 Node.js crypto.randomBytes 生成 32 个加密随机字节
  2. 2将其编码为带有前缀 sk_clarity_ 的 base64url 字符串
  3. 3计算完整密钥的 SHA-256 哈希值
  4. 4在数据库中 仅存储哈希值
  5. 5仅一次 向您返回明文密钥

明文密钥在创建后绝不会被存储、记录或传输。如果丢失，您必须生成新的密钥。

认证流程

每个 MCP API 请求都遵循以下路径：

  1. 1您的 AI 客户端在 Authorization: Bearer 请求头中发送明文密钥
  2. 2Clarity API 使用 SHA-256 对传入的密钥进行哈希
  3. 3使用 计时安全比较（crypto.timingSafeEqual）将哈希值与所有活跃密钥哈希进行比对
  4. 4匹配成功后，提取关联的 user_id 并继续处理
  5. 5后续每个操作都会验证用户是否拥有所请求的资源

计时安全比较可防止攻击者通过测量响应时间来获取有关您密钥的任何信息。

所有权验证

API 密钥认证只是第一层。每个端点还会检查 资源所有权：

端点所有权检查
列出项目筛选 user_id 匹配的项目
列出 / 创建文件验证项目属于该用户
读取 / 写入 / 删除文件验证文件属于该用户
编译 / 调试验证项目属于该用户

密钥管理最佳实践

  • 使用描述性标签 —— 以客户端名称命名密钥
  • 每个客户端一个密钥 —— 不要在多台机器上重复使用同一密钥
  • 先禁用再删除 —— 如果密钥泄露，立即将其关闭
  • 定期轮换 —— 每几个月生成一个新密钥
  • 永远不要提交密钥 —— 将您的 MCP 配置添加到 .gitignore

密钥限制

特性限制
每位用户密钥数5
密钥长度48 个字符（32 个随机字节 + 前缀）
撤销即时

MCP 能做和不能做的事

MCP 能：

  • 列出您的所有项目并浏览文件树
  • 读取、写入、创建和删除项目中的文件
  • 编译 LaTeX 和 Typst 文档
  • 通过结构化分析调试编译错误
  • 搜索内置的 Typst 文档
  • 阅读完整的 Typst 文档页面
  • 生成 TikZ 插图和图表

MCP 不能：

  • 创建或删除整个项目
  • 删除项目的主入口文件
  • 删除非空文件夹
  • 在文件夹之间重命名或移动文件
  • 上传二进制文件（图片、PDF、字体）
  • 访问其他用户的数据或项目
  • 修改账户设置、个人资料或偏好
  • 访问账单、支付或订阅信息
  • 共享或发布项目
  • 管理协作者或权限
  • 绕过所有权验证

审计追踪

每次使用您的 API 密钥时，Clarity 都会更新设置 → MCP / API 中可见的 上次使用时间 时间戳。

这对您有帮助吗？
上一页工具参考下一页 设置
API 密钥与安全 — Clarity Docs