エージェントメモリのためのMCPサーバー：Claude CodeをHotKVに接続する

MCPサーバーは、AIアシスタントに1回のチャットより長く続くメモリを持たせる、最も簡単な方法です。Claude CodeやCursorなどのクライアントは、チャットが終わるとそのコンテキストを失います。それを解決するために生のデータベースアクセスを渡すのは危険です。hotkv-mcpは、HotKV向けの私たちのオープンソースMCPサーバーです。アシスタントに、ノート、会話履歴、イベントログ、プロンプトテンプレート、ドキュメント検索のための固定のツールセットを提供します。それ以外は一切提供しません。

要点。 hotkv-mcpはApache-2.0のMCPサーバーで、Claude Code、Cursor、VS Code、または独自のエージェントを、28個の固定ツールを通じてHotKVサーバーに接続します。任意のコマンドを実行するツールはないので、アシスタントがデータをフラッシュしたり設定を変更したりすることはできません。読み取り専用モードではすべての書き込みツールが取り除かれ、名前空間によってエージェントは1つのキープレフィックスに閉じ込められます。インストールはpip install hotkv-mcpで、uvxで実行することもできます。

Model Context Protocolとは

Model Context Protocol（MCP）は、AIアプリケーションをデータソース、ツール、ワークフローなどの外部システムに接続するためのオープンな標準です。プロジェクトの紹介ページは、これをAIアプリケーションのUSB-Cポートにたとえています。MCPの用語では、アプリケーションがクライアントで、接続先の各システムはサーバーとして公開されます。

メモリの場合、アシスタントはノートを保存するツールのように、名前の付いたツールを呼び出します。そのツールに何を許すかは、サーバーが決めます。モデルが自分専用のデータベース接続を得ることはありません。

HotKVのMCPサーバーが公開するもの

このサーバーは、HotKVのエージェントメモリ、プロンプトレジストリ、ドキュメント検索を28個のツールで包んでいます。各ツールは、読み取りのみか、書き込みか、削除かを、MCPのアノテーションで宣言します。そのため、クライアントは破壊的なツールの前に承認を求めることができます。

メモリのツールは、AIエージェントのメモリで説明したストアのうち、会話履歴、作業メモ、イベントログに対応します。埋め込みによるセマンティックな呼び出しは公開していません。rag_searchはキーワードの関連度で順位付けするので、埋め込みは不要です。

キー、ハッシュ、リストのツールは、どのHotKVサーバーでも動作します。メモリ、プロンプト、ドキュメント検索のツールはHotKVのAIエンジンを使うため、それを含むライセンスが必要です。ライセンスがない場合、これらのツールは、サーバーがその機能のライセンスを持っていないというメッセージを返します。キーのツールは引き続き動作します。HotKV CloudのPerformanceプランとScaleプランのインスタンスにはAIエンジンが含まれています（AIページで説明しています）。

インストールと接続

サーバーにはPython 3.10以降が必要です。HotKVサーバー0.3.0と公式のhotkv-clientパッケージに対して作成されており、バージョン1.0.0がPyPIで公開されています。pipでインストールするか、uvを使ってインストールせずに実行できます。

pip install hotkv-mcp
uvx hotkv-mcp --url hotkv://localhost:6379

Claude Code

1つのコマンドで追加できます。Claude CodeのMCPドキュメントにあるとおり、--は、Claude Code自身のオプションと、サーバーを起動するコマンドを区切ります。

claude mcp add hotkv -- uvx hotkv-mcp --url hotkv://localhost:6379

CursorとClaude Desktop

mcpServersファイルを読み込むクライアントでは、同じサーバーをJSONのエントリとして指定します。パスワードはHOTKV_URL環境変数かクライアントのシークレットストアに置いてください。コマンドラインは、マシンの他のユーザーから見えるためです。TLS接続にはhotkvs://を使います。

{
  "mcpServers": {
    "hotkv": {
      "command": "uvx",
      "args": ["hotkv-mcp", "--read-only"],
      "env": { "HOTKV_URL": "hotkv://:your-password@localhost:6379" }
    }
  }
}

動作の確認

claude mcp listを実行して、サーバーが登録されていることを確認します。次に、アシスタントにserver_infoツールを呼び出すよう依頼します。これはHotKVのバージョンとメモリ使用量を返し、名前空間が未設定の場合はキーの数も返します。また、サーバーが読み取り専用かどうかと、どの名前空間に制限されているかも報告します。これで、セーフガードが有効になったことを確認できます。

エージェントを安全な範囲に収める

ツールを呼び出せるモデルは、ツールを悪用するよう言いくるめられる可能性もあります。そのため、機能より制限の方が重要です。

任意のコマンドは実行できない

生のコマンドを実行するツールはありません。28個のツールのどれもそれを行わないので、アシスタントがデータベースをフラッシュしたり、サーバーの設定を変更したりすることはできません。ただし、ツールが届くキーはどれでも読み取れます。そのため、次に説明する名前空間が重要になります。

読み取り専用モード

--read-onlyは、書き込みを行うすべてのツールを取り除きます。set、delete、hash_set、list_push、追加や消去を行うメモリのツール、prompt_save、rag_create、rag_ingestが含まれます。エージェントにはそれらが見えもしません。メモリを参照するだけで、変更はさせないアシスタントに使ってください。

名前空間とサイズの上限

--namespace PREFIXは、すべてをそのプレフィックスの下に保存します。エージェントにはプレフィックスが見えず、ほかの名前に到達することもできません。エージェントごとに、ほかのプレフィックスの先頭にならないプレフィックスを割り当ててください。agentとagent:bではなく、agent-aとagent-bを使います。そうしないと、短い方が長い方の名前に到達できてしまいます。

結果にも上限があります。--max-value-bytesは長い値を切り詰めて、切り詰めたことを示すフラグを付けます。デフォルトは65,536バイトです。--max-itemsは、1回の呼び出しが返すキー、リスト項目、ヒットの数を制限し、デフォルトは200です。そのため、巨大な値が1つあっても、モデルのコンテキストがあふれることはありません。ハッシュ全体の読み取りには項目数の上限が適用されないので、大きなハッシュはエージェントの名前空間に置かないでください。

HTTPトランスポートにはログインがない

デフォルトのstdioトランスポートは、クライアントがサブプロセスとして起動します。共有利用のために、hotkv-mcp --transport streamable-httpを実行すると、127.0.0.1:8000の/mcpで待ち受けます。呼び出し元の認証は行いません。localhostに留めるか、認証を行うリバースプロキシの背後に置き、専用の名前空間を与えてください。

チーム向けの構成の選び方

適切なフラグは、各エージェントの用途によって異なります。以下のオプションはすべてコマンドラインのフラグです。--read-onlyと--namespaceには、環境変数のHOTKV_MCP_READ_ONLYとHOTKV_MCP_NAMESPACEもあります。

目的を満たす中で最も制限の厳しい行から始めてください。アクセスを後から広げるのは簡単ですが、エージェントがすでに書き込んだものを取り戻すのは困難です。

最初のセッションを順に試す

短い試用で、実際のノートを任せる前に、セーフガードの働きを確認できます。使い捨ての名前空間と、AIエンジンのライセンスがあるローカルのHotKVサーバーを使ってください。ライセンスがないと、メモリのツールは動作しません。

1. 名前空間を付けて接続する。 claude mcp add hotkv -- uvx hotkv-mcp --url hotkv://localhost:6379 --namespace trialを実行します。
2. 制限を確認する。 アシスタントにserver_infoを呼び出して、名前空間と読み取り専用かどうかを報告するよう依頼します。trialで、読み取り専用ではないと答えるはずです。
3. ノートを保存する。 ステージングサイトが特定のアドレスにあることを、サイト名にちなんだ名前のノートとして覚えておくよう依頼します。アシスタントはmemory_set_noteを呼び出し、セッションは初回利用時に作成されます。
4. 新しいチャットで読み戻す。 新しい会話を始めて、そのセッションにどんなノートがあるかを尋ねます。memory_list_notesとmemory_get_noteが呼び出され、ノートは残っています。
5. 判断を記録する。 イベントログに判断を記録するよう依頼します。memory_log_eventが呼び出され、後でmemory_query_eventsでそれを取り出せます。
6. 書き込みアクセスを外す。 古いエントリを削除し、--read-onlyを付けて再接続して、手順4を繰り返します。読み取りは引き続き動作し、書き込みを行うツールは提示されなくなります。

手順6が説明どおりに動作すれば、最も重要な2つの制御、名前空間と読み取り専用モードの働きを確認できたことになります。

アシスタントが保存したものは、読み戻すときには信頼できないテキストとして扱ってください。メモリの記事の保存されたテキストを信頼しないで説明しているとおりです。Webページから書き込まれたノートには、指示が含まれていることがあります。

トラブルシューティング

• "This HotKV server is not licensed for that feature." メモリ、プロンプト、ドキュメント検索のツールには、AIエンジンを含むHotKVライセンスが必要です。キー、ハッシュ、リストのツールは、ライセンスなしでも動作します。
• 接続に失敗する。 URLのスキームを確認してください。hotkv://、hotkvs://（TLS）、redis://、rediss://のすべてが使え、パスワードはhotkv://:password@host:6379のようにURLに含めます。
• 値が途中で切れて返る。 結果が--max-value-bytesを超えると、切り詰められたことを示すフラグが付きます。上限を上げるか、より小さい値を保存してください。
• 書き込みツールがない。 サーバーの引数に--read-onlyがないか、環境にHOTKV_MCP_READ_ONLYがないかを確認してください。
• 以前に保存した名前をアシスタントが見つけられない。 同じセッション名またはエージェント名を使ったか、サーバーが以前と同じ名前空間で動作しているかを確認してください。
• uvxが見つからない。 uvをインストールするか、パッケージをpipでインストールしてhotkv-mcpを直接起動してください。

よくある質問