QuickLab MCP

QuickLab MCP (formerly ModelLab) is an enterprise-grade Machine Learning Experimentation Control Plane exposed via the Model Context Protocol (MCP). Engineered with FastMCP 4 and conforming to the standard MCP baseline (2026-07-28), QuickLab enables autonomous AI agents and human data scientists to discover approved architectures, validate tabular datasets, submit reproducible training experiments, inspect predictions/metrics, and perform deep diagnostic analysis—with zero arbitrary code execution.

---

Key Highlights

• Zero Placeholders, Real Tabular ML: Fully implemented, sandboxed training algorithms for all 7 approved tabular architectures: Logistic Regression, Random Forest, XGBoost, LightGBM, CatBoost, Linear SVM, and Multi-Layer Perceptron (MLP).
• 23 MCP Tools, 3 Resources, 2 Prompts: Comprehensive tool catalog across Projects, Discovery, Ingestion, Experimentation, Artifacts, and Diagnostics.
• Strict Leak-Free Preprocessing: Preprocessing transforms (median/mode imputation, standard scaling, one-hot encoding) are fitted strictly on training folds and serialized alongside models.
• Dual Production Transports:
  • STDIO Transport: Pure JSON-RPC on standard output (sys.stdout) with all structured logging isolated strictly to sys.stderr.
  • Streamable HTTP Transport: Modern HTTP transport mounted at /mcp with Bearer auth middleware and operational probes (/health/live, /health/ready).
• OAuth 2.1 & Multi-Tenant Security: Tenant boundary enforcement, RBAC matrix (Viewer, Researcher, Operator, Admin), token scope attenuation, and anti-enumeration protections (HTTP 404 instead of 403 on cross-tenant probes).
• Transactional Outbox Architecture: Guarantees zero lost experiment submissions using PostgreSQL transactional Outbox events dispatched to Redis queues.
• S3 / MinIO Object Storage: Immutable tenant-isolated artifact storage with SHA-256 integrity verification, presigned download URLs, and offline memory fallback.
• Full Test Coverage: 104 tests passing (100% green) across unit, integration, security matrix, MCP contract, and full end-to-end experiment lifecycle.

---

Architectural Topology

flowchart TD
    subgraph Clients["AI Agents & IDE Interfaces"]
        Claude["Claude Desktop / VS Code / Cursor"]
        Autonomous["Autonomous Agent Mesh"]
    end

    subgraph ControlPlane["ModelLab Control Plane (FastMCP 4)"]
        HTTPGateway["Streamable HTTP Gateway (/mcp)"]
        STDIOGateway["STDIO Transport (Local IPC)"]
        AuthMiddleware["OAuth 2.1 / OIDC Bearer Validator"]
        RateLimiter["Sliding-Window Rate Limiter"]
        ToolRouter["21 MCP Tools & Resource Engine"]
    end

    subgraph Persistence["Persistence & Message Broker"]
        Postgres[(PostgreSQL 16\nSchema & Outbox Events)]
        Redis[(Redis 7\nQueue & Rate Limit Window)]
        MinIO[(MinIO / S3\nDatasets & Model Artifacts)]
    end

    subgraph WorkerLayer["Sandboxed Worker Execution"]
        WorkerEngine["Tabular ML Execution Runner"]
        Preproc["Leak-Free Preprocessing Pipeline"]
        Trainers["7 Approved Tabular Trainers\n(RF, XGB, LGBM, CatB, LR, SVM, MLP)"]
    end

    subgraph Telemetry["Observability & Diagnostics"]
        OTEL["OpenTelemetry Collector"]
        JSONStderr["Structured JSON Logs (stderr)"]
    end

    Claude -->|STDIO| STDIOGateway
    Autonomous -->|HTTP Bearer| HTTPGateway
    HTTPGateway --> AuthMiddleware
    AuthMiddleware --> RateLimiter
    RateLimiter --> ToolRouter
    STDIOGateway --> ToolRouter

    ToolRouter --> Postgres
    ToolRouter --> Redis
    ToolRouter --> MinIO

    Postgres -->|Transactional Outbox| Redis
    Redis --> WorkerEngine
    WorkerEngine --> Preproc
    Preproc --> Trainers
    Trainers --> MinIO
    Trainers --> Postgres

    ControlPlane --> JSONStderr
    ControlPlane --> OTEL
    WorkerEngine --> OTEL

---

Complete MCP Tool Catalog

ModelLab exposes 23 granular tools across 6 functional categories:

1. Project Management Tools

Tool Name	Parameters	Required Scope	Description
create_project	name, description (opt)	ml:projects:write	Create a new project workspace under the caller's tenant boundary.
list_projects	limit (opt), offset (opt)	ml:projects:read	List active projects accessible within the caller's tenant boundary.

2. Discovery Tools

Tool Name	Parameters	Required Scope	Description
list_models	none	ml:models:read	List all approved tabular ML models in the catalog.
get_model	model_id	ml:models:read	Inspect hyperparameter schemas, bounds, and container digests for a model.
list_model_versions	model_id	ml:models:read	List registered immutable versions for a specific model family.
list_datasets	project_id (opt)	ml:datasets:read	List datasets available within the caller's tenant/project boundary.
get_dataset	dataset_id	ml:datasets:read	Retrieve metadata, format, and version history for a specific dataset.
list_dataset_versions	dataset_id	ml:datasets:read	List immutable versions, row counts, and SHA-256 hashes for a dataset.

3. Dataset Management & Validation Tools

Tool Name	Parameters	Required Scope	Description
register_dataset	project_id, name, description, format, data_base64, version	ml:datasets:write	Ingest and validate a tabular dataset (CSV/Parquet/JSONL), store as Parquet, and record content hash.
validate_dataset	format, data_base64	ml:datasets:read	Validate raw dataset bytes against schema rules and row limits without persisting.
inspect_dataset	dataset_id, version, sample_rows	ml:datasets:read	Inspect schema column types, missingness, and head preview rows.

4. Experimentation Tools

Tool Name	Parameters	Required Scope	Description
create_experiment	project_id, dataset_version_id, model_version_id, task_type, target_column, feature_columns, primary_metric, additional_metrics, hyperparameters, random_seed, idempotency_key	ml:experiments:create	Formulate, validate (target/feature columns, model bounds), and queue an ML experiment with transactional Outbox event.
get_experiment	experiment_id	ml:experiments:read	Retrieve current lifecycle state (QUEUED, RUNNING, SUCCEEDED, FAILED, CANCELLED), run counts, timestamps, and error details (error_message, error_type) if failed.
cancel_experiment	experiment_id	ml:experiments:cancel	Gracefully cancel an active or queued experiment run.
list_experiments	project_id, status, limit, offset	ml:experiments:read	Paginated listing of experiments within a project with optional status filter.

5. Results & Artifacts Tools

Tool Name	Parameters	Required Scope	Description
get_experiment_metrics	experiment_id	ml:experiments:read	Retrieve computed metrics across train and validation splits.
get_experiment_predictions	experiment_id, limit	ml:artifacts:read	Retrieve sample prediction records (y_true, y_pred, y_proba_*) and presigned download URL.
list_experiment_artifacts	experiment_id	ml:artifacts:read	List all persisted artifacts (model.joblib, preprocessor.joblib, predictions.parquet, metrics.json).
read_experiment_artifact	artifact_id	ml:artifacts:read	Retrieve artifact metadata and secure presigned S3 download URL.
compare_experiments	experiment_ids	ml:experiments:read	Side-by-side comparison of validation metrics and hyperparameters across runs.

6. Structured Diagnostic Analysis Tools

Tool Name	Parameters	Required Scope	Description
analyze_experiment	experiment_id	ml:analysis:create	Automated diagnostic report evaluating generalization gap, overfitting severity, and data leakage risks.
analyze_model_errors	experiment_id	ml:analysis:create	Deep error slice analysis including residual skew, false positives vs false negatives, and anomaly counts.
check_experiment_validity	experiment_id	ml:analysis:create	Automated verification of experiment validity, dataset lineage, and metric reproducibility.

---

MCP Resources & Prompts

Resources

• modellab://models: Static resource cataloging all approved model architectures.
• modellab://models/{model_id}: Parameterized template for full model hyperparameter schemas.
• modellab://experiments/{experiment_id}/metrics: Parameterized template for experiment metrics.

Prompts

• experiment_design: Guided architectural workflow prompting agents to formulate sound hypotheses, choose candidate models, and select non-leaking split strategies.
• error_diagnosis: Structured diagnostic workflow assisting agents in diagnosing training regressions, severe class imbalances, or generalization gaps.

---

Approved Model Families & Hyperparameter Bounds

Model Family	model_id	Supported Task Types	Key Hyperparameters (Strictly Validated)
Random Forest	random_forest	Binary / Multiclass Classification, Regression	n_estimators [10–1000], max_depth [1–50], min_samples_split [2–20]
XGBoost	xgboost	Binary / Multiclass Classification, Regression	n_estimators [10–2000], max_depth [1–16], learning_rate [0.001–1.0], subsample [0.1–1.0]
LightGBM	lightgbm	Binary / Multiclass Classification, Regression	n_estimators [10–2000], num_leaves [7–256], learning_rate [0.001–1.0]
CatBoost	catboost	Binary / Multiclass Classification, Regression	iterations [10–2000], depth [1–12], learning_rate [0.001–1.0]
Logistic Regression	logistic_regression	Binary / Multiclass Classification	C [0.001–1000.0], penalty (l1, l2, elasticnet, none), solver
Linear SVM	linear_svm	Binary / Multiclass Classification, Regression	C [0.001–100.0], loss (hinge, squared_hinge), max_iter [100–10000]
Multi-Layer Perceptron	mlp	Binary / Multiclass Classification, Regression	hidden_layer_sizes, activation (relu, tanh), alpha [1e-6–1.0], learning_rate_init

---

Quickstart

Prerequisites

• Python 3.13+ (or Conda environment ML_LLM)
• Docker & Docker Compose (optional, for local services)

1. Installation

Instant Execution via uvx (Recommended)

No cloning required — run QuickLab directly with Astral uv:

uvx quicklab-mcp

Local Development Installation

# Clone the repository
git clone https://github.com/Aldrin-Joan/QuickLab-MCP.git
cd QuickLab-MCP

# Install dependencies using uv
uv sync

2. Run the Full Test Suite

Verify all 75 automated tests across unit, integration, contract, security, and e2e suites:

pytest tests/ -v

Output:

================= 75 passed, 7 warnings in 187.73s (0:03:07) ==================

3. Launch Local Infrastructure (Optional)

Spin up PostgreSQL 16, Redis 7, MinIO S3, and OpenTelemetry Collector:

docker compose up -d

Apply database migrations:

alembic upgrade head

4. Running ModelLab

Option A: Streamable HTTP Mode (Production & Remote Agents)

python -m ml_mcp.server.http

Access operational endpoints:

• Liveness Probe: http://127.0.0.1:8000/health/live
• Readiness Probe: http://127.0.0.1:8000/health/ready
• MCP Endpoint: http://127.0.0.1:8000/mcp

Option B: STDIO Transport Mode (IDE & Desktop Agents)

python -m ml_mcp.server.stdio

---

MCP Client Configuration

ModelLab supports both STDIO (local subprocess IPC) and Streamable HTTP (networked SSE + POST) transports across both Docker and UV / local Python.

Select your preferred runtime configuration below:

1. Docker + STDIO

Runs ModelLab inside an isolated Docker container with standard I/O (sys.stdin / sys.stdout) piped directly to the MCP client.

{
  "mcpServers": {
    "modellab": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--entrypoint", "python",
        "--network", "host",
        "-e", "APP_ENV=production",
        "-e", "DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5433/modellab",
        "-e", "REDIS_URL=redis://localhost:6379/0",
        "-e", "OBJECT_STORE_ENDPOINT_URL=http://localhost:9000",
        "-e", "OBJECT_STORE_ACCESS_KEY_ID=minioadmin",
        "-e", "OBJECT_STORE_SECRET_ACCESS_KEY=minioadmin",
        "-e", "OBJECT_STORE_BUCKET_NAME=modellab-artifacts",
        "modellab-api",
        "-m", "ml_mcp.server.stdio"
      ]
    }
  }
}

Note for Docker Desktop (macOS / Windows): If --network host is unavailable in your Docker Desktop environment, connect via the shared Docker network:

"args": [
  "run", "-i", "--rm",
  "--entrypoint", "python",
  "--network", "modellab_default",
  "-e", "DATABASE_URL=postgresql+asyncpg://postgres:postgres@postgres:5432/modellab",
  "-e", "REDIS_URL=redis://redis:6379/0",
  "-e", "OBJECT_STORE_ENDPOINT_URL=http://minio:9000",
  "-e", "OBJECT_STORE_ACCESS_KEY_ID=minioadmin",
  "-e", "OBJECT_STORE_SECRET_ACCESS_KEY=minioadmin",
  "-e", "OBJECT_STORE_BUCKET_NAME=modellab-artifacts",
  "modellab-api",
  "-m", "ml_mcp.server.stdio"
]

---

2. Docker + HTTP

Connects to the ModelLab API service running inside Docker Compose (docker compose -f docker-compose.http.yml up -d).

{
  "mcpServers": {
    "modellab": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_JWT_BEARER_TOKEN>"
      }
    }
  }
}

---

3. UVX + STDIO (Recommended Turnkey Setup)

Runs QuickLab globally via uvx directly from PyPI:

{
  "mcpServers": {
    "quicklab": {
      "command": "uvx",
      "args": ["quicklab-mcp"],
      "env": {
        "APP_ENV": "production",
        "DATABASE_URL": "postgresql+asyncpg://postgres:postgres@localhost:5433/modellab",
        "REDIS_URL": "redis://localhost:6379/0",
        "OBJECT_STORE_ENDPOINT_URL": "http://localhost:9000",
        "OBJECT_STORE_ACCESS_KEY_ID": "minioadmin",
        "OBJECT_STORE_SECRET_ACCESS_KEY": "minioadmin",
        "OBJECT_STORE_BUCKET_NAME": "modellab-artifacts"
      }
    }
  }
}

Or for local source development with uv:

{
  "mcpServers": {
    "quicklab": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/absolute/path/to/QuickLab-MCP",
        "python", "-m", "ml_mcp.server.stdio"
      ],
      "env": {
        "APP_ENV": "production",
        "DATABASE_URL": "postgresql+asyncpg://postgres:postgres@localhost:5433/modellab",
        "REDIS_URL": "redis://localhost:6379/0",
        "OBJECT_STORE_ENDPOINT_URL": "http://localhost:9000",
        "OBJECT_STORE_ACCESS_KEY_ID": "minioadmin",
        "OBJECT_STORE_SECRET_ACCESS_KEY": "minioadmin",
        "OBJECT_STORE_BUCKET_NAME": "modellab-artifacts"
      }
    }
  }
}

---

4. UV + HTTP

Starts the ModelLab HTTP service locally with uv and connects client agents via Streamable HTTP.

1. Launch the server:

uv run python -m ml_mcp.server.http

2. Client Configuration (mcp.json / claude_desktop_config.json):

{
  "mcpServers": {
    "modellab": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_JWT_BEARER_TOKEN>"
      }
    }
  }
}

---

Generating an OAuth 2.1 Bearer Token (for HTTP Modes)

Generate a cryptographically signed JWT token for authentication in HTTP mode:

uv run python -c "
from ml_mcp.server.auth import TokenValidator
from ml_mcp.domain.policies import Role, Scope

validator = TokenValidator()
token = validator.create_access_token(
    principal_id='agent-user',
    tenant_id='default-tenant',
    role=Role.ADMIN,
    scopes=[s.value for s in Scope],
)
print('Bearer Token:\n' + token)
"

---

Security & Access Control (RBAC)

ModelLab implements a zero-trust security architecture adhering to OAuth 2.1:

Scope	Viewer	Researcher	Operator	Admin
ml:models:read	✅	✅	✅	✅
ml:datasets:read	✅	✅	✅	✅
ml:datasets:write	❌	✅	✅	✅
ml:experiments:read	✅	✅	✅	✅
ml:experiments:create	❌	✅	✅	✅
ml:experiments:cancel	❌	✅	✅	✅
ml:analysis:create	❌	✅	✅	✅
ml:artifacts:read	✅	✅	✅	✅
ml:worker:operate	❌	❌	✅	✅
ml:experiment:override	❌	❌	❌	✅

• Scope Attenuation: Access tokens carrying specific scopes attenuate privileges below role defaults.
• Anti-Enumeration Defense: Requests attempting cross-tenant resource access consistently return HTTP 404 (ResourceNotFoundError) rather than 403, preventing attackers from probing valid resource IDs.
• Sensitive Key Redaction: Telemetry and logs automatically scrub sensitive credentials (password, secret, token, key, authorization).

---

Production Containerization

Multi-stage Dockerfile provides hardened images running as unprivileged users:

# Build API Server container
docker build --target ml-mcp-api -t modellab/ml-mcp-api:latest .

# Build Sandboxed Worker container
docker build --target ml-worker-tabular-cpu -t modellab/ml-worker-tabular-cpu:latest .

Both container images run with read-only root filesystems and non-root users (uid 10001 / uid 10002).

---

Project Repository Structure

ModelLab/
├── .github/workflows/ci.yml       # Automated CI/CD pipeline (lint, test, build)
├── alembic/versions/              # Database migration scripts
├── deploy/docker/                 # OTEL Collector and container deployment configs
├── Docs/                          # Architecture, Tech-Stack & Operational Guide
├── src/ml_mcp/                    # Core ModelLab application source
│   ├── application/               # Application services (models, datasets, analysis)
│   ├── config/                    # Pydantic Settings & environment parsing
│   ├── domain/                    # Domain models, policies, RBAC & error hierarchy
│   ├── infrastructure/            # Postgres ORM, Redis queue, S3 storage, OTEL
│   ├── mcp/                       # FastMCP 4 tools, schemas, resources & prompts
│   ├── server/                    # Server factory, auth validator, HTTP & STDIO
│   └── workers/                   # Preprocessing, ML trainers & execution runner
├── tests/                         # 75 Automated Test Cases
│   ├── contract/                  # FastMCP tool contract compliance tests
│   ├── e2e/                       # Full ML experiment lifecycle end-to-end tests
│   ├── integration/               # Database, Outbox, Redis & Worker integration
│   ├── security/                  # Multi-tenant isolation & RBAC security matrix
│   └── unit/                      # Fast unit tests across all domain layers
├── docker-compose.yml             # Local PostgreSQL, Redis, MinIO & OTEL stack
├── Dockerfile                     # Multi-stage production container build
├── pyproject.toml                 # Package definition and locked dependencies
└── README.md                      # Project documentation

---

License

ModelLab is licensed under the Apache License, Version 2.0. See LICENSE for details.