Claude Code

Claude Code 的 claude mcp add CLI 會幫你處理設定的編輯，並依專案或依使用者範圍保存註冊資訊。第一次呼叫 Engram 工具時，OAuth 會在你的瀏覽器中執行。想了解協定背景，請參閱 MCP。

先決條件

開始之前，請確認：

你在 app.engram.page 有一個 Engram 帳號。
至少有一個知識庫已同步。開啟 Obsidian 外掛或網頁版，確認筆記在最近一天內已完成同步。
你可以透過瀏覽器登入。MCP 驗證流程會開啟一個瀏覽器視窗。
如果你打算改用 API 金鑰而不是 OAuth：API 金鑰需要 Pro。 OAuth 登入在每個方案（包括 Free）都能使用，也是建議的做法。 Free 與 Starter 無法建立或使用 API 金鑰。

端點

https://mcp.engram.page

設定

1. 用 Claude Code CLI 註冊 Engram。

claude mcp add --transport http --scope user engram https://mcp.engram.page

--scope user 會讓 Engram 在每個專案中都可使用。改用 --scope project 則只限制在目前儲存庫的 .mcp.json。

想自己動手編輯？把下方區塊加入 ~/.claude.json （使用者範圍）或專案根目錄的 .mcp.json：

{
  "mcpServers": {
    "engram": {
      "url": "https://mcp.engram.page"
    }
  }
}

2. 重新載入。 結束目前的 Claude Code 工作階段，再重新執行 claude。執行 claude mcp list 確認 Engram 已註冊。它的狀態應該顯示為 △ needs authentication。

首次驗證

Claude Code 不會自動提示 OAuth。在新的工作階段中，執行 /mcp，選取 engram，再選擇 Authenticate。瀏覽器會開啟，讓你登入 Engram 並核准連線。 Claude Code 會儲存權杖，之後直接重複使用。授予的是完整的 mcp 範圍。更細緻的逐項操作範圍已列入路線圖。

告訴 Claude 如何使用它

把下方的片段附加到 ~/.claude/CLAUDE.md，也就是 Claude Code 的使用者層級指令檔，會套用到每個專案。各儲存庫自己的覆寫設定，請放在儲存庫根目錄的專案層級 CLAUDE.md。

Engram holds my personal notes — treat it as your long-term memory of me. Search it when a question depends on context I might have shared before. Before saving or updating a note, ask first.

試試看

註冊並完成驗證後，問 Claude：

在我的知識庫中搜尋有關工程師面試流程的筆記，並摘要最相關的三篇。
找出我上個月寫過的所有關於 embeddings 的內容。

Claude 會呼叫 Engram 的 search（或 get_note、write_note 等）工具，取回結果並就地回答。如果工具有被觸發，就設定完成了。

以 API 金鑰取代 OAuth

在無頭主機、CI 或共用知識庫的情境下，可以略過 OAuth，把連線固定使用 Engram API 金鑰。在 app.engram.page/settings/api-keys 產生一把，並以 Bearer 標頭傳送。

最快的做法是把金鑰直接寫進設定檔：

claude mcp add --transport http --scope user engram https://mcp.engram.page \
  --header "Authorization: Bearer engram_YOUR_KEY_HERE"

對 --scope user 來說沒問題（~/.claude.json 只存在你的機器上）。但對 --scope project 不行，因為 .mcp.json 是要被提交的。請改從環境變數載入金鑰。

從環境變數載入金鑰

Claude Code 在讀取 .mcp.json 時，會展開 ${VAR} 與 ${VAR:-default}。對 HTTP 伺服器來說，展開範圍涵蓋 url 與 headers 欄位，而 API 金鑰正是放在這裡。提交這個內容：

{
  "mcpServers": {
    "engram": {
      "type": "http",
      "url": "https://mcp.engram.page",
      "headers": {
        "Authorization": "Bearer ${ENGRAM_API_KEY}"
      }
    }
  }
}

儲存庫中只有變數名稱。每位貢獻者都提供自己的金鑰，而 Engram 會把每把金鑰限定在各自的帳號，所以共用的 .mcp.json 絕不代表共用知識庫。

Claude Code 讀取的是它啟動時的環境，所以請在啟動 claude 之前先匯出金鑰：

export ENGRAM_API_KEY="engram_YOUR_KEY_HERE"

如果要為每個儲存庫使用不同的金鑰，請使用 direnv，並把值放在被 gitignore 的 .envrc：

export ENGRAM_API_KEY="engram_YOUR_KEY_HERE"

執行一次 direnv allow，然後在該目錄中啟動 claude。

如果沒有設定該變數， 設定仍會載入，Claude Code 會送出字面字串 Bearer ${ENGRAM_API_KEY}，Engram 會以 401 拒絕。 claude mcp list 會標出這個問題：

[Warning] [engram] mcpServers.engram: Missing environment variables: ENGRAM_API_KEY

使用金鑰的設定無法連接時，請先檢查有沒有這一行。

使用金鑰後有兩件事會改變。第一次連接時不會開啟瀏覽器，而且 /mcp 不再提供 Authenticate：設定 Authorization 標頭會完全停用 OAuth 後備機制。金鑰涵蓋的範圍與輪替方式，請參閱 MCP 設定 → API 金鑰驗證。

疑難排解（Claude Code 專屬）

claude mcp list 沒有顯示 engram。 指令是在與預期不同的範圍中執行的。請檢查 ~/.claude.json（使用者）與 .mcp.json（專案）中有沒有該項目，然後以正確的 --scope 旗標重新執行 claude mcp add。
/mcp 的選單中沒有 engram。 你在 claude mcp add 之後沒有結束並重新啟動 CLI。請重新啟動 claude。
Authenticate 選項沒有反應，或瀏覽器一直沒有開啟。 無頭或遠端工作階段無法開啟瀏覽器。請在有桌面瀏覽器的主機上執行 Claude Code，或改用 API 金鑰。

跨用戶端的故障請參閱疑難排解。

撤銷

要讓 Claude Code 與 Engram 斷開連線：

在Claude Code中，找到該連接器或 MCP 伺服器項目並移除。
在 Engram 中，開啟你的帳號 → API Keys & Sessions，撤銷對應的工作階段。
OAuth 權杖會在伺服器端失效。Claude Code需要重新驗證才能再次連接。

你也可以用 claude mcp remove engram 在本機移除註冊。這只會移除設定項目，伺服器端的權杖在你於 Engram 撤銷之前仍然有效。

後續步驟

MCP協定概覽。

範圍授權涵蓋的內容。

所有整合挑選其他用戶端。