Xplainable MCP Server

A Model Context Protocol server for the Xplainable platform. It lets an LLM agent (Claude, or any MCP client) train, deploy, optimise, and explain transparent machine-learning models. The agent is the orchestrator: it inspects the data, decides features and preprocessing, trains, reads the metrics, and iterates.

Training always runs server-side on the Xplainable platform — the MCP host never fits a model locally.

Two Ways to Use It

1. Hosted — connect your MCP client to https://mcp.xplainable.io (OAuth login, no installation).
2. Local — run the server yourself over stdio with an Xplainable API key. This is what the rest of this README covers.

Quick Start (Local)

1. Get an API key

Create one at platform.xplainable.io.

2a. Claude Code

claude mcp add xplainable \
  -e XPLAINABLE_API_KEY=your-api-key-here \
  -- uvx --from git+https://github.com/xplainable/xplainable-mcp-server.git xplainable-mcp

2b. Claude Desktop

Add to your MCP settings file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "xplainable": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/xplainable/xplainable-mcp-server.git", "xplainable-mcp"],
      "env": {
        "XPLAINABLE_API_KEY": "your-api-key-here"
      }
    }
  }
}

No uv? Clone and install instead:

git clone https://github.com/xplainable/xplainable-mcp-server.git
cd xplainable-mcp-server
python -m venv .venv && source .venv/bin/activate
pip install -e .

then use "command": "/path/to/xplainable-mcp-server/.venv/bin/xplainable-mcp" (no args) in the config above.

3. Try it

Ask your agent: "What models and datasets do I have?" — it should call models_list_team_models and datasets_list_team_datasets.

The Iterate Loop

The tool surface puts the agent in control of every training decision:

1. datasets_list_team_datasets / models_list_team_models / deployments_list_deployments — see the team's assets
2. datasets_preview_dataset_json(dataset_id) — inspect columns, types, and sample rows; decide the target, columns to drop, and whether preprocessing is needed
3. (Optional) preprocessing_list_available_transformers → preprocessing_create_preprocessor_from_spec → preprocessing_preview_from_data to verify transformed output 3b. Declare feature relationships once per dataset: datasets_infer_relationships proposes derived columns, implications and monotonic hints with evidence; commit with datasets_set_relationships (re-apply to old versions with models_apply_relationships)
4. models_train_model(dataset_id, target_column, model_name, ...) — synchronous server-side training; returns model/version IDs, train/test metrics, and feature importances
5. Inspect: models_get_feature_info / gpt_explain_model; compare train vs test metrics
6. Iterate: models_refit_features for per-feature tuning, or train again with different features / preprocessing
7. deployments_deploy(version_id) — deploy once satisfied (then deployments_activate_deployment)
8. Act on the model: inference_predict / optimisers_run_optimiser / reports_create_report (+ poll reports_get_job_status)

Tool Surface

Tools are generated at server startup from @mcp_tool-decorated methods in the xplainable-client package — there are no checked-in generated files. The surface is flat: every registry tool is exposed, with MCP annotations derived from its category (read → read-only hint, write → destructive hint).

Configuration

Variable	Required	Description
XPLAINABLE_API_KEY	yes (local)	API key from platform.xplainable.io
XPLAINABLE_HOST / XPLAINABLE_HOSTNAME	no	Platform host override (defaults to https://platform.xplainable.io). Set both to the same value.
XPLAINABLE_INFERENCE_HOST	no	Inference server override for the direct-to-inference tools (inference_score_dataset, optimisers_run_portfolio); defaults to https://inference.xplainable.io. Set it whenever the platform host is non-prod.
XPLAINABLE_ORG_ID / XPLAINABLE_TEAM_ID	no	Org/team binding, if your API key is not bound to a team
MCP_TRANSPORT	no	stdio (default) or streamable-http
LOG_LEVEL	no	DEBUG, INFO (default), WARNING, ERROR

See .env.example. The API key is read from the environment only and is never exposed through a tool.

CLI

xplainable-mcp-cli list-tools            # list all available tools
xplainable-mcp-cli validate-config       # check env configuration
xplainable-mcp-cli test-connection       # test API connectivity
xplainable-mcp-cli generate-docs         # generate tool documentation

Docker (HTTP mode)

cp .env.example .env   # fill in your API key
docker compose up --build

The container serves streamable-HTTP on port 8000 with a /health endpoint. For anything beyond localhost, terminate TLS at a reverse proxy.

Development

git clone https://github.com/xplainable/xplainable-mcp-server.git
cd xplainable-mcp-server
pip install -e ".[dev]"

pytest            # run tests
ruff check .      # lint

Runtime tool generation

Client-backed tools are generated at import time by xplainable_mcp/runtime_tools.py from the @mcp_tool registry in xplainable-client — there is no sync step. Upgrading the pinned xplainable-client version is all it takes to pick up new or changed tools; the test suite (tests/test_surface.py) pins the tool count so surface changes are always deliberate.

Compatibility

MCP Server	xplainable-client	fastmcp
current (main)	>=1.13.0	>=2.0.0,<3.0.0

Contributing

See CONTRIBUTING.md.

License

MIT License — see LICENSE.