MCP サーバー¶
BombVault には、Model Context Protocol(MCP)の組み込みサーバーがあります。MCP は、Claude Code や Claude Desktop などの AI アシスタントが外部のツールに接続するために使うプロトコルです。これを通じて、アシスタントはバックアップの状況を読み取れ、許可すればバックアップを開始したり、自分が開始したものを中止したりできます。キーを作成するか、OAuth によるサインインをオンにするまでオフで、それまでは /mcp エンドポイントはすべてに 404 で応答します。
アシスタントにできること、できないこと¶
| ツール | 内容 | 種類 |
|---|---|---|
get_health |
バージョン、インスタンス名、バックアップが実行中かどうか、このキーにできること | 読み取り |
get_status |
ドメインごとの保護ステータス:直近の成功したバックアップ、想定される間隔、検証とオフサイトのチェック、次回のスケジュール実行、アプリのアイドルを待っているバックアップ、コンテナについては最新の起動テスト | 読み取り |
get_coverage |
BombVault が保護しているものとしていないもの。それぞれに理由つき | 読み取り |
list_items |
保護されているすべてのコンテナ、VM、フォルダーセット、フラッシュドライブ、アプリの設定と、そのスケジュール、バックアップが停止するもの、直近のバックアップとその所要時間。データベースのコンテナには直近のダンプも付きます。ZFS データセットも、直近のチェックの結果とともに一覧されます。すべての項目に直近の復元チェックが付き、コンテナには直近の起動テスト、またはテストできない理由が付きます。前回のバックアップ以降に別の設定で作り直されたコンテナには、変わったものが一覧されます | 読み取り |
list_runs |
実行履歴を新しい順に。ドメイン、項目、状態、種類、時刻で絞り込めます。遅かったバックアップは、足を引っ張った要因を名指しします | 読み取り |
list_restore_points |
1 つの項目のプライマリリポジトリにあるリストアポイントと、コンテナについてはそのデータベースダンプ。ZFS データセットはバックアップごとに 1 つのリストアポイントを持ち、その下のすべてのデータセットのスナップショットが付きます | 読み取り |
get_activity |
今実行中のもの。フェーズと進捗率つき | 読み取り |
get_storage_stats |
1 つのドメインのプライマリリポジトリのサイズ履歴と週あたりの増加、そしてそのリポジトリそれぞれのディスクまたはリモートの使用量、空き容量、合計 | 読み取り |
get_size_breakdown |
1 つのコンテナ、VM、フォルダーセットの最新のバックアップで、どのフォルダーとファイルが容量を使っているか、そして直近のバックアップがそれぞれどれだけ追加したか | 読み取り |
search_files |
すべての項目、1 つのドメイン、または 1 つの項目のバックアップから、名前でファイルとフォルダーを探します(VM は対象外)。見つかったものごとに、それを含むバックアップをすべて示します | 読み取り |
list_anomalies |
BombVault がバックアップで気づいた異常。状態、重要度、ドメインで絞り込め、未処理のものの概要つき | 読み取り |
get_anomaly |
その検出結果の 1 件。確認済みにしたときに残したメモつき | 読み取り |
start_backup |
1 つの項目を今すぐバックアップ | 開始 |
start_domain_backup |
1 つのドメインの保護されているすべての項目をバックアップ | 開始 |
start_backup_everything |
「すべてバックアップ」のパスを実行 | 開始 |
cancel_backup |
このキーが開始した実行中のバックアップを中止 | 中止 |
次のことは Web 画面にとどまります。あらゆる種類の復元(データベースダンプのダウンロード、保存、インポートを含む)、バックアップの削除、プルーン、ロック解除、チェックとドリル、オフサイトの複製、設定、認証情報、MCP キー、そしてスケジュール、Web 画面、別のキーが開始したバックアップの中止です。異常を確認済みにしたり想定どおりと印を付けたりするのも同じで、異常ページで行います。理由は、ツールの出力に、あなたのサーバーの名前やエラーメッセージが含まれていて、その中にアシスタントを誘導するように書かれたテキストが含まれうるからです。そのようなテキストに引っかかったアシスタントでも、最悪の場合にできるのは、下の制限の範囲内でバックアップを開始するか、自分が開始したものを中止することだけです。
項目のプライマリリポジトリがリモート(S3、REST、SFTP、rclone)の場合、list_restore_points はそこに接続するため、呼び出しに時間がかかることがあります。オフサイトのコピーは MCP では一覧できません。search_files は、オフサイトのコピーを含むリモートのリポジトリを、アシスタントが求めたときだけ読みます。時間がかかり、ダウンロードしたデータに料金がかかるプロバイダーもあるためです。検索には数分かかることがあるので、最初の呼び出しでバックグラウンドで始め、後の呼び出しで結果を受け取ります。異常チェックが見るものは異常で、ZFS 項目がデータセットごとに 1 つのスナップショットを持つ仕組みは ZFS データセットで説明しています。
開始したバックアップは何をするか¶
アシスタントのバックアップは、Web 画面が開始するバックアップと同じものです。実行中のコンテナは、バックアップが終わるまで、一緒に停止するよう設定されたコンテナとともに停止します。グレースフル方式の VM はシャットダウンされ、再び起動されます。ZFS データセットは、スナップショットを取るあいだ、それ用に設定されたコンテナを停止します。フォルダーセット、フラッシュドライブ、設定は動いたままです。その後、BombVault は保持ポリシーを適用し、オフサイトのリポジトリにコピーすることがあります。list_items は、アシスタントに、項目が何を停止するか、直近のバックアップにどのくらいかかったかを伝え、ツールの説明は、何かを開始する前にあなたに伝えるよう求めています。
バックアップは何かを停止し、古いリストアポイントを入れ替えるので、MCP 経由の開始には制限があります。
- キーごとに 1 時間に 12 回までの開始。
- 同じ項目、ドメイン、または「すべてバックアップ」の MCP による 2 回の開始のあいだは 15 分。
- 同じ項目の MCP による開始は、24 時間に最大 4 回。
- 保持ガード。 ドメインが固定数のリストアポイントを保持する場合(「直近 N 件を保持」だけで、日次、週次、月次のルールがなく、ローカルでもオフサイトの保存先でも)、新しいバックアップのたびに最も古いものが押し出されます。そこで BombVault は、最新の N-1 件の成功したバックアップがすべて MCP 経由で開始されたものである項目の、MCP による開始を拒否します。これにより、スケジュールまたはあなたが作ったリストアポイントが、保持される集合に必ず 1 つは残ります。「直近 1 件を保持」だと、アシスタントはその項目をまったくバックアップできません。次のスケジュールされたバックアップが、再び空きを作ります。年次ルールだけの場合は、当年の 1 つのリストアポイントを保持するので、「直近 1 件を保持」として数えられます。
ドメインまたは「すべてバックアップ」の開始では、制限で止められた項目は除外され、応答にその名前が示されます。Web 画面とスケジュールには、これらの制限は一切かかりません。1 時間あたりの枠はメモリ上にあるので、BombVault を再起動するとリセットされます。
API と Home Assistant からの開始も、MCP 経由の開始と同じ項目ごとの制限と保持ガードに数えられます。
オンにする¶
- 設定、連携、MCP サーバー を開き、クライアントを選択をクリックして、ウィンドウで自分のクライアントを選びます。右上の検索で名前から探せます。一覧にないクライアントは、その他のクライアントから接続します。
- キーで、新しいキーと、クライアント名の提案された名前をそのまま使うか、「ノートパソコンの Claude Code」のように、どこで使うキーかが分かる名前を入力します。クライアントごとに 1 つのキーにすると、ほかに影響せずに 1 つだけ取り消せます。既存のキーを選ぶと、以前に作ったキーをそのクライアントに渡します。
- バックアップを開始できるようにしたいキーでは、バックアップの開始を許可をオンにします。オンにしないと、そのキーは読み取りだけができます。あとからキーの詳細で変更でき、変更はアシスタントの次のリクエストから反映されるため、再接続は不要です。
- キーを作成をクリックします。キーは一度だけ表示されます。BombVault はそのフィンガープリントしか保持せず、もう一度表示することはできないので、今すぐコピーしてください。クライアントがキーを使う前にウィンドウを閉じても、コピーしたと確認するまで、カードは表示し続けます。
ログインパスワードがないと、Web 画面自体がネットワーク上の誰にでも開かれていて、それを開ける人なら誰でもキーを作成できます。カードにもそう表示されます。公開されているように見える名前(たとえばリバースプロキシ経由の bombvault.example.com)で BombVault を開いていて、ログインパスワードが設定されていない場合、そのアドレスからはキーの作成も交換もできません。インターネット上のどのページも、あなたのブラウザーにキーを作らせることができないようにするためです。ログインパスワードを設定するか、IP アドレスや tower、tower.local のようなローカルの名前で BombVault を開いてください。
キーとそのログ¶
各キーには、キーとサインイン済みクライアントの下に専用の行があります。そこには、キーの名前、バックアップを開始できるか読み取り専用か、キーの末尾 4 文字、作成または最後に交換された日時、クライアントが最後に使った日時が表示されます。詳細を開くと、キーの名前変更、権限の変更、交換、取り消しができるウィンドウが開き、今日行った呼び出しの数も分かります。取り消したキーは、取り消したキーの一覧に移り、履歴のどの実行にもその名前がなくなれば、完全に削除できます。
名前の横の行には、そのキーを作ったクライアントのマークが表示されます。その他のクライアントで作ったキーや、カードがクライアントを一覧する前に作ったキーでは、代わりに鍵のマークが表示されます。
キーの詳細にあるログには、そのキーが行ったことが表示され、取り消したキーにも専用のログボタンが残ります。開始したバックアップが最初に、それぞれの状態と、ダッシュボードのアクティビティログのその実行へのリンクとともに並びます。その下に呼び出しが新しい順に、ツールと呼び出しの結果とともに並びます。拒否された場合は理由が書かれます。キーが読み取り専用だった、保持ガードがバックアップを止めた、別のバックアップがすでに実行中だった、同じ項目、ドメイン、パスが数分前に Web 画面の外から開始された、キーがリクエストを送りすぎた、などです。中止は、対象の実行にリンクします。
BombVault は各キーの記録を最大 30 日間保持します。成功した開始と中止は新しい順に 500 件、その横に、それ以外の呼び出し(読み取り、拒否、エラー)が新しい順に 200 件です。実行中のバックアップをポーリングし続けるアシスタントや、拒否された呼び出しを再試行し続けるアシスタントが、そのバックアップの開始をログから押し出すことはできません。呼び出しごとに、ツール、結果、中止が指した実行を保存します。アシスタントが送った内容は保存せず、キーやそのフィンガープリントも保存しません。診断バンドルは記録の件数を数えるだけで、設定のエクスポートには含まれません。
クライアントを接続する¶
クライアントを選択を押すと、すべてのクライアントがタイルになったウィンドウが、このコンピューター上またはクラウドの下に並び、右上に検索があります。タイルを押すと、同じウィンドウでそのクライアントのセットアップが 3 つの手順で開きます。キー、そのクライアント向けの設定(カードを開いたアドレスが入っています)、それをコピーするボタン、設定を置く場所、そして BombVault 自身の証明書を使う場合にクライアントがそれを信頼するために必要なこと、そしてクライアントの最初の呼び出しを待つ手順です。ウィンドウはキーの最後の使用を監視し、その呼び出しが届くと緑になります。
セットアップでは、キーがコマンドラインに現れません。クライアントが環境変数(BOMBVAULT_MCP_KEY)、マスクされた入力、または専用のファイルから読み取れる場合、設定にはその名前だけが書かれます。クライアントにそうした方法がない場合は、キーがクライアントの設定ファイルまたは設定に入り、セットアップにもそう書かれます。クライアントのドキュメントに、知らない証明書の扱いが書かれていない場合は、クライアントが BombVault の証明書を拒否したときにすることとして、その手順が書かれます。
| クライアント | セットアップ | キーの取得元 |
|---|---|---|
| AnythingLLM | 設定ファイル | 設定ファイル |
| Antigravity | 設定ファイル | 環境変数 |
| Claude Code | コマンド | キーファイル |
| Claude Desktop | 設定ファイル | キーファイル |
| Cline | 設定ファイル | 設定ファイル |
| Codex CLI | 設定ファイル | 環境変数 |
| Continue | 設定ファイル | ~/.continue/.env |
| Copilot CLI | 設定ファイル | 設定ファイル |
| Cursor | 設定ファイル | 環境変数 |
| Gemini CLI | 設定ファイル | 環境変数 |
| GitHub Copilot (VS Code) | 設定ファイル | マスクされた入力 |
| Goose | 設定ファイル | 環境変数 |
| Jan | アプリ内のフォーム | アプリの設定 |
| JetBrains (AI Assistant, Junie) | 設定ファイル | 設定ファイル |
| Kimi Code | 設定ファイル | 設定ファイル |
| LM Studio | 設定ファイル | 設定ファイル |
| Mistral Vibe | 設定ファイル | 環境変数 |
| Msty | アプリ内のフォーム | アプリの設定 |
| n8n | アプリ内のフォーム | n8n の認証情報ストア |
| Open WebUI | アプリ内のフォーム | アプリの設定 |
| opencode | 設定ファイル | 環境変数 |
| Perplexity (Mac) | アプリ内のフォーム | キーファイル |
| Qwen Code | 設定ファイル | 環境変数 |
| Roo Code | 設定ファイル | 環境変数 |
| Visual Studio | 設定ファイル | 設定ファイル |
| Warp | 設定ファイル | 設定ファイル |
| Windsurf | 設定ファイル | 環境変数 |
| Zed | 設定ファイル | 設定ファイル |
| Grok | フォーム(クラウド) | ベンダーのサーバー |
| Le Chat | フォーム(クラウド) | ベンダーのサーバー |
| ChatGPT | OAuth によるサインイン(クラウド) | アクセストークン。下を参照 |
| Claude (claude.ai) | OAuth によるサインイン(クラウド) | アクセストークン。下を参照 |
以降のセクションでは、Claude Code と Claude Desktop のセットアップをもう少し詳しく説明し、ほかのクライアントに必要なものを一覧にします。
Claude Code¶
Claude Code は mcp-remote を通じて BombVault に接続します。そのコンピューターに Node.js が必要です。まず、キーを専用のテキストファイルに、1 行で保存します。
次に、カードにあるコマンドを、そのファイルのパスを入れて、ターミナルで一度実行します。コンピューターが信頼する証明書の背後なら、次のようになります。
claude mcp add bombvault --scope user -- npx -y mcp-remote@latest https://bombvault.example.com/mcp --header-file "<path of the file with your key>"
BombVault 自身の証明書を使う場合(TLS と証明書を参照)は、コマンドで Node.js にダウンロードした証明書も指定します。
claude mcp add bombvault --scope user -e "NODE_EXTRA_CA_CERTS=<path of the downloaded bombvault-cert.pem>" -- npx -y mcp-remote@latest https://192.168.1.10:3443/mcp --header-file "<path of the file with your key>"
接続は Claude Code の中で /mcp で確認します。--scope user で、すべてのプロジェクトで BombVault が使えるようになります。Claude Code が保持するのはキーファイルのパスだけなので、キーはコマンドやシェルの履歴にも、プロセス一覧にも現れません。ファイルは自分だけが読める場所に置き、コミットするフォルダーの外にしてください。@latest は、npx に最新の mcp-remote を取得させます。グローバルにインストールされた古いものが使われると、--header-file を知らないからです。
Claude Code の mcp-remote の引数に ${BOMBVAULT_MCP_KEY} を書かないでください。Claude Code は、このような参照を、mcp-remote を起動する前に自分の環境から埋めるので、キーがそのプロセスのコマンドラインに入り、コンピューターの他のプログラムやユーザーが読めてしまいます。
Node.js がなく、コンピューターが信頼する証明書の背後であれば、Claude Code は単独で接続できます。プロジェクトフォルダーに .mcp.json を置きます。
{
"mcpServers": {
"bombvault": {
"type": "http",
"url": "https://bombvault.example.com/mcp",
"headers": {
"Authorization": "Bearer ${BOMBVAULT_MCP_KEY}"
}
}
}
}
BOMBVAULT_MCP_KEY は、Claude Code を起動する場所に設定します。たとえば ~/.claude/settings.json の "env" の下や、シェルのプロファイルです。プロンプトに入力するのではなく、テキストエディターで編集してください。この場合の参照は安全です。Claude Code は、それを引き継ぐ 2 つ目のプロセスを起動しないからです。BombVault 自身の証明書はこの方法では使えません。Claude Code 自身の接続は、NODE_EXTRA_CA_CERTS を設定しても、それを拒否します。キーを書き込んだ .mcp.json は、決してコミットしないでください。
Claude Desktop¶
Claude Desktop は mcp-remote を通じて BombVault に接続します。そのコンピューターに Node.js が必要です。まず、Claude Code と同じように、キーを専用のテキストファイルに、1 行で保存します。設定ファイルは、Claude Desktop の Settings, Developer, Edit Config から開きます。Windows では %APPDATA%\Claude\claude_desktop_config.json、macOS では ~/Library/Application Support/Claude/claude_desktop_config.json にあります。カードにある項目を、すでにあるサーバーの隣、"mcpServers" の中に追加して、Claude Desktop を再起動します。
{
"mcpServers": {
"bombvault": {
"command": "npx",
"args": ["-y", "mcp-remote@latest", "https://192.168.1.10:3443/mcp", "--header-file", "<path of the file with your key>"],
"env": {
"NODE_EXTRA_CA_CERTS": "<path of the downloaded bombvault-cert.pem>"
}
}
}
}
NODE_EXTRA_CA_CERTSは、BombVault 自身の証明書の場合にだけ必要です。コンピューターがすでに信頼する証明書の背後なら、省きます。--allow-httpは、通常のhttp://アドレスの場合にだけ追加されます。- Windows では、パスをスラッシュで書いてください。たとえば
C:/Users/sam/bombvault-key.txtです。バックスラッシュ 1 つは JSON として無効だからです。キーファイルのパスには空白を含めないでください。Windows の Claude Desktop は、空白を含むパスを 2 つに分けてnpxに渡します。 - 設定に書かれるのはキーファイルの名前だけなので、キーは設定にもプロセス一覧にも現れません。ファイルは自分だけが読める場所に置いてください。
クラウドのクライアント¶
ChatGPT、claude.ai の Claude、Grok、Le Chat は、ベンダーのサーバーから BombVault を呼び出すため、BombVault は、公的に信頼された証明書でインターネットから到達できる必要があります。たとえばリバースプロキシの背後です。Le Chat は自己署名証明書を拒否します。プロキシのログインで Web 画面を守ることはできますが、/mcp はそれなしで BombVault まで通す必要があります。これらのサービスはプロキシにサインインできず、BombVault が自分でキーまたはトークンを確認するからです。Grok と Le Chat は固定のキーを送り、そのボタンはほかと同じように設定を行います。ChatGPT と、ほとんどの組織での claude.ai の Claude は、次に説明する OAuth によるサインインでしか接続できません。
OAuth によるサインイン¶
キーを受け取れないクライアントのために、BombVault はそれ自身が OAuth の認可サーバーになります。クライアントは自分を登録し、あなたを BombVault のページに送ります。そこでログインパスワード(と、設定していれば第二要素)でサインインして許可します。クライアントはそのあと、この BombVault の MCP エンドポイントだけに使えるトークンを受け取り、自動で更新します。
- 設定、セキュリティ でログインパスワードを設定します。パスワードがないと、同意を尋ねる相手がいないので、BombVault はサインインを一切提供しません。
- BombVault を、ブラウザーが信頼する証明書で、https でインターネットから到達できるようにします。通常はリバースプロキシ経由です。クライアントは自分のサーバーから
/mcp、/oauth/、/.well-known/を呼び出すので、独自のログインを持つプロキシは、この 3 つのパスを BombVault まで通す必要があります。/oauth/authorizeの同意ページは、自分のブラウザーで開くので、プロキシのログインの背後に置いたままで構いません。プロキシはTRUSTED_PROXYにも指定してください(設定を参照)。BombVault はクライアントの登録をアドレスごとに制限しますが、指定がないと、すべてのクライアントがプロキシから来たように見えてしまいます。 - MCP カードで OAuth によるサインインをオンにして、公開アドレスを入力します。パスを含まない https アドレスで、たとえば
https://backup.example.comです。すべてのトークンがこのアドレスに結びつくので、変更後は各クライアントがもう一度サインインする必要があります。 - クライアントを選択で ChatGPT か Claude を選びます。ウィンドウには、公開アドレスに
/mcpを加えたコネクター URLと、そのクライアントのどこに入れるかが表示されます。ChatGPT では、Settings, Apps & Connectors, Advanced settings で Developer mode をオンにして、Create を選び、コネクター URL を MCP サーバー URL として貼り付け、認証に OAuth を選びます。claude.ai では、Settings, Connectors, Add custom connector を開き、コネクター URL を貼り付け、OAuth のクライアント ID とシークレットは空のままにして、Connect を選びます。 - クライアントが同意ページを開きます。誰が求めているか、あなたの応答がどこに戻されるか、そして最初はオフのバックアップの開始を許可スイッチが表示されます。許可か拒否を選びます。
サインインしたクライアントごとに、同じ一覧にそのマーク付きの専用の行ができます。その詳細にはログ、取り消す、バックアップの開始を許可があり、キーと同じ制限が適用されます。取り消すとすぐに有効になります。同じクライアントがもう一度サインインすると、新しい許可が古いものを置き換え、30 日間誰も使わなかった許可は失効します。同時にサインインできるクライアントは最大 10 個で、10 個のキーとは別です。
同意ページは、登録済みのクライアントが、登録した戻り先アドレスの 1 つをそのまま指定したリクエストだけを受け付けます。https か、自分のコンピューターのクライアント向けのループバックアドレス(任意のポート)です。受け付けるのは PKCE(S256)つきの認可コードフローだけで、あなたの応答はセッションに結びついているので、ほかの Web サイトがあなたの代わりに送ることはできません。アクセストークンは 1 時間有効です。リフレッシュトークンは使うたびに置き換えられ、その後に再び現れたものは、誰かがコピーを持っているということなので、許可を取り消します。応答が届かなかったために 30 秒以内に最後のリフレッシュを繰り返すクライアントには、代わりに新しいトークンが渡されます。BombVault はインターネットからクライアントのメタデータ文書を取得しないので、クライアントは動的クライアント登録で登録します。
そのほかのクライアント¶
Streamable HTTP を話せるクライアントなら、どれでも動きます。
- URL:Web 画面のアドレスに
/mcpを加えたもの。たとえばhttps://192.168.1.10:3443/mcp。 - キーは
Authorization: Bearer <key>かX-API-Key: <key>に入れます。両方を送る場合は、同じキーでなければなりません。 Content-Type: application/jsonとAccept: application/json, text/event-streamのPOST。- リクエストごとに 1 つの JSON-RPC メッセージ。バッチは拒否されます。
- プロトコルバージョン 2026-07-28、2025-11-25、2025-06-18、2025-03-26。
TLS と証明書¶
BombVault は、自分で作った証明書で HTTPS を提供します。その証明書は、最初は localhost、127.0.0.1、::1 の名前しか持ちません。Claude Code と mcp-remote は、LAN のアドレスではそれを拒否します。回避する方法を、ほとんどの Unraid 環境に合う順に挙げます。
- MCP カードでアドレスを追加する。 カードが、証明書に含まれていないアドレスで HTTPS 経由で開かれたとき、そう表示してこのアドレスを証明書に追加を提案します。BombVault は、そのアドレスを加えて証明書を発行し直します(ブラウザーは、最初のときと同じように、もう一度警告します)。そのあと証明書をダウンロードをクリックします。スニペットは
NODE_EXTRA_CA_CERTSをダウンロードしたファイルに設定するので、クライアントは、まさにこの証明書を信頼します。つまり、以前のダウンロードでセットアップしたクライアントはすべて、証明書が再発行された時点で、このコンピューターでもほかのコンピューターでも、新しいファイルを入手するまで接続できなくなります。 - 信頼された証明書を持つリバースプロキシ(Nginx Proxy Manager、SWAG、Caddy、Traefik)。クライアントにはプロキシの証明書が見えるので、追加のことは必要なく、カードも BombVault 自身の証明書について警告しません。
- Tailscale。 コンテナの前に
tailscale serveを置くか、Unraid の Tailscale 連携を使うと、信頼された証明書を持つts.netの名前が得られます。 HTTP_ONLY=true。TLS を終端するプロキシの背後か、完全に信頼できるネットワークでのみ使います。Web 画面全体を通常の HTTP に切り替え、コンテナ設定の変更が必要で、キーが暗号化されずに送られます。
NODE_TLS_REJECT_UNAUTHORIZED=0 は、決して設定しないでください。その Node.js プロセスが通信するすべてのものに対して、証明書の確認がオフになります。
リバースプロキシは Authorization(または X-API-Key)ヘッダーを通す必要があります。指示しない限りプロキシはそうします。また /mcp をバッファリングしたり書き換えたりしてはいけません。BombVault の証明書も検証する、Nginx または Nginx Proxy Manager 向けの location ブロックは次のとおりです。
location /mcp {
proxy_pass https://192.168.1.10:3443;
proxy_ssl_verify on;
proxy_ssl_trusted_certificate /data/bombvault-cert.pem;
proxy_ssl_name localhost;
proxy_http_version 1.1;
proxy_buffering off;
proxy_set_header Host $host;
}
プロキシの背後では、すべてのリクエストにプロキシのアドレスが付きます。誤って設定された 1 つのクライアントが間違ったキーを 5 回送ると、そのプロキシの背後のすべての MCP クライアントが 1 分間締め出されます。クライアントごとに数えるには、プロキシを TRUSTED_PROXY に指定してください(設定を参照)。
セキュリティモデル¶
- 有効なキーがなく、OAuth によるサインインがオフのとき、
/mcpは404で応答します。 - OAuth によるサインインは、ログインパスワードが設定されているあいだだけ提供されます。トークン、コード、クライアントシークレットはフィンガープリントだけが保存され、トークンは発行されたアドレスでしか使えません。
- クライアントは、1 つのアドレスから 1 時間に最大 10 回登録できます。誰もサインインしていない登録済みクライアントは、BombVault が最大 100 個を、それぞれ 1 日間保持します。間違ったコードとリフレッシュトークンは、間違ったキーと同じロックアウトに数えられます。
- 許可は、設定バックアップの復元や
APP_KEYの変更のときに、キーと同じように動作します。復元のあとは、すべてのクライアントがもう一度サインインする必要があります。 - 例外のアドレスはありません。
localhost、Unraid ホスト、リバースプロキシ、tailscale serveからのリクエストも、ほかと同じようにキーが必要で、Web 画面にログインパスワードがない場合も同じです。 - キーはフィンガープリントだけが保存され、一度だけ表示され、名前の変更、交換、取り消しができます。有効なキーは最大 10 個で、それぞれに独自のバックアップの開始を許可スイッチがあります。
- キーの作成、交換、権限の変更、取り消しは、そのたびに、通知がオフでない限り、どのアドレスから行われたかとともに、通知チャンネルに通知を送ります。
- 同じアドレスから 1 分間に 5 回間違ったキーを送ると
429になります。キーごとに 1 分間に 120 リクエストと 1 時間に 12 回のバックアップ開始までで、さらに上のクールダウンと保持ガードがあります。 - 別のオリジンのブラウザーページからのリクエストは拒否されます。
- ログインパスワードが設定されていないあいだ、公開されているように見えるホスト名からはキーを作成できません。
- アシスタントが開始したすべてのバックアップと、それによって起きるプルーンやオフサイトの実行は、アクティビティログ、エラーパネル、バックアップ通知に、キーの名前とともに「via MCP」と印が付きます。
- ツールの呼び出しはすべて、キーの ID と末尾 4 文字(名前は決して含まれません)とともにコンテナのログに書かれ、
/metrics(bombvault_mcp_requests_total、bombvault_mcp_tool_calls_total、bombvault_mcp_active_keys)で数えられます。 - 設定バックアップを復元すると、すべてのキーが取り消されます。復元されるデータベースに、保存後に取り消したキーが含まれているかもしれないからです。そのあとで新しいキーを作成してください。
APP_KEYが変わる(再インストール、または別のコンテナへの復元)と、キーは使えなくなります。カードがそれを検出してキーに印を付け、キーを交換で、再び使えるシークレットを与えます。- キーはパスワードのように扱ってください。キーを環境変数、プロンプト、キーファイルから読み取れないクライアントは、キーを設定または設定ファイルに平文で保持し、セットアップにもそう書かれます。あまり信頼できないコンピューターでは、読み取り専用のキーを選んでください。
外に出るもの¶
アシスタントが読み取ったものは、すべてその背後の AI プロバイダーに送られます。ファイル検索では、見つかったファイルの名前、サイズ、バックアップ内のパスも送られます。項目名、スケジュール、エラーメッセージつきの実行履歴、リストアポイントの ID と時刻、データベースエンジンの名前とダンプのサイズ、現在のアクティビティ、ストレージの数値、カバレッジ、状態です。BombVault は、何かが外に出る前に、ホストのパス、リポジトリの場所、ホスト名、認証情報、フックのコマンド、キーを取り除きます。
トラブルシューティング¶
| 見えるもの | 意味 |
|---|---|
404 |
有効なキーがなく OAuth によるサインインがオフ、または /api/mcp のような誤ったパスです。エンドポイントは /mcp です。 |
401 |
キーがない、入力ミス、取り消された、または交換された。プロキシが Authorization ヘッダーを落としているかもしれません(X-API-Key を試してください)。カードがキーをもう有効でないと印を付けている場合は、APP_KEY が変わっています。キーを交換してください。 |
403 |
リクエストが別のオリジンのブラウザーページから来ました。デスクトップまたはコマンドラインのクライアントを使ってください。 |
GET での 405 |
正常です。エンドポイントは POST しか受け付けません。 |
400 "Accept must contain both 'application/json' and 'text/event-stream'" |
クライアントが Streamable HTTP には古すぎます。更新してください。 |
400 "batch requests are not accepted" |
クライアントが JSON-RPC のバッチを送っています。リクエストごとに 1 つのメッセージを送ってください。 |
429 |
このアドレスから間違ったキーが多すぎるか、1 つのキーで 1 分間に 120 リクエストを超えました。1 分待って、アシスタントがループにはまっていないか確認してください。 |
| 「certificate」、「self-signed」、「unable to verify」のエラー | クライアントが BombVault の証明書を信頼していません。TLS と証明書を参照してください。 |
busy |
別のバックアップまたはメンテナンスジョブがそのドメインを保持しています。終わってからもう一度試してください。 |
cooldown |
この項目、ドメイン、または「すべてバックアップ」が、15 分未満前に Web 画面の外から開始されました。 |
retention_guard |
MCP によるバックアップをもう 1 つ増やすと、「直近 N 件を保持」の枠に MCP が作ったリストアポイントしか残らなくなる、またはその項目が過去 24 時間にすでに MCP で 4 回(失敗と中止も含む)バックアップされています。前者は次のスケジュールされたバックアップが空きを作り、後者は最も古いバックアップから 24 時間後にまた使えるようになります。どちらの場合も、Web 画面からなら開始できます。 |
rate_limited |
キーがこの 1 時間の 12 回の開始を使い切りました。 |
開始での not_permitted |
キーが読み取り専用です。カードでバックアップの開始を許可をオンにしてください。再接続は不要です。中止の場合は、その実行がこのキーで開始されたものではないという意味です。 |
domain_off |
そのセクションが 設定、一般 でオフになっています。 |
not_found |
その項目は BombVault に保護されていません。先に Web 画面で追加してください。MCP が設定を作ることはありません。 |
| クライアントが認可サーバーを見つけられない | OAuth によるサインインがオフ、ログインパスワードが未設定、またはプロキシが /.well-known/ を BombVault まで通していません。 |
| 同意ページが、戻り先アドレスが登録されていないと言う | クライアントが、登録していない戻り先アドレスを送りました。クライアントでコネクターを削除して、もう一度追加してください。 |
サインイン済みのクライアントで 401 |
許可が取り消された、30 日間使われずに失効した、または公開アドレスが変わりました。クライアントがもう一度サインインします。 |
コンテナに環境変数 MCPGODEBUG を設定しないでください。MCP ライブラリの動作が変わり、不正な値だと、BombVault がログを 1 行も書く前に起動時に停止します。