NVSentinel Lab

nvidia-nvsentinel-mcp

Go で書かれた、ラボクラスター上で NVIDIA NVSentinel （Kubernetes 上の GPU 障害検出と修復）をテストする MCP サーバーです。NVSentinel 自体も Go で書かれています。Claude Code などの MCP クライアントは、NVSentinel の報告内容を読み取り、シミュレートされた GPU に障害を注入し、NVSentinel がノードを cordon してドレインすることを確認できます。

このリポジトリには、サーバーとテスト結果のサンプルが含まれています。NVSentinel はインストールしません。インストールするのは omerfsen.aicr で、クラスターは omerfsen.nvke または kind を使用します。将来的には上流へ貢献することを目指しています。docs/upstream.md を参照してください。

テスト結果

このサーバーを介して MCP 経由で取得した、kind 上の NVSentinel v1.30.0 の実際の出力です： docs/test-results。これらは、実際の GPU の状態ではなく、シミュレートされた DCGM に対する NVSentinel のパイプラインを検証するものです。

標準規格

このサーバーは次の標準規格に準拠しています。各要件、そのステータス、要件を証明するテスト、既知のギャップについては、最新版を確認するためのリンクとともに docs/mcp-standards.md に記載しています。

標準規格	バージョン
Model Context Protocol	2026-07-28、および 2024-11-05 までの各バージョン
MCP Registry server.json	2025-12-11、有効かつ公開済み（0.5.1）
AGENTS.md	AGENTS.md、CLAUDE.md から読み込み
Agent Skills	skills/nvsentinel-lab

公式の 適合性テストスイート では実行していません。このスイートは HTTP サーバーのみをテストします。MCP にはドキュメントの記述に関する標準がないため、一般的な慣例に従い、docs/tools.md はサーバーから生成しています。

ツール

ツール	ラボを変更するか	内容
lab_status	いいえ	ノード（cordon の状態、NVSentinel の状態、失敗している GPU チェック）、Pod、ワークロード
list_scenarios	いいえ	シナリオ、ステージ、許可されている XID、ログソース
wait_for_stage	いいえ	cordoned など、指定したステージになるまでポーリング
component_logs	いいえ	NVSentinel コンポーネントのログの末尾の行
node_events	いいえ	GPU ノード上の最近のイベント
inject_fault	はい	シミュレートされた GPU に XID 95 を注入
clear_fault	はい	障害を解除するため、シミュレートされた hostengine を再起動
reset_lab	はい	DCGM の停止と注入した障害を元に戻す
run_test_scenario	はい	シナリオを最初から最後まで実行し、各ステップを報告

シナリオ	確認内容
xid95	XID 95 を注入：検出、cordon、ワークロードの退避、ドレイン成功。障害を解除：正常化、cordon 解除、ワークロード復帰
dcgm_outage	hostengine を停止：モニターが DCGM との接続喪失を報告。復旧：状態がクリア

変更を伴うツールは、NVSENTINEL_MCP_ALLOW_CHANGES=true が設定されていない限り無効です。設定されている場合も、kind クラスターでのみ動作します。詳細は docs/security.md を参照してください。

各ツールの入力、出力、アノテーションについては docs/tools.md を参照してください。これは tools/list に対してサーバーが返す内容から生成されます。同様に、生データは docs/tools.json にあります。サーバーとの不一致があるとテストは失敗します。make docs で再生成できます。

インストール

サーバーには kubeconfig が必要です。kind のラボでは、make lab-token を実行すると kubeconfig が作成されます（kind でテストを実行するを参照）。MCP は stdio 経由で通信するため、どの MCP クライアントからでも起動できます。以下のコマンドでは変更は行われません。ラボに変更を加えるクライアントでのみ、-e NVSENTINEL_MCP_ALLOW_CHANGES=true を追加してください。

1. サーバーをインストールします。 使用するプラットフォーム向けのバイナリを最新リリースからダウンロードします。

プラットフォーム	ファイル
Linux、x86-64	nvidia-nvsentinel-mcp-linux-amd64
Linux、Arm	nvidia-nvsentinel-mcp-linux-arm64
macOS、Intel	nvidia-nvsentinel-mcp-darwin-amd64
macOS、Apple シリコン	nvidia-nvsentinel-mcp-darwin-arm64
Windows、x86-64	nvidia-nvsentinel-mcp-windows-amd64.exe
Windows、Arm	nvidia-nvsentinel-mcp-windows-arm64.exe

Linux と macOS では、FILE にダウンロードしたファイルを設定します。

FILE=nvidia-nvsentinel-mcp-linux-amd64
BASE=https://github.com/omerfsen/nvidia-nvsentinel-mcp/releases/latest/download
curl -fsSLO "$BASE/$FILE"
curl -fsSL "$BASE/checksums.txt" | grep " $FILE\$" | sha256sum -c -   # macOS: shasum -a 256 -c -
gh attestation verify "$FILE" --repo omerfsen/nvidia-nvsentinel-mcp    # optional: who built it
install -m 755 "$FILE" ~/.local/bin/nvidia-nvsentinel-mcp

Windows では、PowerShell で kubeconfig を自分だけが読み取れる場所に保管してください。サーバーはその場所を確認できません。

$File = "nvidia-nvsentinel-mcp-windows-amd64.exe"
$Base = "https://github.com/omerfsen/nvidia-nvsentinel-mcp/releases/latest/download"
Invoke-WebRequest "$Base/$File" -OutFile "$HOME\bin\nvidia-nvsentinel-mcp.exe"

各リリースには checksums.txt と SBOM（nvidia-nvsentinel-mcp.sbom.cdx.json）も含まれます。動作確認済みなのは Linux の x86-64 のみで、その他のプラットフォーム向けはビルド済みですが、テストされていません。または、Go 1.27 でインストールできます。 go install github.com/omerfsen/nvidia-nvsentinel-mcp@latest または、root として実行されず、サイズが約 32 MB のイメージ docker.io/omerfsen/nvidia-nvsentinel-mcp を使用してください。

nvidia-nvsentinel-mcp --version で確認してください。フラグを指定せずに実行すると、stderr に 1 行ログを出力したあと、stdin で MCP クライアントからの入力を待つため、何もしていないように見えますが、これは正常です。Ctrl-C で停止します。--help でフラグを確認できます。また、--debug を指定すると、各ツール呼び出しとクラスターの詳細が stderr に記録されます。

2. クライアントに追加します。 バイナリが PATH 上にある場合、Claude Code では次のようにします。

claude mcp add nvsentinel-lab -- nvidia-nvsentinel-mcp

または、~/.local/bin/nvidia-nvsentinel-mcp のように、バイナリのフルパスを指定します。

イメージを使用する場合：

claude mcp add nvsentinel-lab -- docker run --rm -i --read-only --cap-drop=ALL \
  --security-opt=no-new-privileges --user "$(id -u):$(id -g)" --memory=128m --cpus=1 \
  --pids-limit=64 --network=kind \
  --volume "$HOME/.kube/nvsentinel-lab-mcp-docker.yaml:/kube/config:ro" \
  docker.io/omerfsen/nvidia-nvsentinel-mcp@sha256:cb6fba848870580f77d347d476a2a7003cd336cd6f4807a72928013538d7aed9

その他のクライアントでも、MCP 設定で同じコマンドを指定します。クライアントから参照できる PATH 上にバイナリがない場合は、フルパスを使用してください。

{ "mcpServers": { "nvsentinel-lab": { "command": "nvidia-nvsentinel-mcp" } } }

3. 任意：スキルを追加します。 スキルを追加すると、エージェントがツールの使い方を学習できます。スキルに含まれるのは手順のみなので、手順 1 と 2 も必要です。どちらのコマンドでも実行できます。

gh skill install omerfsen/nvidia-nvsentinel-mcp nvsentinel-lab
npx skills add omerfsen/nvidia-nvsentinel-mcp --skill nvsentinel-lab

GitHub CLI の v2.103.2 には gh mcp add がありません。スキルのインストールには gh skill を使用し、MCP サーバーはクライアントから追加します。このサーバーは、公式 MCP Registry に io.github.omerfsen/nvidia-nvsentinel-mcp として掲載されています。

kind でテストを実行する

Go、Docker、kubectl、helm、yq、約 10 GiB の空きメモリ、および make dev を実行済みの omerfsen/aicr のチェックアウトが必要です（https://github.com/omerfsen/aicr/pull/8 がマージされるまでは、dev/osen/nvsentinel-latest ブランチを使用してください）。

make lab-up           # the kind cluster, with its own kubeconfig
make lab-install      # NVSentinel v1.30.0 through omerfsen.aicr (AICR_DIR=<checkout>)
make lab-fixture      # simulated DCGM, a labelled node, a workload, the server's RBAC
make lab-token        # a kubeconfig for the server: its own identity, valid 8 hours
make e2e              # the tests, through the real binary over MCP; writes docs/test-results
make image e2e-image  # the same, with the server in its container
make lab-down

クラスターを使わないテストは、make lint test で実行できます。

Claude Code から使用する

サーバー自体の開発作業をする場合は、チェックアウトしたディレクトリで make build lab-token を実行し、その後このディレクトリで Claude Code を再起動して、.mcp.json からサーバーを承認します。この設定では変更が許可されます。

設定

変数	デフォルト	説明
NVSENTINEL_MCP_KUBECONFIG	~/.kube/nvsentinel-lab-mcp.yaml（イメージの場合：/kube/config）	使用する kubeconfig。非公開である必要があります（chmod 600）
NVSENTINEL_MCP_ALLOW_CHANGES	オフ	true を指定すると、ラボ内でのみ変更ツールが有効になります
NVSENTINEL_MCP_LAB_CONTEXT	kind-nvsentinel-lab	変更ツールで使用するコンテキスト。kind- で始まる必要があります

テストしていないこと

• Linux の x86-64 以外のバイナリです。クロスコンパイルされており、実行していません。
• 実機の GPU です。RTX 4080 SUPER は NVSentinel の検証済みリストに含まれておらず、実際の DCGM ヘルスもまだ確認する必要があります。
• kind ではなく、NVKE 上での AICR のインストールです。
• 修復です。kind へのインストールでは cordon と drain までで停止します。AICR の修復ミックスインには metadata-collector が必要で、metadata-collector には NVML が必要です。
• syslog モニターです。カーネルトランスポートのジャーナルエントリーを読み取りますが、kind ノードでは安全に生成できないため、kind では無効にしています。
• イメージの cosign 署名と SBOM アテステーションを手動で検証することです。これらは添付済みで、ビルドの来歴のみを検証しました（gh attestation verify）。

すべての手順、失敗、行き詰まりについては、docs/build-log.md をご覧ください。

ライセンス

Apache-2.0。lab/gpu-spec.yaml と lab/fake-dcgm.yaml は NVSentinel に由来し、同じライセンスの下で提供されています。