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 在本地训练小型模型，并且需要 challenger extra，该 extra 会安装 scikit-learn 和 scipy：

pip install 'mcp-proxyml[challenger]'

如果未安装该 extra，这两个工具会返回清晰的错误信息，提示你安装该 extra，而不会导致服务启动失败。

环境变量

变量	必需	说明
PROXYML_API_KEY	是	你的 ProxyML API 密钥

安全与权限

此服务可以访问的内容

文件系统 — proxyml_infer_schema 和 proxyml_train_challenger 各自会读取你指定路径下的一个 CSV 文件。其他工具不会读取或写入本地文件。

网络 — 仅出站 HTTPS，目标为 https://api.proxyml.ai（或 PROXYML_BASE_URL 中设置的网址）。不会连接其他主机。

环境 — 只会读取 PROXYML_API_KEY 和 PROXYML_BASE_URL。不会访问其他环境变量。

不执行 shell 命令，不使用本地端口，也不访问其他系统资源。

发送到 ProxyML 服务器的内容

工具	传输的内容
proxyml_infer_schema	无 — CSV 仅在本地读取和处理
proxyml_train_challenger	无 — 训练完全在本地进行；只有当你选择自行上传时，返回的负载才会被发送
proxyml_score_champion	无 — 评分完全在本地进行
proxyml_put_schema	特征模式：列名、类型和约束
proxyml_get_schema	模式名称（字符串）
proxyml_synthesize_data	模式名称、样本数量，以及可选的一个特征向量
proxyml_train_surrogate	合成特征向量，以及模型对这些向量的预测结果
proxyml_predict_batch	你明确传入的特征向量
proxyml_explain_local / proxyml_explain_local_batch	你明确传入的一个或多个特征向量
proxyml_find_counterfactual	一个特征向量和一个目标标签
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”按钮，或自行将其 POST 到 /app/projects/{project_id}/challenger。

身份验证

每次请求都会通过 TLS 在 X-API-KEY HTTP 标头中发送你的 API 密钥。 此密钥从 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 extra（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	在一次调用中分解多个实例中各特征的贡献
proxyml_find_counterfactual	查找能翻转预测结果的最近点
proxyml_find_counterfactuals	proxyml_find_counterfactual 的批量版本，可处理多个实例
proxyml_diff_models	比较两个代理模型版本之间的特征重要性

CI/CD

工具	描述
proxyml_detect_drift	比较两个版本，并根据系数和保真度阈值返回结构化的通过/失败结果

账户

工具	描述
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 比较不同版本。

Agent 工作流

在 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 中可以顺畅地完成，因为 Agent 能直接执行代码：

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 返回低保真度警告或其他训练诊断信息时，Agent 可以利用这些信息指导下一轮迭代，而不是就此停止：

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.

训练警告（收敛性、稀疏性、类别不平衡、高相关性）旨在提供可执行的建议——Agent 可以读取这些信息，并决定是否 调整 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），并编写报告。