Modelport

modelport

Turn any ML model into an MCP tool in 3 lines of code.

modelport wraps your trained model behind a standardized, self-describing capability that AI agents can discover, understand, and safely invoke via MCP (Model Context Protocol).

It provides:

• Model-first API — Capability.from_model() auto-infers schemas from trained models
• Rich MCP tool descriptions — LLMs see purpose, when-to-use guidance, input requirements, and limitations
• Input/output validation — every invocation is validated against JSON Schema before and after execution
• Structured error handling — standardized error codes, recoverable error hints, and retry guidance for MCP workflows
• Runtime safety — retry, timeout, and rate-limiting semantics built in
• MCP server — serve via stdio or StreamableHTTP for MCP clients

Install

# Core only (no ML dependencies)
pip install modelport

# With scikit-learn support
pip install "modelport[sklearn]"

# With XGBoost support
pip install "modelport[xgboost]"

# With LightGBM support
pip install "modelport[lightgbm]"

# With everything
pip install "modelport[all]"

For local development:

uv sync

Supported Backends

Backend	Extra	Status
scikit-learn estimators	sklearn	Fully supported
XGBoost sklearn API (XGBClassifier, XGBRegressor)	xgboost	Fully supported
LightGBM sklearn API (LGBMClassifier, LGBMRegressor)	lightgbm	Fully supported
Python callable (dict -> dict)	core	Fully supported

Quick Start

1. Describe your model

from sklearn.datasets import load_iris
from sklearn.linear_model import LogisticRegression

from modelport import Capability

model = LogisticRegression(max_iter=200).fit(*load_iris(return_X_y=True))

capability = Capability.from_model(
    model,
    capability_id="iris-classifier",
    purpose="Predict iris species from flower measurements.",
    when_to_use=("You have sepal/petal measurements",),
    when_not_to_use=("You need regression or continuous outputs",),
)

result = capability.invoke({"sepal_length": 5.1, "sepal_width": 3.5, "petal_length": 1.4, "petal_width": 0.2})
print(result)

2. Serve as MCP

from modelport.server.mcp_server import MCPCapabilityServer

server = MCPCapabilityServer(capability)
mcp = server.as_fastmcp(name="iris-classifier")
mcp.run(transport="stdio")

Connect to Claude Desktop, Cursor, or any MCP client — the tool appears with a rich description, correct input schema, and validation.

3. Example with VSCode.

Just add the following config to .vscode/mcp.json on the project's root folder:

{
  "servers": {
    "iris-classifier": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "examples/04_multi_model_mcp/server.py",
        "--transport",
        "stdio"
      ]
    }
  }
}

Error Handling

modelport provides structured error handling with:

• Error codes: VALIDATION_ERROR, BACKEND_ERROR, RATE_LIMITED, TIMEOUT, INTERNAL_ERROR
• Recoverability hints: Tells clients if errors are recoverable (transient) or fatal
• Retry guidance: retry_after_seconds for rate limits and timeouts
• Unified format: Consistent structured errors across modelport MCP flows

from modelport import CapabilityError, ErrorCode

# Errors are automatically structured by modelport
# MCP clients receive:
{
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Invalid input provided",
        "recoverable": "recoverable",
        "details": {
            "validation_errors": [...]
        }
    }
}

Performance Features

• Parallel batch predictions: True async/await parallelism (5-10x faster than sequential)

Pydantic Model Support

Use Pydantic models to define input/output contracts:

from pydantic import BaseModel

class IrisInput(BaseModel):
    sepal_length: float
    sepal_width: float
    petal_length: float
    petal_width: float

class IrisPrediction(BaseModel):
    species: str
    probability: float

capability = Capability.from_model(
    model,
    capability_id="iris-classifier",
    purpose="Predict iris species",
    input_model=IrisInput,
    output_model=IrisPrediction,
)

Development Commands

uv run pytest tests/ -v
uv run ruff check src/modelport/ tests/
uv run mypy src/modelport/

Examples

• examples/01_basic_classifier: sklearn Capability.from_model(...)
• examples/02_mcp_server: serving a model as MCP
• examples/03_gradient_boosting: XGBoost + LightGBM capabilities
• examples/04_multi_model_mcp: expose XGBoost + LightGBM as separate MCP tools in one server

Documentation

• API Documentation
• Core Concepts
• Runtime Backends
• MCP Server
• Validation