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.

Related MCP server: OSDU MCP Server

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

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

Contributing

See CONTRIBUTING.md.

License

MIT License — see LICENSE.