Model Manager MCP Server¶

Download Package ¶

Overview¶

The Insights Hub Model Manager MCP Server is a Model Context Protocol (MCP) server that exposes the Insights Hub Model Manager APIs as a set of tools consumable by any MCP-compatible AI client (e.g., Claude Desktop, JetBrains AI, VS Code Copilot).

It bridges your AI assistant with the following Insights Hub backend services:

The server exposes 39 tools in total: - 2 built-in tools - connectivity check and token acquisition - 1 inference tool - run_inference, a dedicated MLServer-style invocation tool - 36 API tools - full CRUD over all supported Insights Hub resources

Transport modes supported: - --stdio (default) - launched directly by an MCP client as a subprocess - --sse - runs as a standalone HTTP server using Server-Sent Events

Prerequisites¶

Installation¶

Install from the Wheel¶

You will receive a .whl file (e.g., model_manager_mcp_server-1.0.0-py3-none-any.whl). Install it into a dedicated virtual environment:

# Create and activate the virtual environment
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip

# Install the wheel
.\.venv\Scripts\python.exe -m pip install .\model_manager_mcp_server-1.0.0-py3-none-any.whl

After installation, the command model-manager-mcp is available inside .venv\Scripts\.

Verify the Installation¶

.\.venv\Scripts\model-manager-mcp.exe --help

Configuration¶

All runtime settings are read from environment variables. You can supply them either via a .env file placed in the working directory or via the MCP client's env configuration block.

Required Settings (All Modes)¶

Required Settings (SSE Mode Only)¶

Optional Settings¶

.env File Example¶

Create a .env file in your working directory:

MODEL_MANAGER_CLIENT_ID=my-client-id
MODEL_MANAGER_CLIENT_SECRET=my-client-secret
MODEL_MANAGER_TENANT=my-tenant
MODEL_MANAGER_BASE_URL=https://gateway.eu1.mindsphere.io
MODEL_MANAGER_TOKEN_URL=https://gateway.eu1.mindsphere.io/api/technicaltokenmanager/v3/oauth/token
MODEL_MANAGER_MCP_SERVER_NAME=modelmanager

# Only needed for --sse mode:
# MCP_HOST=0.0.0.0
# MCP_PORT=3001

Running the Server¶

stdio Mode (Recommended for MCP Clients)¶

This is the default mode. The MCP client starts the server as a subprocess and communicates over standard input/output:

.\.venv\Scripts\model-manager-mcp.exe --stdio

SSE Mode (HTTP Server)¶

In SSE mode, the server runs as a standalone HTTP service. This requires MCP_HOST and MCP_PORT to be configured.

.\.venv\Scripts\model-manager-mcp.exe --sse

The server will listen at:

http://<MCP_HOST>:<MCP_PORT>/sse

SSE mode requires starlette and uvicorn, which are included in the wheel's dependencies.

MCP Client Setup¶

stdio Client Configuration (mcp.json)¶

Add the following to your MCP client's configuration file:

{
  "servers": {
    "model-manager": {
      "type": "stdio",
      "command": "model-manager-mcp",
      "args": ["--stdio"],
      "cwd": ".",
      "env": {
        "MODEL_MANAGER_CLIENT_ID": "<your-client-id>",
        "MODEL_MANAGER_CLIENT_SECRET": "<your-client-secret>",
        "MODEL_MANAGER_TENANT": "<your-tenant-id>",
        "MODEL_MANAGER_BASE_URL": "<your-model-registry-base-url>",
        "MODEL_MANAGER_TOKEN_URL": "<your-token-url>"
      }
    }
  }
}

Tip: If your client does not inherit the virtual environment's PATH, set "command" to the absolute path of the executable, e.g.:

"command": "C:\\Users\\you\\projects\\mcp\\.venv\\Scripts\\model-manager-mcp.exe"

SSE Client Configuration¶

If the server is running in SSE mode, configure your client to connect to the running HTTP server:

{
  "servers": {
    "model-manager": {
      "type": "sse",
      "url": "http://localhost:3001/sse"
    }
  }
}

Authentication¶

The server uses OAuth2 Client Credentials with tenant impersonation (Insights Hub Technical Token Manager).

How It Works¶

1. On the first API call per session, the server requests a Bearer token from MODEL_MANAGER_TOKEN_URL using the configured CLIENT_ID and CLIENT_SECRET.
2. The token is cached per tenant and automatically refreshed 60 seconds before it expires (default token lifetime is 3600 seconds).
3. Every downstream API request carries the Bearer token in the Authorization header.

Per-Request Credential Override¶

The built-in auth_getToken tool accepts optional overrides so you can test with alternative credentials without changing the server configuration:

{
  "clientId": "alternate-client-id",
  "clientSecret": "alternate-secret",
  "tokenUrl": "https://alternate-token-url/token"
}

Available Tools Reference¶

Built-in Tools¶

These two tools are always available regardless of backend configuration.

ping¶

Test that the MCP server is running and reachable.

Example response: Model Registry MCP server is running.

auth_getToken¶

Acquire a Bearer token using OAuth2 Client Credentials with tenant impersonation.

Example response:

{
  "access_token": "eyJ..."
}

Inference Tool¶

run_inference is a dedicated tool for sending predictions to a deployed model server. It is registered separately from both the built-in utility tools and the manifest-driven API tools because it uses a custom MLServer-style payload (inputs[], optional parameters) rather than the generic body wrapper.

URL: POST {MODEL_MANAGER_BASE_URL}/api/modelmanager/v3/inference/{model_id}?modelType=mlserver

By contrast, model server management tools use: POST {MODEL_MANAGER_BASE_URL}/api/modelmanager/v3/modelservers

run_inference¶

Run inference on a deployed model server using an MLServer-compatible payload.

Input tensor structure:

{
  "name": "input-0",
  "data": [1.0, 2.0, 3.0],
  "datatype": "FP64",
  "shape": [1, 3]
}

Example request body:

{
  "inputs": [
    {
      "name": "input-0",
      "data": [5.1, 3.5, 1.4, 0.2],
      "datatype": "FP64",
      "shape": [1, 4]
    }
  ]
}

Note: model_id is passed as a tool parameter and used in the URL path (POST .../inference/{model_id}). The optional modelType query parameter (default: mlserver) specifies the model type. Only inputs and optional parameters are sent in the HTTP request body.

Model Registry - Registered Models¶

list_registered_models_get¶

List all registered models with optional filtering and pagination.

Endpoint: GET /api/modelmanager/v3/modelregistry/registeredmodels

create_registered_model_post¶

Create a new registered model.

Endpoint: POST /api/modelmanager/v3/modelregistry/registeredmodels

Request body:

{
  "name": "my-model",
  "description": "A machine learning model for predictions",
  "origin": "Predict",
  "customProperties": {
    "framework": { "string_value": "tensorflow" },
    "task": { "string_value": "classification" }
  }
}

get_registered_model_by_id_get¶

Retrieve a registered model by its ID.

Endpoint: GET /api/modelmanager/v3/modelregistry/registeredmodels/{model_id}

get_registered_model_by_name_get¶

Find a registered model by name.

Endpoint: GET /api/modelmanager/v3/modelregistry/registeredmodel

update_registered_model_patch¶

Update an existing registered model (partial update).

Endpoint: PATCH /api/modelmanager/v3/modelregistry/registeredmodels/{model_id}

Request body (partial):

{
  "description": "Updated description",
  "customProperties": {
    "status": { "string_value": "production" },
    "owner": { "string_value": "ml-team" }
  }
}

delete_registered_model_delete¶

Delete a registered model.

Endpoint: DELETE /api/modelmanager/v3/modelregistry/registeredmodels/{model_id}

Model Registry - Model Versions¶

list_model_versions_get¶

List versions for a registered model.

Endpoint: GET /api/modelmanager/v3/modelregistry/registeredmodels/{model_id}/versions

create_model_version_post¶

Create a new version for a registered model.

Endpoint: POST /api/modelmanager/v3/modelregistry/modelversions?model_id={model_id}

Request body:

{
  "name": "v1.0.0",
  "description": "First production release",
  "customProperties": {
    "accuracy": { "string_value": "0.95" }
  }
}

get_model_version_get¶

Get a specific model version by ID.

Endpoint: GET /api/modelmanager/v3/modelregistry/modelversions/{version_id}

get_model_version_by_name_get¶

Find a model version by name.

Endpoint: GET /api/modelmanager/v3/modelregistry/modelversions

update_model_version_patch¶

Update an existing model version.

Endpoint: PATCH /api/modelmanager/v3/modelregistry/modelversions/{version_id}

Request body (partial):

{
  "description": "Updated version description",
  "customProperties": {
    "accuracy": { "string_value": "0.95" },
    "framework": { "string_value": "tensorflow" }
  }
}

delete_model_version_delete¶

Delete (soft-delete / archive) a model version.

Endpoint: DELETE /api/modelmanager/v3/modelregistry/modelversions/{version_id}

compare_model_versions_post¶

Compare two or more model versions using their custom properties.

Endpoint: POST /api/modelmanager/v3/modelregistry/modelversions/compare

All version IDs must belong to the same registered model.

Request body:

{
  "modelVersionIds": ["version-id-1", "version-id-2", "version-id-3"]
}

Model Registry - Model Artifacts¶

list_model_artifacts_get¶

List artifacts for a model version.

Endpoint: GET /api/modelmanager/v3/modelregistry/modelversions/{version_id}/artifacts

upsert_model_artifact_post¶

Create or update a model artifact for a version.

Endpoint: POST /api/modelmanager/v3/modelregistry/modelversions/{version_id}/artifacts

Request body:

{
  "name": "model.pkl",
  "uri": "s3://bucket/models/model.pkl",
  "artifactType": "model-artifact",
  "storageKey": "my-storage-key",
  "storagePath": "s3://bucket/models/model.pkl",
  "resources": { "cpu": "1", "memory": "1Gi" },
  "format": "sklearn",
  "description": "Trained scikit-learn classifier",
  "customProperties": {
    "priority": { "string_value": "medium" }
  }
}

get_model_artifact_by_id_get¶

Get a model artifact by its ID.

Endpoint: GET /api/modelmanager/v3/modelregistry/modelartifacts/{artifact_id}

update_model_artifact_patch¶

Update an existing model artifact (partial update).

Endpoint: PATCH /api/modelmanager/v3/modelregistry/modelartifacts/{artifact_id}

Request body (example: update description):

{
  "description": "Updated artifact description"
}

Request body (example: update custom properties):

{
  "customProperties": {
    "format": { "string_value": "onnx" },
    "size_mb": { "string_value": "25" }
  }
}

delete_model_artifact_delete¶

Delete a model artifact.

Endpoint: DELETE /api/modelmanager/v3/modelregistry/modelartifacts/{artifact_id}

Model Deployment¶

register_model_version_artifact_post¶

Register a model, version, and artifact in a single atomic API call.

Endpoint: POST /api/modelmanager/v3/modelregistry/register

Request body:

{
  "model_data": {
    "name": "my-model",
    "description": "A machine learning model",
    "origin": "Predict"
  },
  "model_version_data": {
    "name": "v1.0.0",
    "description": "First release"
  },
  "model_artifact_data": {
    "name": "model.pkl",
    "artifactType": "model-artifact",
    "modelFormatName": "sklearn",
    "storagePath": "s3://bucket/models/model.pkl",
    "resources": { "cpu": "1", "memory": "1Gi" }
  }
}

Field Requirements:

model_data fields:

model_version_data fields:

model_artifact_data fields:

deploy_model_from_version_post¶

Deploy a model directly from the registry. The server automatically extracts resource requirements, format, and storage path from the artifact.

Endpoint: POST /api/modelmanager/v3/modelregistry/{model_id}/version/{version_id}/deploy

Model Servers¶

modelServerListGet¶

List all model servers with optional filtering and pagination.

Endpoint: GET /api/modelmanager/v3/modelservers

modelServerCreate¶

Create a new model server.

Endpoint: POST /api/modelmanager/v3/modelservers

Example - sklearn model:

{
  "name": "my-model-server",
  "model": {
    "storagePath": "s3://bucket/models/model.pkl",
    "format": "sklearn"
  },
  "resources": { "cpu": "1", "memory": "1Gi" }
}

Example - TensorFlow model with auto-scaling:

{
  "name": "my-scaled-server",
  "model": {
    "storagePath": "s3://bucket/models/model.h5",
    "format": "tensorflow"
  },
  "resources": { "cpu": "2", "memory": "4Gi" },
  "scaling": { "minReplicas": 1, "maxReplicas": 3 }
}

modelServerIdGet¶

Get details for a specific model server.

Endpoint: GET /api/modelmanager/v3/modelservers/{id}

modelServerIdGetStatus¶

Get the status and conditions of a model server.

Endpoint: GET /api/modelmanager/v3/modelservers/{id}/status

Possible states include: Loading, Loaded, Failed, Terminating.

modelServerReplace¶

Replace a model server's entire configuration (full update).

Endpoint: PUT /api/modelmanager/v3/modelservers/{id}

Request body: A complete InferenceService definition (same structure as create).

modelServerIdPatch¶

Update a model server using JSON Patch operations (RFC 6902).

Endpoint: PATCH /api/modelmanager/v3/modelservers/{id}

Example - update scaling:

{
  "ops": [
    { "op": "replace", "path": "/scaling/minReplicas", "value": 2 },
    { "op": "replace", "path": "/scaling/maxReplicas", "value": 5 }
  ]
}

Example - update resource allocation:

{
  "ops": [
    { "op": "replace", "path": "/resources/cpu", "value": "4" },
    { "op": "replace", "path": "/resources/memory", "value": "8Gi" }
  ]
}

Example - swap model binary:

{
  "ops": [
    { "op": "replace", "path": "/model/storagePath", "value": "s3://bucket/models/model-v2.pkl" }
  ]
}

modelServerIdDelete¶

Delete a model server (removes all revisions and pods). This action is not immediate.

Endpoint: DELETE /api/modelmanager/v3/modelservers/{id}

IoT Time Series¶

retrieveTimeseries¶

Retrieve time series data for a specific asset and aspect combination.

Endpoint: GET /api/iottimeseries/v3/timeseries/{assetId}/{aspectName}

Note: latestValue=true cannot be combined with from, to, or limit.

Example: Get the last 100 temperature readings for an asset:

{
  "assetId": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "aspectName": "TemperatureSensors",
  "sort": "desc",
  "limit": 100,
  "select": "temperature"
}

retrieveAggregates¶

Retrieve aggregated time series data (count, sum, average, min, max) for an asset and aspect over a given time range.

Endpoint: GET /api/iottsaggregates/v4/aggregates

Example: Get hourly average temperature over one week:

{
  "assetId": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "aspectName": "TemperatureSensors",
  "from": "2026-07-30T00:00:00Z",
  "to": "2026-08-06T00:00:00Z",
  "intervalValue": 1,
  "intervalUnit": "hour",
  "select": "temperature.average,temperature.min,temperature.max"
}

Data Lake¶

generateUploadObjectUrls¶

Generate signed URLs to upload one or more objects to the Integrated Data Lake.

Endpoint: POST /api/datalake/v3/generateUploadObjectUrls

Request body:

{
  "paths": [
    { "path": "myfolder/mysubfolder/model.pkl" }
  ]
}

Response includes objectUrls[].signedUrl and objectUrls[].path.

generateDownloadObjectUrls¶

Generate a signed URL to download a single object from the Integrated Data Lake.

Endpoint: POST /api/datalake/v3/generateDownloadObjectUrls

Only one path per request is allowed.

Request body:

{
  "paths": [
    { "path": "myfolder/mysubfolder/model.pkl" }
  ]
}

Response includes objectUrls[].signedUrl and objectUrls[].path.

Common Workflows¶

Register a Model End-to-End (Single Call)¶

Use the atomic registration endpoint to create model + version + artifact in one step:

Tool: register_model_version_artifact_post
Body:
{
  "model_data": { "name": "iris-classifier", "description": "Iris flower classifier", "origin": "Predict" },
  "model_version_data": { "name": "v1.0.0", "description": "Initial release" },
  "model_artifact_data": {
    "name": "model.pkl",
    "artifactType": "model-artifact",
    "modelFormatName": "sklearn",
    "storagePath": "models/iris-classifier/v1/model.pkl",
    "resources": { "cpu": "1", "memory": "512Mi" }
  }
}

Register a Model Step-by-Step¶

1. Create model: create_registered_model_post
2. Create version: create_model_version_post (pass model_id)
3. Upload artifact binary (optional - use generateUploadObjectUrls to get a signed URL)
4. Register artifact: upsert_model_artifact_post (pass version_id)

Deploy a Model for Inference¶

Option A - Direct deploy from registry:

Tool: deploy_model_from_version_post
Parameters: model_id=<id>, version_id=<id>

Option B - Manual model server creation:

Tool: modelServerCreate
Body: { "name": "iris-server", "model": { "storagePath": "...", "format": "sklearn" }, "resources": { "cpu": "1", "memory": "512Mi" } }

Then check the server state:

Tool: modelServerIdGetStatus
Parameters: id=<server-id>

Wait until state is Loaded, then run inference:

Tool: run_inference
Parameters: model_id=<server-id>
Body: { "inputs": [{ "name": "input-0", "data": [5.1, 3.5, 1.4, 0.2], "datatype": "FP64", "shape": [1, 4] }] }

Compare Model Versions¶

After training multiple versions of the same model, compare their custom properties:

Tool: compare_model_versions_post
Body: { "modelVersionIds": ["<version-id-A>", "<version-id-B>"] }

Retrieve IoT Sensor Data for Inference Input¶

Fetch recent sensor readings and feed them into the model:

Tool: retrieveTimeseries
Parameters: assetId=<32-char-hex>, aspectName=TemperatureSensors, limit=10, sort=desc

Response Format¶

Every tool call returns one or more text content blocks:

Example success response:

HTTP 200
{
  "id": "abc123",
  "name": "iris-classifier",
  ...
}

Example error response:

HTTP 404
{
  "error": "Not Found",
  "message": "Model with id 'xyz' not found"
}

Tip: When updating a model server with modelServerIdPatch, save the returned ETag and pass it as the etag parameter in subsequent PATCH calls for optimistic concurrency control.

Troubleshooting¶

Server fails to start with "must be set" error¶

All required environment variables must be present. Check your .env file or MCP client env block and ensure every required variable listed in Required Settings (All Modes) is defined and non-empty.

"Auth failed" or HTTP 401 responses¶

• Verify MODEL_MANAGER_CLIENT_ID and MODEL_MANAGER_CLIENT_SECRET are correct.
• Verify MODEL_MANAGER_TOKEN_URL points to the correct Insights Hub Technical Token Manager endpoint for your region.
• Verify MODEL_MANAGER_TENANT matches your tenant's ID exactly (case-sensitive).
• Use auth_getToken to manually test the token acquisition.

HTTP 403 responses¶

The OAuth2 client credentials may lack the required scopes or role assignments for the requested operation. Contact your Insights Hub tenant administrator to verify permissions.

HTTP 404 responses¶

Ensure the IDs (model_id, version_id, artifact_id, etc.) are correct and belong to your configured tenant. IDs are UUIDs and are case-sensitive.

SSE mode not starting¶

• Confirm starlette and uvicorn are installed (they are bundled in the wheel).
• Confirm MCP_HOST and MCP_PORT are set.
• Check that the port is not already in use.

MCP client cannot find model-manager-mcp command¶

If the virtual environment is not on the system PATH, use the absolute path to the executable in your MCP client configuration:

"command": "C:\\Users\\you\\my-project\\.venv\\Scripts\\model-manager-mcp.exe"

Large responses are truncated¶

API responses are capped at 50,000 characters. If you need the full response, use pageSize / limit parameters to retrieve smaller result sets, or use nextPageToken to paginate through results.

Documentation version: 1.0 - Insights Hub Model Manager MCP Server v1.0.0