Ephemeris Time-Series Forecasting
Probabilistic time-series forecasts from zero-shot foundation models: routed, single or ensembled.
Should I use this
Quality & Safety
Based on automated analysis of tool definitions and protocol compliance.
Context Cost
This is the approximate number of tokens consumed each time the server's tools are loaded into a model's context. Higher counts reduce the attention available for other tasks.
Install
One-Click Install
Add this to your `claude_desktop_config.json` file:
{
"mcpServers": {
"ephemeris": {
"command": "npx",
"args": [
"ephemeris-mcp"
]
}
}
}Runnable packages
1.0.0stdioRemote endpoints
https://ephemeris.cascade.industries/api/mcpstreamable-httpWhat it can do
Tool inventory
Tools (7)
🟢get_version
Read this deployed MCP server's version, nullable build commit and supported saved forecast schema versions. Call with {}. No API key, account access, inference, charges or writes; network access to this server only. Returns component, version, build_commit (full source SHA or null when unavailable), and artifact_schema_versions. Unknown commit stays null. Server, CLI, npm bridge and artifact schema versions are independent; this tool cannot inspect local installations, check the latest registry release or establish model quality. Use list_models for live model capabilities. After a connection failure reconnect and retry; no forecast could have been submitted by this tool.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}Output Schema
{
"type": "object",
"properties": {
"component": {
"type": "string",
"const": "ephemeris-mcp-server"
},
"version": {
"type": "string"
},
"build_commit": {
"anyOf": [
{
"type": "string",
"pattern": "^[a-f0-9]{40}$"
},
{
"type": "null"
}
]
},
"artifact_schema_versions": {
"type": "object",
"properties": {
"ephemeris.forecast": {
"type": "array",
"items": {
"type": "string",
"const": "1"
}
}
},
"required": [
"ephemeris.forecast"
],
"additionalProperties": false
}
},
"required": [
"component",
"version",
"build_commit",
"artifact_schema_versions"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}🟢describe_forecast(artifact, series_index, variate_index)
Deterministic calculations from a complete ephemeris.forecast v1 artifact object, including CLI artifacts. No inference or forecast charge; this hosted tool still receives data over the network. Returns scope, result, basis, limitations and source pointers: last-observed baseline, median endpoint/change, marginal-median aggregates, and exact saved billing units. Missing medians/context remain unknown. Sum of medians only for period_total; it is not a cumulative-distribution interval or median. No calibrated coverage, causal explanation, path/peak probability, or business action is inferred. Example: pass {artifact: <forecast result artifact>}; choose series_index/variate_index for multiple results. Maximum 1 MiB; malformed/version/shape errors are recoverable by fixing the artifact or using CLI, never rerunning inference. Missing labels may be corrected in a COPY of context without changing request/response. No filesystem access, URL fetches, persistent storage, Gnomon import, or scoring.
Input Schema
{
"type": "object",
"properties": {
"artifact": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {},
"description": "Complete ephemeris.forecast schema_version 1 JSON object returned by forecast or saved by Ephemeris CLI. Pass the object, not a filename, URL, resource URI, request ID, or bearer token. Maximum 1 MiB UTF-8 JSON. Contains submitted history; send only data you are authorized to process on this hosted server."
},
"series_index": {
"description": "Zero-based series index; required when the artifact has multiple series, otherwise 0.",
"type": "integer",
"minimum": 0,
"maximum": 63
},
"variate_index": {
"description": "Zero-based variate index; required for multivariate results, otherwise 0.",
"type": "integer",
"minimum": 0,
"maximum": 255
}
},
"required": [
"artifact"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}Output Schema
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": {}
}🟢plot_forecast(artifact, series_index, variate_index, format, history, ...)
Render a complete ephemeris.forecast v1 artifact object as PNG (default inline preview) or SVG (embedded resource to save). No inference or forecast charge; hosted processing receives the artifact over the network. Example: {artifact: <saved artifact>, format: png}. Requires returned q0.5; never invents a median. Observed history, forecast boundary, median and nominal quantile bands are labeled. Default history view is most recent max(24, 2*horizon) points, capped by available history; history: all shows all. Dates only when supported by recorded metadata, otherwise sampling steps. Bands do not establish calibrated coverage; missing/crossed points are omitted and counted. Maximum 1 MiB input. Select series_index/variate_index for multiple results. Fix argument/shape errors without rerunning inference. User-supplied labels can be corrected in a COPY of artifact context offline; no new forecast needed. Client decides preview/download UI. URNs identify attached bytes, not hosted URLs; no filesystem access, URL fetching or persistent storage.
Input Schema
{
"type": "object",
"properties": {
"artifact": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {},
"description": "Complete ephemeris.forecast schema_version 1 JSON object returned by forecast or saved by Ephemeris CLI. Pass the object, not a filename, URL, resource URI, request ID, or bearer token. Maximum 1 MiB UTF-8 JSON. Contains submitted history; send only data you are authorized to process on this hosted server."
},
"series_index": {
"description": "Zero-based series index; required when the artifact has multiple series, otherwise 0.",
"type": "integer",
"minimum": 0,
"maximum": 63
},
"variate_index": {
"description": "Zero-based variate index; required for multivariate results, otherwise 0.",
"type": "integer",
"minimum": 0,
"maximum": 255
},
"format": {
"default": "png",
"description": "png returns an inline image preview; svg returns an embedded text resource to save as .svg. Neither creates a hosted download URL.",
"type": "string",
"enum": [
"png",
"svg"
]
},
"history": {
"description": "Observed points to show: default min(available, max(24, 2*horizon)). all shows full history. View changes never change the artifact or inference.",
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 100000
},
{
"type": "string",
"const": "all"
}
]
},
"lower": {
"description": "Existing lower quantile. Supply together with upper. Default pairs complementary available levels.",
"type": "number",
"exclusiveMinimum": 0,
"exclusiveMaximum": 1
},
"upper": {
"description": "Existing upper quantile, greater than lower. Supply together with lower.",
"type": "number",
"exclusiveMinimum": 0,
"exclusiveMaximum": 1
}
},
"required": [
"artifact"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}Output Schema
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": {}
}🟡forecast(context, include_artifact, mode, model, series, ...)
Submit numeric observations to forecast future sampling steps. Spends credits on successful calls. Choose and retain idempotency_key before submitting; no automatic retries, replay depends on server retention. Minimal example: {mode: route, series: [{values: [10,12,11], freq: D}], horizon: 2, quantiles: [0.1,0.5,0.9]}. Returns forecasts and meta as before, plus artifact by default for describe_forecast/plot_forecast. Save the embedded JSON attachment: it includes full input history and local context; no hosted storage is created. Context never becomes a model input. Billing is at meta.billing in millicredit strings (100 mc = 0.1 credits). Missing future inputs mean not supplied, not no events. Quantile bands do not establish coverage, cumulative intervals or peak probabilities. After uncertain completion, reuse the same key and API request; an expired key may cause a new charge.
Input Schema
{
"type": "object",
"properties": {
"context": {
"type": "object",
"properties": {
"series": {
"maxItems": 64,
"type": "array",
"items": {
"type": "object",
"properties": {
"series_id": {
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
]
},
"unit": {
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
]
},
"timezone": {
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
]
},
"target_description": {
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
]
},
"measurement": {
"anyOf": [
{
"type": "string",
"enum": [
"period_total",
"period_average",
"point_in_time"
]
},
{
"type": "null"
}
]
},
"timestamps": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"maxLength": 100
}
},
{
"type": "null"
}
]
},
"future_timestamps": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"maxLength": 100
}
},
{
"type": "null"
}
]
},
"source_available_at": {
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
]
},
"recorded_as_of": {
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
]
},
"future_covariate_roles": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string",
"enum": [
"known_future",
"scenario_assumption",
"unspecified"
]
}
}
},
"additionalProperties": false
}
},
"scenario_assumptions": {
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"maxLength": 2000
}
}
},
"required": [
"series"
],
"additionalProperties": false,
"description": "Local artifact metadata, never sent as model inputs. series aligns with input series; timestamps align with history and future_timestamps with horizon. Units/target/measurement/timezone must come from the user; unknowns stay null. Future-input labels are caller assertions; narrative assumptions do not change inference."
},
"include_artifact": {
"description": "Default true: include a portable ephemeris.forecast v1 artifact and embedded JSON attachment (up to 1 MiB), with full input history. Save it client-side for describe_forecast/plot_forecast or the CLI. false returns the existing API response only. No persistent hosted storage is created.",
"type": "boolean"
},
"mode": {
"type": "string",
"enum": [
"route",
"ensemble",
"explicit"
],
"description": "\"route\": automatically select a model. \"ensemble\": blend compatible models and may cost more. Neither guarantees accuracy or calibration. \"explicit\": run the single model named in `model`."
},
"model": {
"description": "Required when mode is \"explicit\". Must be a name returned by list_models.",
"type": "string",
"minLength": 1
},
"series": {
"minItems": 1,
"maxItems": 64,
"type": "array",
"items": {
"type": "object",
"properties": {
"values": {
"anyOf": [
{
"minItems": 1,
"type": "array",
"items": {
"type": "number"
}
},
{
"minItems": 1,
"type": "array",
"items": {
"minItems": 1,
"type": "array",
"items": {
"type": "number"
}
}
}
],
"description": "Observed history, oldest first. A flat number array is one univariate series. A nested array is one multivariate series with one inner array per variate, all the same length."
},
"freq": {
"description": "Pandas-style sampling frequency such as \"H\", \"D\", \"W\", \"15min\" or \"M\". Improves routing and seasonal handling; omit if unknown.",
"type": "string",
"minLength": 1
},
"covariates": {
"type": "object",
"properties": {
"past": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "number"
}
},
"description": "Named historical channels, each the same length as the series context."
},
"future": {
"description": "Future numeric channels (known future or explicit scenario assumptions), each exactly `horizon` long. Every future channel must also appear in `past`.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "number"
}
}
}
},
"required": [
"past"
],
"description": "Optional exogenous covariates. Only models with `covariates: true` in list_models can use them. In route and ensemble mode the panel narrows to those models; in explicit mode, naming a model without covariate support is an error."
}
},
"required": [
"values"
]
},
"description": "One to 64 series forecast in one request. All share horizon and quantiles."
},
"horizon": {
"description": "Number of future steps to forecast, 1 to 4096. Defaults to 64. Some models stop short of this (max_horizon in list_models): route and ensemble skip them, explicit mode rejects the request.",
"type": "integer",
"minimum": 1,
"maximum": 4096
},
"context_len": {
"description": "Most recent points per variate to feed the model and bill for, 1 to 16384. Defaults to 256. Values beyond the model's context cap are truncated at the cap.",
"type": "integer",
"minimum": 1,
"maximum": 16384
},
"quantiles": {
"description": "Up to 21 quantile levels strictly between 0 and 1, for example [0.1, 0.5, 0.9]. The response keys forecasts by these as decimal strings.",
"maxItems": 21,
"type": "array",
"items": {
"type": "number",
"exclusiveMinimum": 0,
"exclusiveMaximum": 1
}
},
"top_k": {
"description": "Ensemble only: cap on how many models participate.",
"type": "integer",
"minimum": 1,
"maximum": 16
},
"combine": {
"description": "Ensemble only. \"mixture\" averages the predictive distributions (default); \"vincentize\" averages the quantiles.",
"type": "string",
"enum": [
"mixture",
"vincentize"
]
},
"idempotency_key": {
"description": "Client-chosen key, 8 to 128 characters of letters, numbers, dot, underscore, colon or hyphen. A retry with the same key and identical API body replays while retained by the server. Retain the key before submission; expired keys may cause a new charge.",
"type": "string",
"pattern": "^[A-Za-z0-9._:-]{8,128}$"
}
},
"required": [
"mode",
"series"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}Output Schema
{
"type": "object",
"properties": {
"artifact": {
"description": "Portable ephemeris.forecast v1 JSON including full history and local context. Save client-side and pass the object to describe_forecast/plot_forecast. Not a hosted URL.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"artifact_status": {
"description": "included or unavailable. A packaging/size failure never discards the paid forecasts/meta response.",
"type": "string"
},
"artifact_error": {
"type": "string"
},
"forecasts": {
"description": "One entry per input series, aligned with the request.",
"type": "array",
"items": {
"type": "object",
"properties": {
"quantiles": {
"description": "Forecast values keyed by quantile level as a decimal string (\"0.5\"). A flat array of numbers for a univariate series, one inner array per variate for a multivariate one, each `horizon` long. A null marks a value the model could not produce.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {}
}
}
},
"additionalProperties": {},
"description": "One entry per input series, in request order."
}
},
"meta": {
"type": "object",
"properties": {
"gateway_request_id": {
"description": "Ephemeris request id. Quote this in support requests and usage lookups.",
"type": "string"
},
"request_id": {
"description": "Upstream model-panel request id for the forecast.",
"type": [
"string",
"null"
]
},
"upstream_request_ids": {
"description": "All upstream ids when a mixed-frequency batch was split.",
"type": "array",
"items": {
"type": "string"
}
},
"mode": {
"type": "string"
},
"models_used": {
"description": "Models whose output is in this forecast.",
"type": "array",
"items": {
"type": "string"
}
},
"model_revisions": {
"description": "Served weight revision (Hugging Face commit hash) per model in models_used. Identifies the exact weights, independent of this server's version.",
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"router_confidence": {},
"per_model_latency_ms": {},
"notes": {},
"billing": {
"type": "object",
"properties": {
"settled_mc": {
"description": "Millicredits charged for this call.",
"type": "string"
},
"balance_mc": {
"description": "Millicredits remaining after this call.",
"type": "string"
}
},
"additionalProperties": {}
}
},
"additionalProperties": {}
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": {}
}🟢list_models
Discover the model panel: each model's availability right now (healthy), capabilities (multivariate, covariates, max_horizon, auto_max_horizon), its weight in an ensemble at each horizon, pinned and actually served weight revision, price per thousand series-slots in millicredits and maximum billable context. Call this before using forecast in explicit mode; the deployed panel can differ from any documentation.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}Output Schema
{
"type": "object",
"properties": {
"models": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"healthy": {
"description": "Whether the model's worker is up and accepting forecasts right now.",
"type": "boolean"
},
"hf_repo": {
"type": [
"string",
"null"
]
},
"revision": {
"description": "Revision pinned in the panel manifest, if any.",
"type": [
"string",
"null"
]
},
"served_revision": {
"description": "Commit hash of the weights the worker actually loaded.",
"type": [
"string",
"null"
]
},
"multivariate": {
"type": "boolean"
},
"covariates": {
"type": "boolean"
},
"pools": {
"type": "array",
"items": {
"type": "string"
}
},
"max_horizon": {
"description": "Longest horizon this model can forecast; null means no limit.",
"type": [
"number",
"null"
]
},
"auto_max_horizon": {
"description": "Longest horizon at which route and ensemble use this model; null means no limit beyond max_horizon. Explicit mode may still name it up to max_horizon.",
"type": [
"number",
"null"
]
},
"ensemble_weights": {
"description": "Weight this model carries in a full-panel ensemble, keyed by horizon in steps. Absent at horizons past max_horizon or auto_max_horizon.",
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
{
"type": "null"
}
]
},
"skill_weight": {
"description": "Diagnostic feedback score. Not the ensemble's weighting; see ensemble_weights.",
"type": [
"number",
"null"
]
},
"credits": {
"type": [
"number",
"null"
]
},
"price_per_kslot_mc": {
"description": "Millicredits per thousand series-slots; null when the model is not billable.",
"type": [
"string",
"null"
]
},
"billing_context_cap": {
"description": "Most context points billed per variate; longer inputs are billed at the cap.",
"type": [
"number",
"null"
]
},
"detail": {
"type": [
"string",
"null"
]
}
},
"required": [
"name"
],
"additionalProperties": {}
}
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": {}
}🟢get_balance
Return the account's spendable credit balance in millicredits, excluding credits reserved by in-progress forecasts. 1000 millicredits equal one credit.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}Output Schema
{
"type": "object",
"properties": {
"balance_mc": {
"description": "Spendable millicredits (ledger minus active holds).",
"type": "string"
},
"active_holds_mc": {
"description": "Millicredits reserved by in-flight forecasts.",
"type": "string"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": {}
}🟢get_usage(limit, offset)
Return the account's forecast request log, newest first, with the mode, models used, series count, horizon, credits estimated and settled, HTTP status and latency of each request.
Input Schema
{
"type": "object",
"properties": {
"limit": {
"description": "Rows per page, 1 to 200. Defaults to 50.",
"type": "integer",
"minimum": 1,
"maximum": 200
},
"offset": {
"description": "Rows to skip. Use `pagination.next_offset` from the previous page.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}Output Schema
{
"type": "object",
"properties": {
"data": {
"description": "Request log rows, newest first.",
"type": "array",
"items": {
"type": "object",
"properties": {
"requestId": {
"type": "string"
}
},
"additionalProperties": {}
}
},
"limit": {
"type": "number"
},
"offset": {
"type": "number"
},
"pagination": {
"type": "object",
"properties": {
"limit": {
"type": "number"
},
"offset": {
"type": "number"
},
"returned": {
"type": "number"
},
"has_more": {
"type": "boolean"
},
"next_offset": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": {}
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": {}
}Community
Evidence