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 through a small set of goal-oriented workflow_* tools.

Training runs server-side on Xplainable's agentic pipeline — 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 workflow_list_assets.

The Workflow Loop

The curated workflow_* tools cover the whole journey:

1. workflow_list_assets — find a dataset (and see existing models / deployments)

2. workflow_train_model(dataset_id, goal, model_name) — returns a run_id

3. Loop: workflow_wait_for_update(run_id) — narrate progress as events arrive; if a decision is pending, relay it to the user and submit their answer via workflow_decide (the run's two gates: label selection and training approval)

4. workflow_deploy_model(model_id) — deploy after the run completes (there is no deployment gate inside the run)

5. Act on the model: workflow_optimise_model / workflow_predict (scores rows with the trained model via the platform inference route — no deployment needed) / workflow_explain_model / workflow_create_report

Tool Surface

By default the server registers the curated surface: 28 tools — the 9 workflow_* tools above, plus 16 curated read/health tools across datasets, models, deployments, optimisers, runs, agentic state, and gateway health, plus 3 team-selection tools (list_user_teams, set_active_team, select_team).

Set XPLAINABLE_ADVANCED_TOOLS=1 (accepted values: 1, true, yes) to register the full surface (~104 tools), adding write/admin tools for preprocessing, monitors, GPT reports, inference, and low-level agentic run control.

Tool files under xplainable_mcp/tools/ are auto-generated from @mcp_tool-decorated client methods (see "Synchronization with xplainable-client" below) — each tool carries tags (e.g. curated, workflow, read, write) that drive this gating. Do not hand-edit generated tool files.

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

Synchronization with xplainable-client

Tool files are generated from the xplainable-client package:

# Check if sync is needed / regenerate tool files
python scripts/sync_workflow.py --sync-files

# Generate a detailed report
python scripts/sync_workflow.py --markdown sync_report.md

See examples/SYNC_WORKFLOW.md and examples/sync_scenarios.md for the full process. Run the sync with the pinned xplainable-client version installed, and with Python 3.11+.

Compatibility

Contributing

See CONTRIBUTING.md.

License

MIT License — see LICENSE.