Claude Code

Claude Code の claude mcp add CLI は、設定の編集を代わりに行い、登録をプロジェクト単位またはユーザー単位で管理します。OAuth は、 Engram のツールを初めて呼び出したときに、ブラウザーで実行されます。プロトコルの背景については、MCP を参照してください。

前提条件

はじめる前に、次を確認してください。

app.engram.page に Engram アカウントがある。
少なくとも 1 つの保管庫が同期されている。Obsidian プラグインまたは Web アプリを開き、直近 1 日以内にノートが同期されていることを確認してください。
ブラウザーでサインインできる。MCP の認証フローはブラウザーウィンドウを開きます。
OAuth の代わりに API キーを使う予定の場合: 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 を使うと、Engram は現在のリポジトリの .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 Code のユーザーレベルの指示ファイルである ~/.claude/CLAUDE.md に追記します。すべてのプロジェクトに適用されます。リポジトリごとに上書きしたい場合は、リポジトリのルートにあるプロジェクトレベルの 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 に聞いてみてください。

保管庫からエンジニア採用面接のプロセスに関するノートを検索して、上位 3 件を要約して。
先月書いた、埋め込みに関するものをすべて探して。

Claude が Engram の search (または get_note、write_note など) ツールを呼び出し、結果を取り出して、その文脈で答えます。ツールが呼び出されたら、設定は完了です。

OAuth の代わりに API キーを使う

ヘッドレスのマシン、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 しておきます。

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

キーを使った設定で接続できないときは、まずこの行を確認してください。

キーを使うと、2 つのことが変わります。初回の接続でブラウザーは開かず、/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プロトコルの概要。

スコープ付与の対象範囲。

すべての連携別のクライアントを選ぶ。