MCP server

The remote server at https://mcp.spavik.co uses stateless Streamable HTTP. There is nothing to install on the server side. Your MCP client must support a custom HTTP header.

ConnectCopy Anchor Link

Send your Spavik API key as X-Spavik-Api-Key:

X-Spavik-Api-Key: sk-spv-api-...

For Claude Code, keep the key in the environment:

export SPAVIK_API_KEY="sk-spv-api-..."
claude mcp add --transport http spavik https://mcp.spavik.co \
  --header "X-Spavik-Api-Key: $SPAVIK_API_KEY"

For another client, configure the server URL and the same header. Use its secret input or environment-variable support.

Discovery, prompts and the preparation guide are public. For tools and resources that call the API, the MCP forwards only the incoming X-Spavik-Api-Key, unchanged. Authorization is ignored and is never converted into an API key. The API alone checks credentials, permissions and quotas on the requested operation.

The client and its credentials live only for the HTTP request. There is no preliminary key check, credential cache, server-key fallback or OAuth flow. API refusals become MCP tool errors (isError: true) or resource errors.

Prepare before evaluatingCopy Anchor Link

Start from the business decision and authorized data sources. The agent uses its own connectors to read APIs, files or databases; this MCP has no source connectors. prepare_data and spavik://preparation guide source inspection, field availability, joins, leakage prevention and a reproducible recipe.

Choose classification, regression or forecasting from the decision, not merely from the presence of dates. A future quantity can also use regression when its explanatory features are available at the requested horizon. Explain any unverified temporal or group evaluation requirements.

The twelve toolsCopy Anchor Link

Billable tools describe their pricing. Read account_usage for the available balance before a billable call. Cost estimation is unavailable; legacy dry_run: true requests are rejected without sending a prediction or forecast.

Data and parametersCopy Anchor Link

Pass file content in data: CSV with a header row or a JSON array of objects serialized as a string. The remote server cannot read paths on your machine. predict and submit_outcomes also accept up to 50 objects inline in rows and outcomes respectively.

• evaluate_data: data, target, optional engine_family.
• train_model: data, target, optional name, engine_family, auto_update. The API selects its configured default family when omitted. Keep the returned model ID and feature columns for prediction.
• predict: model_id, rows or data, optional engine_version within the model's family. The response identifies the exact serving engine.
• backtest_forecast: data, target, optional horizon (default 1), timestamp, item_id, point_estimate, quantiles, engine_family, engine_version and include_backtest_predictions.
• forecast: the same series options and a required horizon, with optional backtest. include_backtest_predictions requires backtest: true. point_estimate is mean by default or median.
• submit_outcomes: model_id, and outcomes or data. Each outcome has actual and the full features. request_id is optional correlation metadata. Add prediction, version and exact engine for performance measurement.
• list_models: archived, limit (1 to 50) and offset (at least 0). Follow pagination.next_offset until null. Set archived: true to find models that can be restored.

For more than 50 outcomes, send a JSON array as text in data, preserving nested features and probabilities. The API accepts up to 1000 outcomes per batch. CSV is not suitable for these nested objects.

Keep horizon, point estimate, quantiles, prepared history and column roles consistent between backtest and forecast. Monthly timestamps must be month-start or month-end. All series must share frequency and calendar anchor, evaluated in UTC. Do not silently shift dates or invent missing observations.

Read the resultsCopy Anchor Link

Evaluation returns structural validation and the API's assessment unchanged. A better comparison on this sample does not prove future reliability. See Read an evaluation for the statuses, random-holdout limits, MASE weighting, observation counts and exclusions.

model_performance presents observed.assessment and preserves the full API report, including complementary metrics, baselines, per-class and per-version results, undefined reasons and training context. No matched outcomes means no comparison yet. The MCP does not calculate scores or replace the API conclusion.

Keep each input row and prediction, including version and engine, to report its observed outcome later. Every outcome requires features and actual. submit_outcomes returns refresh_triggered; if true, automatic integration has already started. Do not request a duplicate refresh. A refresh can report incomplete_outcomes when some submitted feature rows were incomplete.

Structured results and safe recoveryCopy Anchor Link

Starting with MCP server 0.2.0, every tool publishes an outputSchema and returns business fields in structuredContent.data. Read structuredContent.data.assessment for an evaluation, or structuredContent.data.predictions, .version and .engine after scoring. The human-readable text remains in content for existing clients.

The common envelope also contains error, request_id, idempotency_key, idempotent_replay, predictions_remaining and cost. Success has error: null. predictions_remaining copies the API's X-Spavik-Predictions-Remaining header (monthly allowance left plus credit balance); null means not reported. A tool failure sets MCP isError: true, data: null and an error with code, message, http_status, retryable, retry_after_seconds and outcome_unknown. Unknown values remain null; an unknown cost is not zero.

Five mutation tools accept idempotency_key: train_model, predict, forecast, submit_outcomes and refresh_model. archive_model and restore_model reach the same state however often they run, so simply repeat them. Generate a unique key and save it with the tool arguments before the first call. For example, these are the arguments for a one-row prediction:

{
  "model_id": "mdl_your_model",
  "rows": [{"plan": "pro", "seats": 12, "tickets_90d": 3}],
  "idempotency_key": "019a00b7-28f6-7000-8000-000000000001"
}

Use a real model ID and a new key for your own operation. If the response is lost, reuse the same key and arguments with the same workspace credentials. The API can replay completed responses for 24 hours by default, measured from operation creation; an expired completed key can execute and charge again. Respect retry_after_seconds and stop when error.retryable is false. REQUEST_INTERRUPTED and IDEMPOTENCY_RESPONSE_UNAVAILABLE require inspection; never create another key to force execution. Keep the request ID for support.

A successful replay has idempotent_replay: true. The MCP exposes no separate operation-status lookup. If the key is omitted, it generates one for its internal retries, but a client that loses the entire response cannot recover that generated key. Supplying it beforehand prevents that gap.

Server versionsCopy Anchor Link

Read serverInfo.version from initialize, or version from https://mcp.spavik.co/health, to identify the release available on the endpoint you use. protocolVersion identifies the separately negotiated MCP protocol.

Version 0.2.0 replaces the former structuredContent.result string with the data object and result envelope. Update consumers of that structured field; text consumers can keep reading content. The current tool surface has twelve tools: prediction_history has been removed for every plan. Preserve inputs and results in your application, including model version and exact engine.

Version 0.3.0 renames the envelope field credits_remaining to predictions_remaining, after the header it copies. Clients reading the old name must switch; the value is unchanged.

Resources and promptsCopy Anchor Link

The four prompts are prepare_data, build_model, score_rows and close_the_loop. Essential guidance also appears in the server instructions and tool descriptions for clients with limited resource or prompt support.

Model lifecycleCopy Anchor Link

Archive a model to free an active-model slot while keeping its artifacts. Restore it when needed; restoration takes a slot again. Account deletion, permanent model deletion, key management, billing, administration and webhooks are outside this MCP's tool surface.