Mcp Proxyml

mcp-proxyml

ProxyML API 用の MCP サーバーです。Claude（およびその他の MCP クライアント）から、ProxyML の代理モデリングおよび説明可能性ツールに直接アクセスできます。

前提条件

• ProxyML API キー — proxyml.ai で登録してください
• uv（uvx インストール方法で必要）

  curl -LsSf https://astral.sh/uv/install.sh | sh

または、pip を使う場合：

pip install uv

Installation

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "proxyml": {
      "command": "uvx",
      "args": ["mcp-proxyml"],
      "env": {
        "PROXYML_API_KEY": "your-api-key-here"
      }
    }
  }
}

設定ファイルは次の場所にあります：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

その後、Claude Desktop を再起動してください。

Claude Code

claude mcp add-json proxyml '{"command":"uvx","args":["mcp-proxyml"],"env":{"PROXYML_API_KEY":"your-api-key-here"}}'

その他の MCP クライアント

pip install mcp-proxyml
PROXYML_API_KEY=your-key mcp-proxyml

ローカルでのチャレンジャーのトレーニング（任意）

proxyml_train_challenger と proxyml_score_champion は、proxyml SDK を介して小規模なモデルをローカルでトレーニングします。scikit-learn と scipy をインストールする challenger エクストラが必要です：

pip install 'mcp-proxyml[challenger]'

これをインストールしていない場合、サーバーの起動に失敗するのではなく、このエクストラのインストールを促す明確なエラーがこれら 2 つのツールから返されます。

環境変数

変数	必須	説明
PROXYML_API_KEY	はい	ProxyML API キー

セキュリティと権限

このサーバーがアクセスできるもの

ファイルシステム — proxyml_infer_schema と proxyml_train_challenger は、それぞれ指定されたパスにある CSV ファイルを 1 つ読み込みます。他のツールがローカルファイルを読み書きすることはありません。

ネットワーク — https://api.proxyml.ai（または PROXYML_BASE_URL に設定された URL）へのアウトバウンド HTTPS 通信のみです。他のホストには接続しません。

環境 — 読み取るのは PROXYML_API_KEY と PROXYML_BASE_URL のみです。他の環境変数にはアクセスしません。

シェル実行、ローカルポート、その他のシステムリソースへのアクセスはありません。

ProxyML のサーバーに送信されるデータ

ツール	送信される内容
proxyml_infer_schema	なし — CSV はローカルでのみ読み込まれ、処理されます
proxyml_train_challenger	なし — トレーニングはすべてローカルで行われます。返されたペイロードは、自分でアップロードすることを選択した場合にのみ送信されます
proxyml_score_champion	なし — スコアリングはすべてローカルで行われます
proxyml_put_schema	特徴量スキーマ：列名、型、制約
proxyml_get_schema	スキーマ名（文字列）
proxyml_synthesize_data	スキーマ名、サンプル数、および任意で 1 つの特徴ベクトル
proxyml_train_surrogate	合成特徴ベクトルと、それらのベクトルに対するモデルの予測値
proxyml_predict_batch	明示的に渡した特徴ベクトル
proxyml_explain_local / proxyml_explain_local_batch	明示的に渡した特徴ベクトル
proxyml_find_counterfactual	1 つの特徴ベクトルとターゲットラベル
proxyml_list_surrogates / proxyml_get_summary / proxyml_export_surrogate / proxyml_diff_models / proxyml_detect_drift	バージョン ID および／またはしきい値（特徴データは含まれません）
proxyml_get_usage	なし

一般的なワークフローでは、未加工のトレーニングデータが環境外に出ないように設計されています。proxyml_infer_schema は CSV から列のメタデータをローカルで取得し、proxyml_synthesize_data はそのスキーマを使ってサーバー側でサンプルを生成します。そして、proxyml_train_surrogate が送信するのは、これらの合成サンプルと、それらに対するモデルの予測値のみです。元のデータセットは送信されません。

合成データではなく実データを使って proxyml_explain_local、proxyml_predict_batch、または proxyml_find_counterfactual を使用する場合、それらの特徴ベクトルは ProxyML API に送信されます。

proxyml_train_challenger と proxyml_score_champion は ProxyML API を一切呼び出しません。SDK のローカルなトレーニング／スコアリングコードをプロセス内で実行し、JSON ペイロードを返します。このサーバーがそのペイロードを代わりにアップロードすることはありません。ペイロードを保存し、ProxyML ダッシュボードの「Upload challenger」ボタンを使うか、/app/projects/{project_id}/challenger に自分で POST してください。

認証

API キーは、TLS 経由で X-API-KEY HTTP ヘッダーとしてすべてのリクエストに送信されます。 PROXYML_API_KEY 環境変数から読み取られ、このサーバーによって ログに記録されたり、ディスクに書き込まれたりすることはありません。

ツール

スキーマ

ツール	説明
proxyml_infer_schema	ローカルの CSV ファイルから特徴量スキーマを推論します。データはサーバーに送信されません
proxyml_get_schema	名前を指定して保存済みのスキーマを取得します
proxyml_put_schema	特徴量スキーマをアップロードまたは置き換えます
proxyml_list_schemas	認証済みアカウントの名前付き特徴量スキーマをすべて一覧表示します
proxyml_delete_schema	名前付き特徴量スキーマを削除します

トレーニング

ツール	説明
proxyml_synthesize_data	保存済みのスキーマから合成サンプルを生成します
proxyml_train_surrogate	お使いのモデルでスコアリングしたサンプルを使って線形サロゲートをトレーニングします
proxyml_list_surrogates	トレーニング済みのサロゲートモデルを新しい順に一覧表示します
proxyml_get_model_schema	サロゲートのトレーニング時にスナップショットされた特徴量スキーマを取得します
proxyml_update_surrogate	再トレーニングせずにサロゲートの名前を変更したり、注釈を追加したりします
proxyml_delete_surrogate	UUID を指定してサロゲートモデルを削除します
proxyml_predict	単一のインスタンスに対するサロゲートの予測を取得します
proxyml_predict_batch	インスタンスのリストに対するサロゲートの予測を取得します

ローカルでのチャレンジャーのトレーニング

challenger エクストラが必要です（pip install 'mcp-proxyml[challenger]'）。

ツール	説明
proxyml_train_challenger	CSV を使ってローカルでチャレンジャーモデルをトレーニングし、アップロード可能なペイロードを組み立てます
proxyml_score_champion	チャンピオンモデルの予測をローカルでスコアリングし、公平に比較します

説明可能性

ツール	説明
proxyml_get_summary	特徴量の重要度とモデルの概要
proxyml_export_surrogate	監査とガバナンスのための係数全体のエクスポート
proxyml_explain_local	単一のインスタンスについて、特徴量ごとの寄与度の内訳を表示します
proxyml_explain_local_batch	1 回の呼び出しで複数のインスタンスについて、特徴量ごとの寄与度を表示します
proxyml_find_counterfactual	予測が反転する最も近い点を見つけます
proxyml_find_counterfactuals	複数のインスタンスに対応した proxyml_find_counterfactual のバッチ版です
proxyml_diff_models	2 つのサロゲートのバージョン間で特徴量の重要度を比較します

CI/CD

ツール	説明
proxyml_detect_drift	2 つのバージョンを比較し、係数と忠実度のしきい値に基づいて、構造化された合否結果を返します

アカウント

ツール	説明
proxyml_get_usage	現在のティア、リクエスト数、クォータを表示します。事前確認に便利です

診断

ツール	説明
proxyml_health_check	API への接続を確認します。認証は不要で、使用量クォータにもカウントされません

典型的なワークフロー

1. proxyml_infer_schema      — point at a CSV, get a schema back
2. proxyml_put_schema        — upload it
3. proxyml_synthesize_data   — generate synthetic samples
4. [score samples with your model]
5. proxyml_train_surrogate   — send samples + predictions, get a surrogate
6. proxyml_get_summary       — see which features drive predictions
7. proxyml_explain_local     — explain a specific decision
8. proxyml_find_counterfactual — find what would need to change

ステップ 1～2 は初回のみのセットアップです。ステップ 3～5 はモデルの変更に応じて繰り返し実行して再トレーニングできます。バージョンの比較には proxyml_diff_models を使用してください。

エージェント型ワークフロー

CI/CD でのドリフト検出

proxyml_detect_drift はデプロイメントパイプラインでの使用を想定しています。proxyml_diff_models をラップし、しきい値を適用して構造化された合否結果を生成します。

On model deployment:
1. proxyml_train_surrogate          — train surrogate on new model version
2. proxyml_detect_drift(a, b)       — compare against previous version
   → passed: false                  — block deployment or flag for review
   → passed: true                   — proceed

しきい値はユースケースごとに調整できます。

proxyml_detect_drift(
  version_a="<previous>",
  version_b="<new>",
  coefficient_threshold=0.15,   # tighter for high-stakes models
  fidelity_threshold=0.02
)

本番データを使わない開発モデルの検証

本番データでトレーニングしたサロゲートと予測を比較して、下位環境でトレーニングしたモデルを検証できます。開発環境に本番データは必要ありません。

このワークフローでは、MCP サーバー単独では実行できない手順（開発モデルでのスコアリング）が必要ですが、エージェントがコードを直接実行できる Claude Code では自然に実行できます。

1. proxyml_synthesize_data(num_points=100)   → synthetic samples
2. [agent runs: dev_predictions = dev_model.predict(samples)]
3. proxyml_predict_batch(samples)            → surrogate predictions
4. [agent computes MAE and compares to tolerance]

Claude Code 用のプロンプト例：

Using ProxyML, validate my dev model against the production surrogate.
Synthesize 100 samples from the "default" schema, score them with my model
at dev_model.predict(), get surrogate predictions with proxyml_predict_batch,
then compute the mean absolute error and tell me whether it's within 0.1.

サロゲートは本番環境の挙動の代用として機能します。開発モデルが許容範囲内でサロゲートと一致すれば、実データでトレーニングしたモデルと一貫した挙動を示している可能性が高いです。

反実仮想の調査

説明が必要な判断をモデルが下した場合、たとえばローンの申請却下、 取引へのフラグ設定、保険見積もりの拒否などでは、proxyml_explain_local と proxyml_find_counterfactual を連続して呼び出し、「なぜか」と「何を 変更する必要があるか」の両方に答えます。

1. proxyml_explain_local(instance)              → which features drove this decision
2. proxyml_find_counterfactual(instance, target) → nearest point that flips it

プロンプトの例：

My model rejected this application: [age=34, income=42000, loan_amount=15000, ...].
Using ProxyML, explain why it was rejected and find the minimum changes that
would result in an approval. Highlight which changes are realistic given that
age is immutable.

Claude は proxyml_explain_local を呼び出して、主な寄与特徴量を示し、 次に目標の結果を指定して proxyml_find_counterfactual を呼び出し、 その違いを平易な言葉で解釈します。

代理モデルの反復的な改善

proxyml_train_surrogate が忠実度の低さに関する警告やその他のトレーニング診断を返した場合、エージェントはそこで 停止せず、次の反復に向けてそれらを活用できます。

1. proxyml_train_surrogate(samples, predictions)
   → warning: "Surrogate fidelity is low (R²=0.52)..."
2. proxyml_synthesize_data(num_points=500)       — increase sample count
3. [re-score with model]
4. proxyml_train_surrogate(larger_samples, predictions)
5. proxyml_detect_drift(v1, v2)                  — confirm improvement, not regression

プロンプトの例：

Train a surrogate for my regression model using the "default" schema with 200
samples. If fidelity is below 0.7, keep doubling the sample count and retraining
until it passes or you reach 1600 samples. Use proxyml_detect_drift after each
retrain to confirm the model is improving rather than just changing.

トレーニングの警告（収束、スパース性、クラスの不均衡、高い相関）は、 対処に役立つよう設計されています。エージェントはそれらを読み取り、 num_samples を調整するか、スキーマを見直すか、人間によるレビューが必要だと 判断できます。

ガバナンスレポート

Claude は、専用のエンドポイントがなくても、既存のツールからガバナンスレポートを生成できます。プロンプトの例：

Using ProxyML, generate a governance report for surrogate version <id>.
Include: task type, training date, fidelity metrics, top 5 features by importance,
any warnings from training, and a plain-English summary of what drives predictions.
Format it as a structured document suitable for attaching to a deployment ticket.

Claude は proxyml_get_summary を呼び出し（メタデータを見つけるために proxyml_list_surrogates も呼び出し）、レポートを作成します。