Use the time-series MCP server#

The optional Model Context Protocol (MCP) server exposes wind-turbine analytics to MCP clients. It uses Python/FastMCP and Streamable HTTP through the existing HTTPS gateway. Grafana and the sensor ingestion paths remain unchanged.

Prerequisites#

  • Complete the Get Started prerequisites.

  • Use Python 3.12 or later for the example client.

  • Set the existing database and Grafana credentials.

  • Set HOST_IP to the gateway’s IPv4 address.

  • Use an analytics image with /config, /udfs/package, the native Kapacitor task API, and a /stop_pipeline endpoint that shuts down the Kapacitor daemon.

The server uses Kapacitor directly for running-task status and the microservice’s /stop_pipeline endpoint for complete shutdown. Images whose stop endpoint only disables a task must be rebuilt with complete daemon shutdown support, together with the MCP image. The server verifies daemon shutdown before reporting success.

Deploy#

Caution

Deployment targets stop the existing stack and remove its volumes. Use them only on a deployment that you intend to replace.

  1. Set MCP credentials in the same shell:

    Set MCP_USERNAME and MCP_PASSWORD in .env:

    MCP_USERNAME=mcpuser
    MCP_PASSWORD=<your-password>
    

    The username must contain only alphabets and be at least 5 characters long. The password must be at least 10 alphanumeric characters with at least one letter and one digit. make check_env_variables MCP=true validates both values. Never commit credentials.

  2. Build the server:

    make build
    

    The MCP image is built locally; a published MCP image is not required. Runtime package versions are pinned in mcp-server/requirements.txt, but transitive dependencies are not hash-locked. DOCKER_REGISTRY and TIME_SERIES_MCP_IMAGE control its registry and repository. Its default tag is 2026.1.0.

  3. Select one ingestion path:

    make up_mqtt_ingestion MCP=true
    # Or:
    make up_opcua_ingestion MCP=true
    

    Analytics waits for start_pipeline; these commands do not upload or activate the UDF. Without MCP=true, both commands retain automatic analytics startup.

  4. For batch processing, append batch during deployment:

    make up_mqtt_ingestion batch MCP=true
    

    The server selects the batch UDF and creates its model alias inside the upload archive. It does not modify application assets. Batch results use a 20-minute window.

INCLUDE=validation retains its existing behavior with MCP. The num_of_streams parameter is not supported. System metrics remain available in Grafana when collected; this MCP version does not expose host metrics.

Trust the gateway certificate#

All MCP requests require Basic authentication over verified HTTPS, including initialization and discovery. There is no insecure client option.

The local gateway creates a self-signed certificate with localhost and HOST_IP subject alternative names. Obtain this certificate through a trusted local connection:

docker exec nginx_proxy cat /opt/nginx/certs/cert.pem > ./mcp-gateway-ca.pem
export MCP_CA_FILE="$PWD/mcp-gateway-ca.pem"
export MCP_URL="https://127.0.0.1:3000/mcp"

Replace the address and port with the configured HOST_IP and GRAFANA_PORT. Store the certificate outside version control. The gateway regenerates its certificate on restart; obtain the new certificate after a restart. For production, provision an organization-trusted certificate and key instead of the local certificate-generation step.

Use the example client#

The client reads MCP_USERNAME, MCP_PASSWORD, HOST_IP, and GRAFANA_PORT from the component .env and connects to https://HOST_IP:GRAFANA_PORT/mcp by default. Environment variables, including MCP_URL and MCP_CA_FILE, override values from .env. Run the client with --help to see all options; --url overrides MCP_URL and --ca-file overrides MCP_CA_FILE.

From the component root:

python3 -m venv mcp-server/example/.venv
mcp-server/example/.venv/bin/pip install -r mcp-server/example/requirements.txt
mcp-server/example/.venv/bin/python mcp-server/example/example_client.py describe
mcp-server/example/.venv/bin/python mcp-server/example/example_client.py get_pipeline_status
mcp-server/example/.venv/bin/python mcp-server/example/example_client.py start_pipeline \
  --arguments '{"time_series_inf_device":"CPU"}'
mcp-server/example/.venv/bin/python mcp-server/example/example_client.py list_insights_data \
  --arguments '{"severity":"anomaly","page":1,"page_size":20}'
mcp-server/example/.venv/bin/python mcp-server/example/example_client.py get_anomaly_summary
mcp-server/example/.venv/bin/python mcp-server/example/example_client.py get_processing_metrics
mcp-server/example/.venv/bin/python mcp-server/example/example_client.py list_sources
mcp-server/example/.venv/bin/python mcp-server/example/example_client.py stop_pipeline

GPU is also supported by start_pipeline when the analytics container has suitable hardware. The MCP container itself does not require a GPU. Device changes retain the active alert configuration. The server rejects control requests when a different UDF task is configured.

Caution

stop_pipeline disables analytics only. Sensor ingestion and containers continue running. Streaming input received while analytics is disabled is not replayed automatically. One-shot simulators can exhaust their input before analytics starts; use continuous ingestion for interactive demonstrations.

Tool data contract#

Tool

Result

describe

Tools, schemas, processing mode, classification codes, and operational guidance

get_pipeline_status

Daemon health and selected task state, including not_configured and stopped

start_pipeline

Verified enabled state, selected device, and change indicator

stop_pipeline

Verified daemon shutdown (stopped) or an explicit unconfigured state

list_sources

Paginated source identifiers observed in the requested time window

list_insights_data

Paginated points, classification, analysis flag, and timing values in seconds

get_anomaly_summary

Processed, analysed, unanalysed, anomalous, and per-severity counts

get_processing_metrics

Counts, window-average rates, mean latencies, and last-observed timestamps

Data tools accept start_time and end_time as timezone-aware timestamps. The default window covers the preceding 30 minutes; the maximum window is 24 hours. The start is inclusive and the end is exclusive. Use an explicit, fixed window while paging through results. List tools accept page and page_size, with at most 100 entries per page. They return has_more and next_page, not an expensive unrestricted total count. Point, summary, and metrics tools support an exact source filter. Use list_sources to find valid identifiers, then pass one as --arguments '{"source":"<source-id>"}'. Without a filter, results cover all sources, and the window object in the response omits source; it appears there only when a filter was applied. Source identifiers support up to 128 letters, digits, underscores, dots, colons, and hyphens. list_insights_data supports all, anomaly, normal, low, medium, and high severity filters.

Classification codes are 0, 0.3, 0.6, and 1.0; they are not confidence scores. The analysis flag distinguishes unanalysed points from analysed points. Anomaly percentage uses analysed points as its denominator. Missing timing values and percentages without analysed points are null, not zero. Rates divide retained point counts by the requested window duration in minutes. They differ from Grafana’s fixed three-minute rolling queries. Counts cannot include expired data; the stack defaults to one-hour retention.

The server does not expose arbitrary InfluxQL, uploads from clients, shell commands, vision, fusion, or LLM explanations. Database and analytics errors are explicit, sanitized tool failures. Partial startup failures identify the completed deployment stages. The existing database user has broad privileges; provision a separate read-only database identity for MCP when deployment policy requires it.

Validate and stop#

make status MCP=true
make down MCP=true

Use MCP=true consistently for deployment, status, and shutdown. The server port is internal; only nginx exposes /mcp. Its internal /health endpoint provides liveness and does not require credentials. Browser origins must match the configured HTTPS gateway origin.