Claude Codeでwandb MCPサーバーを使い実験結果を読む手順

Weights & Biases(W&B)は、機械学習の実験管理とLLMアプリのトレース(Weave)を扱うサービスです。W&Bが公開しているMCP(Model Context Protocol)サーバーを使うと、Claude Codeの会話から実験のRunやトレースを問い合わせられます。ダッシュボードを開かずに「評価精度の上位5件」や「最近の失敗トレースの傾向」を聞ける形です。

登録は claude mcp add の1行で済みます。この記事では、その1行の中身、使えるツールの分類、読み取り専用で運用する方法、質問の書き方を順に扱います。

W&B MCPサーバーでできること

W&B MCPサーバーは、W&Bのデータを自然言語で問い合わせるためのサーバーです。READMEの用途は4つに分かれています。

ほかのMCPサーバーを同じ流れで繋いだ例は、GA4のMCPサーバーやAuth0のMCPサーバーの記事にあります。

登録する前に用意するもの

必要なのはW&Bのアカウントと、APIキーの2つです。READMEは、APIキーを wandb.ai/authorize のページから取得するよう案内しています。

接続先は2通りです。

READMEはホスト版を推奨しています。理由として、インストールが不要なこと、リリースの更新をW&Bが管理すること、同時利用を守る負荷制限が組み込まれていることを挙げています。過負荷のときは再試行可能な応答が返る設計なので、混雑時の失敗は一度やり直す価値があります。W&B DedicatedやSelf-Managedの環境では、運用者がチャートで有効にしていれば https://<your-instance>/mcp が接続先になります。

ホスト版をClaude Codeに登録する

READMEのClaude Code向け手順は、次の1コマンドです。

claude mcp add --transport http wandb \
  https://mcp.withwandb.com/mcp --scope user \
  --header "Authorization: Bearer <your-api-key-here>"

Claude Codeの側から見ると、これはBearerトークン付きのHTTPサーバーを足すコマンドです。--transport http でリモートサーバーを指定し、--header で認証ヘッダーを付けています。短縮形の -t と -H も使えます。

スコープはAPIキーの置き場所で決める

--scope は設定の保存先を決めます。

READMEの例は --scope user なので、キーは ~/.claude.json に入り、どのプロジェクトからもW&Bを呼べます。特定の研究リポジトリだけで使うなら、--scope を外して既定のlocalにする選択肢もあります。

チームで同じ設定を共有したいときは --scope project を使います。キーをそのまま .mcp.json に書いてコミットすると、キーがリポジトリに残ります。.mcp.json ではヘッダー値に環境変数を展開できるので、キーは環境変数に逃がします。

{
  "mcpServers": {
    "wandb": {
      "type": "http",
      "url": "https://mcp.withwandb.com/mcp",
      "headers": {
        "Authorization": "Bearer ${WANDB_API_KEY}"
      }
    }
  }
}

${VAR} が未設定で既定値もない場合、設定は読み込まれますが、展開されない ${VAR} の文字列がそのまま使われます。claude mcp list に警告が出るので、登録後に一度確認すると気づけます。

接続を確かめる

登録したら、一覧で状態を見ます。

claude mcp list

✔ Connected が出れば接続できています。✘ Failed to connect の場合は、失敗の詳細がHTTPステータスやサーバーのエラー文付きで同じ行に出ます。キーを貼ったときに前後へ空白や改行が混ざると、Claude Codeが headers.Authorization の名前を挙げて警告します。値は自動では削られないので、設定を直して貼り直します。

セッション内では /mcp でも同じ状態を見られます。接続が切れたサーバーをまとめて繋ぎ直すには、/mcp reconnect allが使えます。

使えるツールを知っておく

接続すると、W&B側のツールがClaude Codeに渡ります。READMEの表をもとに、用途で分けると次のとおりです。

表のほかに、エージェントの実行データ(OpenTelemetryのスパン)を読むツール群や、W&Bのホスト型エージェントに作業を任せるARIAのツール群もあります。これらは通常のプロファイルには含まれず、明示的に選ぶものです。まずは上の表の範囲で十分です。

読み取り専用で運用する

実験データを読ませたいだけなら、書き込み系のツールは外しておけます。READMEには、WANDB_MCP_ACCESS_MODE=read-only を設定すると、書き込みに分類されたツールがすべて除かれると書かれています。対象には create_wandb_report_tool と log_analysis_to_wandb が含まれます。query_wandb_tool は、どのモードでも読み取り専用です。

この環境変数を使うのは、サーバーを手元で起動するローカル方式です。ローカル方式の登録は、次の形になります(vX.Y.Z はREADMEの指示どおり、リリース一覧にある署名済みの版に置き換えます)。

claude mcp add wandb \
  --env WANDB_API_KEY=<your-api-key> \
  --env WANDB_MCP_ACCESS_MODE=read-only \
  -- uvx --from git+https://github.com/wandb/wandb-mcp-server@vX.Y.Z \
  wandb_mcp_server

-- より後ろが、サーバーを起動するコマンドです。uv が未導入なら、先に入れておきます。自前のW&Bインスタンスに繋ぐときは、env に WANDB_BASE_URL も足します。

ホスト版には WANDB_MCP_ACCESS_MODE を渡す場所がありません。書き込み系ツールを止めたいときは、Claude Codeの permissions の deny に mcp__wandb__create_wandb_report_tool と mcp__wandb__log_analysis_to_wandb を入れます。MCPのルールは mcp__<サーバー名>__<ツール名> の形で、サーバー名は claude mcp add で付けた名前です。deny は呼び出しそのものを拒否し、毎回確認に回す ask とは動きが違います。

ローカル版で調整できる環境変数

ローカル方式では、サーバーの挙動をいくつかの環境変数で切り替えられます。READMEの一覧から、Claude Codeで使う場面に関わるものを抜き出します。

ドキュメント検索は、W&Bのドキュメント用MCPサーバーを別に繋いでいる場合に切るためのスイッチです。同じ検索が二重に出るのを避けられます。

テレメトリについて、READMEは「生のツール引数はログに記録しない」と書いています。ただし MCP_LOG_PRIVACY_LEVEL の既定は off で、認証済みのW&Bユーザー名が利用状況イベントに含まれることがあります。共有環境や、ユーザー名を外へ出したくない運用では、strict(SHA-256の仮名化)を選ぶか、MCP_ANALYTICS_DISABLED で無効にします。ホスト版を使うなら、この調整はW&B側の運用に委ねる形になります。

質問の書き方

READMEの使い方のヒントは3点です。ここでは、Claude Codeへの指示に落とした形で示します。

• エンティティ(チームまたはユーザー)名とプロジェクト名を、最初に必ず書く
• 「いちばん良い評価は?」のような広い問いは避け、「f1が最高の評価はどれか」まで絞る
• 広い問いに答えさせるときは、結果が全体かどうかを必ず確かめる

例えば、次のような依頼になります。

my-team/image-clf プロジェクトで、eval/accuracy が高い上位5件のRunを出して。
各Runの learning_rate と batch_size も並べて。

トレースの調査なら、READMEが勧める順序に沿います。先に infer_trace_schema_tool でフィールドを調べ、そのあと query_weave_traces_tool で列を絞って読む流れです。

my-team/support-agent の最新100件のトレースを見て、失敗の多い原因を説明して。
まずスキーマを調べてから、必要な列だけ取得して。

query_weave_traces_tool の detail_level には3段階があります。

最初は既定の summary で眺め、気になるトレースだけ full で掘る使い方が、トークンを無駄にしません。

結果が全体かどうかを確かめる

READMEによると、コレクションや評価を返すツールは total_count / returned_count / has_more / project_exhaustive / sampled / truncated といった項目で、返した範囲を報告します。広い問いでは、これらの意味をClaudeに説明させてから結論を読みます。上位100件だけを見た結果を、プロジェクト全体の結論と取り違えないための確認です。

学習曲線も同じで、get_run_history_tool の samples は全キー合計の行数の上限であり、キーごとの上限ではありません。損失と検証損失を同時に出させると、1キー当たりの点が思ったより少ないことがあります。

つまずきやすい点

ローカル方式で環境変数を渡すとき、stdioのMCPサーバーへ何が引き継がれるかはCLAUDE_CODE_MCP_ALLOWLIST_ENVの記事で扱っています。

まとめ

W&B MCPサーバーを入れると、Claude Codeが実験管理の画面の代わりに、Runの抽出や比較、Weaveトレースの失敗調査を担当します。使い始めは、ホスト版を claude mcp add で登録し、claude mcp list で接続を確かめ、プロジェクト名を添えた具体的な問いから始めるのが安全です。

書き込みを許したくない運用では、ローカル版なら WANDB_MCP_ACCESS_MODE=read-only、ホスト版なら書き込み系ツールへの deny ルールで止めます。結果の件数や切り詰めの有無を確かめる習慣があれば、上位100件だけを全体と読み違える事故は防げます。