Mcp Proxyml
mcp-proxyml
MCP server for the ProxyML API. Gives Claude (and other MCP clients) direct access to ProxyML's surrogate modelling and explainability tools.
Prerequisites
- A ProxyML API key — sign up at proxyml.ai
- uv (required for
uvxinstallation method)
curl -LsSf https://astral.sh/uv/install.sh | sh
Or if you use 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"
}
}
}
}
The config file is at:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Then restart Claude Desktop.
Claude Code
claude mcp add-json proxyml '{"command":"uvx","args":["mcp-proxyml"],"env":{"PROXYML_API_KEY":"your-api-key-here"}}'
Other MCP clients
pip install mcp-proxyml
PROXYML_API_KEY=your-key mcp-proxyml
Environment variables
| Variable | Required | Description |
|---|---|---|
PROXYML_API_KEY | Yes | Your ProxyML API key |
Security & permissions
What this server can access
Filesystem — proxyml_infer_schema reads one CSV file at the path you
provide. No other tool reads or writes local files.
Network — outbound HTTPS only, to https://api.proxyml.ai (or the URL
set in PROXYML_BASE_URL). No other hosts are contacted.
Environment — only PROXYML_API_KEY and PROXYML_BASE_URL are read.
No other environment variables are accessed.
No shell execution, no local ports, no other system resources.
What is sent to ProxyML's servers
| Tool | What is transmitted |
|---|---|
proxyml_infer_schema | Nothing — CSV is read and processed locally only |
proxyml_put_schema | Feature schema: column names, types, and constraints |
proxyml_get_schema | Schema name (string) |
proxyml_synthesize_data | Schema name, sample count, and optionally one feature vector |
proxyml_train_surrogate | Synthetic feature vectors + your model's predictions for those vectors |
proxyml_predict_batch | Feature vectors you pass explicitly |
proxyml_explain_local / proxyml_explain_local_batch | Feature vector(s) you pass explicitly |
proxyml_find_counterfactual | One feature vector and a target label |
proxyml_list_surrogates / proxyml_get_summary / proxyml_export_surrogate / proxyml_diff_models / proxyml_detect_drift | Version IDs and/or threshold values (no feature data) |
proxyml_get_usage | Nothing |
The typical workflow is designed so that raw training data never leaves your
environment. proxyml_infer_schema derives column metadata from your CSV
locally; proxyml_synthesize_data generates samples server-side from that
schema; and proxyml_train_surrogate sends only those synthetic samples
plus your model's predictions for them. Your original dataset is not
transmitted.
If you use proxyml_explain_local, proxyml_predict_batch, or
proxyml_find_counterfactual with real data points rather than synthetic
ones, those feature vectors will be sent to the ProxyML API.
Authentication
Your API key is sent on every request as an X-API-KEY HTTP header over TLS.
It is read from the PROXYML_API_KEY environment variable and is never
logged or written to disk by this server.
Tools
Schema
| Tool | Description |
|---|---|
proxyml_infer_schema | Infer a feature schema from a local CSV file — no data sent to the server |
proxyml_get_schema | Retrieve a stored schema by name |
proxyml_put_schema | Upload or replace a feature schema |
Training
| Tool | Description |
|---|---|
proxyml_synthesize_data | Generate synthetic samples from the stored schema |
proxyml_train_surrogate | Train a linear surrogate on samples scored by your model |
proxyml_list_surrogates | List trained surrogate models, newest first |
proxyml_predict_batch | Get surrogate predictions for a list of instances |
Explainability
| Tool | Description |
|---|---|
proxyml_get_summary | Feature importances and model summary |
proxyml_export_surrogate | Full coefficient export for audit and governance |
proxyml_explain_local | Per-feature contribution breakdown for a single instance |
proxyml_explain_local_batch | Per-feature contributions for multiple instances in one call |
proxyml_find_counterfactual | Find the nearest point that flips the prediction |
proxyml_diff_models | Compare feature importances between two surrogate versions |
CI/CD
| Tool | Description |
|---|---|
proxyml_detect_drift | Compare two versions and return a structured pass/fail against coefficient and fidelity thresholds |
Account
| Tool | Description |
|---|---|
proxyml_get_usage | Current tier, request count, and quota — useful as a pre-flight check |
Typical workflow
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
Steps 1–2 are one-time setup. Steps 3–5 can be repeated to retrain as your model changes; use proxyml_diff_models to compare versions.
Agentic workflows
Drift detection in CI/CD
proxyml_detect_drift is designed for use in deployment pipelines. It wraps proxyml_diff_models and applies thresholds to produce a structured pass/fail:
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
Thresholds can be tuned per use case:
proxyml_detect_drift(
version_a="<previous>",
version_b="<new>",
coefficient_threshold=0.15, # tighter for high-stakes models
fidelity_threshold=0.02
)
Dev model validation without production data
Validate a model trained in a lower environment by comparing its predictions against a surrogate trained on production data — no production data required in the dev environment.
This workflow requires a step the MCP server can't do on its own (scoring with your dev model), but works naturally in Claude Code where the agent can execute code directly:
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]
Example prompt for 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.
The surrogate acts as a proxy for production behaviour — if the dev model agrees with it within tolerance, it's likely behaving consistently with what was trained on real data.
Counterfactual investigation
When a model makes a decision that needs explaining — a rejected loan application,
a flagged transaction, a declined insurance quote — chain proxyml_explain_local
and proxyml_find_counterfactual to answer both "why?" and "what would need to
change?":
1. proxyml_explain_local(instance) → which features drove this decision
2. proxyml_find_counterfactual(instance, target) → nearest point that flips it
Example prompt:
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 will call proxyml_explain_local to surface the top contributing features,
then proxyml_find_counterfactual with the target outcome, and interpret the
difference in plain language.
Iterative surrogate improvement
When proxyml_train_surrogate returns a low fidelity warning or other training
diagnostic, the agent can use it to guide the next iteration rather than stopping:
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
Example prompt:
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.
The training warnings (convergence, sparsity, class imbalance, high correlation)
are designed to be actionable — the agent can read them and decide whether to
adjust num_samples, revisit the schema, or flag for human review.
Governance report
Claude can generate a governance report from existing tools without a dedicated endpoint. Example prompt:
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 will call proxyml_get_summary (and proxyml_list_surrogates to find metadata) and compose the report.
Server Config
{
"mcpServers": {
"proxyml": {
"command": "uvx",
"args": [
"mcp-proxyml"
],
"env": {
"PROXYML_API_KEY": "your-api-key-here"
}
}
}
}