Claude Code

Claude Code 的 claude mcp add CLI 会替你完成配置编辑，并按项目或按用户保存注册信息。OAuth 会在你第一次调用 Engram 工具时在浏览器中运行。协议背景请参阅 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 中启用 Engram。

想手动编辑？把下面的配置块添加到 ~/.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协议概览。

权限范围授权涵盖哪些内容。

所有集成选择其他客户端。