ClaudeにMLflow MCPを繋いでトレース調査と評価ループを回す

自作のエージェントが時々おかしな答えを返すとき、原因はたいていログの奥にあります。MLflowのトレースにはその奥の1ステップごとの入出力が残っており、Claude Codeから読めるようにすると「失敗したトレースを探す、評価する、直す、直ったか確かめる」を1つの会話で回せます。

接続の方法は2つあります。トレースを読み書きするMLflow MCPサーバーと、改善ループ全体を担うMLflowプラグインです。この記事では両方の入れ方と、ループの各段階でどちらを使うかを順に説明します。

MLflow MCPサーバーとプラグインは何が違うのか

MLflow MCPサーバーは、MLflowのトレース管理操作をMCP経由で公開する仕組みです。検索、取得、フィードバックの記録、タグ付け、削除ができます。ドキュメントには実験的機能と明記されており、今後のリリースで変わる可能性があります。

一方のMLflowプラグインは、Claude Codeのマーケットプレイスに載っている別物です。紹介ページによると、計装(トレースの組み込み)から評価、修正までの改善ループを11個のスキルで受け持ち、依頼内容に応じて専門のスキルへ振り分けるディスパッチャーを備えています。

注意したいのは要件の差です。MCPサーバーだけなら3.5.1で動きますが、プラグインは3.8以上を求めます。手元のMLflowが3.5〜3.7なら、まずMCPサーバーだけを入れるか、MLflow本体を上げてからプラグインを入れる順になります。

どちらか一方でなく両方を入れる使い方もできます。プラグインがスキルとして手順を持ち、MCPサーバーが生のトレースを引くツールになる、という分担です。ただし両者がどう連携するかは、紹介ページにもMCPのドキュメントにも書かれていません。この記事では「併用できる別々の部品」として扱います。

MLflow MCPサーバーをClaude Codeに接続する

前提は、MLflow 3.5.1以上と、トラッキングサーバー(またはDatabricks)のURLです。MCP機能はmcp付きのextraとして入ります。

pip install 'mlflow[mcp]>=3.5.1'

Claude Codeへの登録は、claude mcp add を使う方法が推奨されています。-- より前がClaude Code側のオプション、後ろがMCPサーバーの起動コマンドです。

claude mcp add mlflow-mcp \
  -e MLFLOW_TRACKING_URI=http://localhost:5000 \
  -- uv run --with "mlflow[mcp]>=3.5.1" mlflow mcp run

チームで共有するなら、プロジェクトルートの .mcp.json に同じ内容を書いてバージョン管理に入れます。

{
  "mcpServers": {
    "mlflow-mcp": {
      "command": "uv",
      "args": ["run", "--with", "mlflow[mcp]>=3.5.1", "mlflow", "mcp", "run"],
      "env": {
        "MLFLOW_TRACKING_URI": "http://localhost:5000"
      }
    }
  }
}

MLFLOW_TRACKING_URI には接続先を入れます。ローカルなら http://localhost:5000、リモートならそのサーバーのURLです。Databricksの場合は値を databricks にして、DATABRICKS_HOST と DATABRICKS_TOKEN などの環境変数で認証を渡します。

.mcp.json に書いたサーバーは、初回に承認を求められます。承認を取り消したいときはclaude mcp reset-project-choicesの手順を使います。JSONをそのまま登録したい場合はclaude mcp add-jsonの記事が近道です。

公開するツール群を絞る

MCPサーバーは、MLFLOW_MCP_TOOLS 環境変数で公開するツールのカテゴリを選べます。ツールが多いとClaudeの文脈とトークンを食うため、絞る設定が用意されています。

traces,scorers,experiments のようにカンマ区切りで個別に選ぶこともできます。エージェントの改善ループだけが目的なら、既定の genai で足ります。従来の機械学習モデルの管理も同じ会話で扱いたいときだけ、all に広げます。

どのツールで何ができるか

トレース管理のツールは次の10個です。ドキュメントの一覧表にある名前とパラメータをそのまま挙げます。

genai カテゴリにはscorersやrunsも含まれますが、ドキュメントの一覧表にはそれらのツール名が載っていません。評価の実行そのものをMCPから呼べるかどうかは、表からは読み取れません。次の節で見るように、評価の実行はPythonの mlflow.genai.evaluate が受け持つ前提で組むのが無難です。

extract_fieldsで返すデータを絞る

search_traces と get_trace には extract_fields というパラメータがあり、ドット区切りのパスで必要なフィールドだけを返せます。トレース全体を取ると応答が大きくなり、Claudeの文脈を圧迫するため、これは実用上かなり効きます。

# 失敗トレースの概要だけ取る
search_traces(
    experiment_id="1",
    extract_fields="info.trace_id,info.state,data.spans.*.name",
)
 
# 評価とタグだけ取る
get_trace(
    trace_id="tr-abc123",
    extract_fields="info.assessments.*,info.tags.*",
)

* は配列やオブジェクトの全要素を指します。名前にドットを含むフィールドはバッククォートで囲みます。たとえばトレース名は info.tags.`mlflow.traceName` と書きます。よく使うパスには、info.execution_duration(総実行時間)、info.assessments.*.feedback.value(フィードバックの値)、data.spans.*.attributes.mlflow.spanType(AGENT・TOOL・LLMなどのスパン種別)があります。

CLAUDE.mdに次のような一節を置いておくと、Claudeが毎回フィールド指定を考えずに済みます。これは筆者側の運用案で、ドキュメントに書かれた設定ではありません。

## MLflowトレースの調べ方
- トレース調査は mlflow-mcp の search_traces から始める
- 一覧取得では必ず extract_fields を付け、info.trace_id,info.state,info.execution_duration に絞る
- 詳細は get_trace で1件ずつ。data.spans.*.name から読み、必要なスパンだけ掘る
- delete_traces は実行前にユーザーへ対象と件数を確認する

トレース→評価→改善→検証のループを回す

プラグインの紹介ページは、ループを「計装、トレース、評価、反復、検証」と説明しています。ここではその各段階に、MCP・プラグイン・Pythonのどれを当てるかを表にします。

失敗トレースを探す

MCPのドキュメントには、エージェントに頼む例が載っています。「実験1の直近1時間の失敗トレースを探して」と頼むと、search_traces に status='ERROR' と時刻の条件を渡す、という流れです。遅いトレースなら execution_time_ms > 5000 で絞り、order_by に execution_time_ms DESC を渡します。

会話では、実験IDと期間と件数の上限を最初に伝えると無駄がありません。

mlflow-mcpで実験1のエラー状態のトレースを直近1時間分、最大20件探して。
extract_fieldsで trace_id・state・execution_duration・request_preview だけ返して、
共通する失敗パターンがあれば挙げて。

これは入力例です。Claudeがどう応答するかは、トレースの内容と環境で変わります。

人の判断とLLM判定をトレースに残す

評価の記録先は、トレースに紐づく「フィードバック」です。MLflowのフィードバックには、真偽値、数値(1〜5の星評価や確信度など)、自由記述のテキストを使えます。ソースの種別は3つです。

MCPの log_feedback には trace_id、name、value、source_type、rationale を渡します。ドキュメントの例は「トレース tr-abc123 に、正確さを理由にした関連性スコア0.85を記録して」という依頼です。

人が確認した正解を残したいときは log_expectation を使います。フィードバックは「出力への評価」、expectationは「あるべき答え」という違いがあります。後者は、次の節の評価データセットの元になります。

データセットとスコアラーで一括評価する

評価の実行は、Pythonの mlflow.genai.evaluate が担います。評価は3つの部品でできています。データセット(入力と期待値)、スコアラー(評価基準)、予測関数(データセットに対する出力を作る関数)です。

import mlflow
from mlflow.genai.scorers import Correctness, Guidelines
 
dataset = [
    {
        "inputs": {"question": "Can MLflow manage prompts?"},
        "expectations": {"expected_response": "Yes!"},
    },
]
 
def predict_fn(question: str) -> str:
    ...  # 評価対象のエージェントを呼ぶ
 
results = mlflow.genai.evaluate(
    data=dataset,
    predict_fn=predict_fn,
    scorers=[
        Correctness(),
        Guidelines(name="is_english", guidelines="The answer must be in English"),
    ],
)

Correctness は組み込みのLLM判定スコアラー、Guidelines は自然文の基準で判定するスコアラーです。結果は mlflow server --port 5000 で起動したUIの「Runs」タブから、実行単位で見られます。

Claude Codeからは、このスクリプトを書かせて実行させ、出力を読ませる反復に使います。ここで効くのは、プロンプトの出来よりも「評価スクリプトを毎回同じ場所に置く」という約束です。

• 評価データセットとスクリプトを同じディレクトリに固定する
• スコアラーを変えずに、修正前後で同じ実行を繰り返す
• 結果の比較は、MLflowのRunsで前回と今回を並べて確認する

修正と再検証

修正後の検証は、同じデータセットと同じスコアラーで評価を再実行することです。スコアラーを一緒に直してしまうと、改善したのか基準が緩んだのか区別できなくなります。

プラグインには、修正の前に回帰テストを書く手順があると紹介されています。「fix this agent issue」と頼むと、そのスキルに振り分けられる想定です。回帰テストを先に置くのは、直したつもりの再発を防ぐ定番のやり方です。評価を軸にツールを磨く考え方はエージェント向けツール設計の原則でも扱っています。

削除系ツールをClaudeに勝手に実行させない

MCPサーバーの全ツールのうち、delete_traces、delete_trace_tag、delete_assessment は戻せない操作です。ドキュメントの使用例にも「30日より古いトレースを削除して」という依頼が載っており、Claudeは delete_traces をタイムスタンプ条件付きで呼びます。

Claude Codeの権限ルールは、MCPツールを mcp__<サーバー名>__<ツール名> で指定します。上の登録例ではサーバー名が mlflow-mcp なので、mcp__mlflow-mcp__delete_traces になります。.claude/settings.json に拒否ルールを置けば、削除系だけを止められます。

{
  "permissions": {
    "deny": [
      "mcp__mlflow-mcp__delete_traces",
      "mcp__mlflow-mcp__delete_trace_tag",
      "mcp__mlflow-mcp__delete_assessment"
    ]
  }
}

サーバー全体を指す mcp__mlflow-mcp__* の形でも書けます。ただし括弧付きの引数条件は、MCPツールのルールでは読み飛ばされる点に注意が必要です。「30日以内なら許可」のような条件は書けないので、削除系は全面禁止にするか、毎回確認(ask)に回す二択になります。

読み取りだけで足りる調査用のセッションなら、mcp__mlflow-mcp__search_traces と mcp__mlflow-mcp__get_trace だけを許可する構成も取れます。

つまずきやすい点

MLflowのバージョンが合わない。MCPが3.5.1以上、プラグインが3.8以上です。uv run --with "mlflow[mcp]>=3.5.1" の指定は下限なので、新しいバージョンが解決されるかどうかは環境次第です。プラグインを使うなら、手元のサーバー側のバージョンも上げておきます。

接続先を間違える。 MLFLOW_TRACKING_URI が空だと、意図しない場所を見ます。ローカルで試すだけなら、mlflow server --port 5000 で立てて http://localhost:5000 を指定するのが最短です。

応答が重い。 extract_fields を付けずに get_trace を連発すると、スパンの入出力が丸ごと返ります。一覧は絞り、詳細は1件ずつ読みます。

トレース自体が取れていない。そもそも計装していなければ、MCPで引けるものがありません。MLflowのトレースは、mlflow.openai.autolog() のような1行の自動トレース、または @mlflow.trace デコレータで取り始めます。AnthropicのSDKならautologの対象に anthropic を指定できます。SDK側のOpenTelemetry出力を使う方式はAnthropic SDKのOpenTelemetryトレースの記事にまとめています。

プラグインの入れ方。プラグインの導入経路は、マーケットプレイスの指定方法で変わります。コマンドの使い分けはclaude plugin installの記事を参照してください。

まとめ

MLflow MCPサーバーはトレースを読み書きする手足で、MLflowプラグインは改善ループの進め方を持つ手順書です。まず小さく始めるなら、MCPサーバーを genai カテゴリのまま入れて、失敗トレースの検索と extract_fields による絞り込みだけを使うのが入りやすいでしょう。評価の実行は mlflow.genai.evaluate に任せ、削除系ツールは拒否ルールで先に塞いでおきます。

そのうえでMLflowを3.8以上に上げてプラグインを足すと、計装から回帰テストまでを依頼文1つで振り分けられるようになります。MCPサーバーが実験的機能である点だけは、バージョンを上げる前に変更履歴を見る理由になります。