Clarity

mcp

API 金鑰與安全性

Clarity 如何在使用 MCP 時保護您的專案和資料。

API 金鑰的運作方式

當您在 Settings → MCP / API 中建立 API 金鑰時，Clarity 會：

  1. 1使用 Node.js crypto.randomBytes 生成 32 個密碼學安全隨機位元組
  2. 2以 base64url 編碼並加上 sk_clarity_ 前綴
  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 匹配的專案
列出 / 建立檔案驗證專案屬於該使用者
讀取 / 寫入 / 刪除檔案驗證檔案屬於該使用者
編譯 / 除錯驗證專案屬於該使用者

這意味著即使兩位使用者有相同的 API 金鑰雜湊值（由於唯一性約束，這是不可能的），他們也永遠無法存取彼此的資料。

金鑰管理最佳實踐

  • 使用描述性標籤 — 以客戶端名稱命名金鑰（如「Claude Desktop」、「Cursor 筆電」），以便在金鑰洩露時知道要撤銷哪一個
  • 每個客戶端使用一個金鑰 — 不要在多台機器或工具之間重複使用同一個金鑰
  • 停用後再刪除 — 如果您懷疑金鑰已洩露，請立即透過設定中的開關停用，然後進行調查
  • 定期輪換 — 每隔幾個月生成新金鑰並撤銷舊金鑰
  • 永遠不要提交金鑰 — 如果您的 MCP 設定包含明文金鑰，請將其加入 .gitignore

金鑰限制

功能限制
每位使用者的金鑰數量5
金鑰長度48 字元（32 隨機位元組 + 前綴）
撤銷立即生效 — 在下一次 API 請求時生效

MCP 可以和不可以做什麼

MCP 可以：

  • 列出您所有的專案並瀏覽檔案樹
  • 讀取、寫入、建立和刪除專案中的檔案
  • 編譯 LaTeX 和 Typst 文件
  • 使用結構化分析除錯編譯錯誤
  • 搜尋內建的 Typst 文件（語言功能 + Touying 框架）
  • 讀取完整的 Typst 文件頁面
  • 生成 TikZ 插圖和圖表

MCP 不可以：

  • 建立或刪除整個專案（僅能操作專案內的檔案）
  • 刪除專案的主要入口檔案
  • 刪除非空資料夾（必須先移除內容）
  • 重新命名或在資料夾之間移動檔案
  • 上傳二進位檔案（圖片、PDF、字型）
  • 存取其他使用者的資料或專案
  • 修改帳號設定、個人資料或偏好設定
  • 存取帳單、付款或訂閱資訊
  • 分享或發佈專案
  • 管理協作者或權限
  • 繞過所有權驗證

稽核軌跡

每次使用您的 API 金鑰時，Clarity 會更新 Settings → MCP / API 中可見的 最後使用時間 時間戳記。這可協助您：

  • 確認您的 MCP 連線處於活動狀態
  • 識別近期未使用的過時金鑰
  • 偵測異常的使用模式
這對您有幫助嗎？
上一頁工具參考下一頁 設定
API 金鑰與安全性 — Clarity Docs