Eldric Docs 5.0.215 ← eldric.ai
Inference

Forecasting from other tools (MCP)

How-to · Developers and administrators · Applies to 5.0.211

An external agent or tool can ask Eldric's forecaster over MCP. The edge serves an MCP server at POST /mcp/forecast with eight tools. This page shows what you need before you connect, how to connect, and what the answers and refusals look like.

Before you connect

  • A key of a non-administrator. Use the API key of a viewer or developer. Every user finds theirs in the chat, in the user menu under API keys. An administrator's or superadmin's key is refused with 403 admin_credential_not_allowed, so that an admin key never drives an external surface.
  • Forecasting in the licence. Without it every tool call answers feature_not_licensed.
  • Forecasting switched on for the tenant. From 5.0.210 the switch is per tenant. The tenant default has it on until an administrator stores a setting for it; every other tenant has it off until an administrator turns it on, in the admin console under Tenant Features (Forecasting & hazard) or with PUT /api/v1/tenants/<tenant>/features. A tenant without it gets forecast_not_enabled_for_tenant on every forecast tool.
  • Room in the tenant's forecast quota. From 5.0.211 an administrator can limit how much a tenant forecasts each month and how many streams it may hold open. There is no limit until one is set. See the forecast quota.
  • A node with sign-in switched on. On a node where authentication is off, the server answers 403 mcp_requires_user_auth.

Connecting

Point your MCP client at https://<your edge>/mcp/forecast and send the key as X-API-Key or as Authorization: Bearer <key>. The server speaks JSON-RPC 2.0, one message per POST; a batch is refused. It accepts the protocol versions 2025-06-18 and 2025-03-26 and calls itself eldric-forecast. A request without a key gets 401 before any JSON-RPC is read.

This path is not /api/v1/mcp. That one is the admin side of Eldric's own MCP client, for servers Eldric calls.

A first exchange by hand:

curl -s https://<your edge>/mcp/forecast \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}'

curl -s https://<your edge>/mcp/forecast \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

tools/list returns the eight tools with a description and an input schema each. A notification, such as notifications/initialized, is answered with 202 and runs nothing.

The tools

Each tool call is one call to a forecast route, made as you, so the route's own checks apply.

ToolWhat it does
forecastForecasts one series sent in the call. Needs model and series; optional horizon, quantiles, covariates and actual for an anomaly score per step.
forecast_by_referenceForecasts from a file you own (CSV, XLSX or ODS), named by its artifact id. Only your own files can be read.
stream_startOpens a stream on a model with a first history and returns a stream_id.
stream_appendAdds new observed values to a stream.
stream_forecastForecasts from a stream, from its running state (mode: "stream") or over the whole history (mode: "exact").
stream_closeCloses one of your streams.
limitsThe limits of the node that answered and the models it serves; see below.
model_infoThe limits of one model.

A stream belongs to the person whose key opened it. It lives in the memory of the node that opened it and ends when that node restarts or after its idle time. Another person's stream answers not-found, exactly like an unknown id.

What limits returns

Take the model name for every other tool from here. limits returns:

  • target_seconds, the time budget for one exact call, and ttl_seconds, how long an idle stream lives;
  • own_open_streams, the number of streams you have open (the node-wide counts are not shown to an MCP caller);
  • models, one entry per model, with max_points (the longest history), recommended_points, max_steps (the trained horizon), max_horizon (the longest horizon accepted; steps past max_steps are untrained extrapolation), quantile_levels, whether calendar inputs and covariates are used, and whether the model was trained to stream.

From 5.0.210 the node's configured forecast model is listed straight after a restart. Before, the list stayed empty until someone ran a forecast. A model that fails to load is not listed. The limits are node-wide, and another call may reach another node. Changing them is an admin action and not a tool.

Ask for quantiles only at levels in quantile_levels. A level that is not on the model's grid is refused with the list of levels; nothing is interpolated.

Refusals

The first four answers below are HTTP answers to the POST itself. Everything after that is a tool result marked isError: the route's own body, unchanged, with its HTTP status in _meta.http_status. Nothing falls back to another model or to a default limit. An argument the tool does not take is refused as a JSON-RPC error (-32602) before any route is called.

AnswerWhy
401No key, or a key the cluster does not know.
403 admin_credential_not_allowedThe key belongs to an administrator or superadmin.
403 mcp_requires_user_authThe node does not enforce sign-in, or the call came from another node rather than a user.
413 payload_too_largeOne message is larger than 8 MB.
429 tenant_rate_limitedYour tenant has sent more requests this minute than its limit allows (bucket forecast, the same per-minute limit as chat). The body says retry_after_ms.
feature_not_licensed (tool result)Forecasting is not in the cluster's licence.
forecast_not_enabled_for_tenant (tool result)Forecasting is not switched on for your tenant.
forecast_quota_exceeded (tool result, status 429)Your tenant has reached its forecast quota. unit says which part: points_x_horizon for the month's amount, with resets_at, or open_streams; close a stream with stream_close or let an idle one expire. retry_after_s says how long to wait.
forecast_quota_unknown (tool result, status 503)Your tenant has a quota, and how much of it is used could not be read just now. Retry after retry_after_s.
model_not_found (tool result)model_info was asked for a model that limits does not list.
forecaster_unreachable (tool result)No forecasting node could be reached for this call.
stream_unreachable (tool result)The stream is on a node the edge cannot reach right now. It may still exist; retry later.
status 503 (tool result)The node is busy. The HTTP answer carries Retry-After; retry after that time. The server does not retry by itself.

What is recorded

From 5.0.210 each tool call that reaches a forecast tool is recorded as a task episode with the surface mcp. It holds the tool, its settings and counts such as how many points were sent, never the values of the series, the covariates or a reference. A refused call is recorded as failed with its refusal code. A malformed request is not recorded, and nothing is when the tenant has auto_record off. See Task episodes.