# Retrocast MCP

> For AI agents: the complete documentation index is at
> [https://docs.retrocast.com/llms.txt](https://docs.retrocast.com/llms.txt) — every page is also available as
> markdown by appending `.md` to its URL.

The Retrocast MCP server exposes your
[Retrocast](https://app.retrocast.com) workspace as tools, so an MCP client can
ingest a dataset, inspect its columns, run forecasts and backtests, score the
results and open the run in the app — without you writing any HTTP calls.

It is a different server from the [Docs MCP](https://docs.retrocast.com/mcp/docs/docs-mcp),
which only searches this documentation and needs no account. This one works
against your own data, so it signs you in first.

## Who can connect

| | |
| --- | --- |
| Endpoint | `https://retrocast-backend-prod.fly.dev/mcp` |
| Transport | Streamable HTTP (stateless) |
| Authentication | OAuth 2.0 — your MCP client runs the flow for you |
| Requires | A [Retrocast account](https://app.retrocast.com). Free accounts get 20 forecasts a day; backtesting is available on paid plans |

Clients discover the authorization server from
`/.well-known/oauth-protected-resource/mcp`; there is nothing to register or
paste by hand.

No account yet? [Sign up for Retrocast](https://app.retrocast.com). The free tier
covers 20 forecasts a day, which is enough to connect a client and work through
the dataset and forecasting tools below. Backtesting is available on paid plans.

## Connect a client

**Claude, Codex and Cursor are the supported clients today.** Other MCP clients
aren't tested against this server yet — [tell us which one you need](#getting-help)
and we'll look at it.

Claude Code:

```bash
claude mcp add --transport http retrocast https://retrocast-backend-prod.fly.dev/mcp
```

Codex CLI:

```bash
codex mcp add --transport http retrocast https://retrocast-backend-prod.fly.dev/mcp
```

Claude Desktop and the Codex app read a JSON config instead:

```json
{
  "mcpServers": {
    "retrocast": {
      "url": "https://retrocast-backend-prod.fly.dev/mcp"
    }
  }
}
```

Cursor needs the OAuth client spelled out in `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "retrocast-mcp": {
      "url": "https://retrocast-backend-prod.fly.dev/mcp",
      "auth": {
        "CLIENT_ID": "PJdmQfpYABFfWspX"
      }
    }
  }
}
```

The first call opens a browser window for the OAuth consent step. After that the
client refreshes the token on its own.

Accounts belonging to more than one organisation aren't supported yet — a
connection resolves against your own. If you need multi-organisation access,
[get in touch](#getting-help).

## Tools

Everything below runs against your own organisation's data. Read-only tools are
marked as such by the server, so clients that ask before mutating only prompt on
the ones that write.

### Datasets

| Tool | Purpose |
| --- | --- |
| `upload_dataset` | Ingest a CSV or Parquet file. Returns a presigned upload target — PUT the bytes, then call `confirm_dataset_upload`. |
| `confirm_dataset_upload` | Finalise an upload: analyse, commit column roles, poll until the dataset is `ready`. |
| `create_dataset_from_link` | Ingest a presigned Parquet URL in one call, no upload round-trip. |
| `list_datasets` | Browse your datasets, newest first, paginated. |
| `get_dataset` | One dataset's status, column roles and readiness. |
| `get_dataset_columns` | Columns with types, flags, and the index/target suggested at analyse time. |
| `update_dataset_defaults` | Correct the default index or target column on a ready dataset. |
| `list_example_datasets` | Curated example datasets (`ex_…`) to try the workflow on. |
| `detect_hierarchy` | Infer categorical nesting (for example region → store → SKU). |
| `column_values` | Distinct values of one column. |
| `search_dataset_values` | Find which column holds a label, by searching every text column. |
| `query_timeseries` | The gap-filled target series as rows. |

`upload_dataset` never streams file bytes through the model or the server: it
hands back a self-signed storage URL that you PUT to directly. Uploads store no
default index or target, so pass the suggestion you want as an explicit
`datetime_column` / `target_column` — or set them once with
`update_dataset_defaults`.

### Covariates

| Tool | Purpose |
| --- | --- |
| `detect_covariate_roles` | Suggest how a covariate dataset's columns map onto a target. |
| `create_covariate_attachment` | Attach a covariate dataset to a target with column roles. |
| `list_covariate_attachments` | List attachments, optionally filtered by target. |

Uploading a *covariate* dataset is out of scope for now — attach one that is
already in the workspace.

### Forecasting and backtesting

| Tool | Purpose |
| --- | --- |
| `create_forecast` | Synchronous forecast. Accepts attached, inline and built-in covariates. |
| `run_backtest` | Synchronous backtest over historical cutoffs. Returns run metadata and pooled metrics. |
| `list_backtest_runs` | Browse runs with per-run metrics merged in. |
| `get_backtest_run` | One run's metadata and scalar metrics. |
| `list_backtest_series_metrics` | Per-series metrics — worst series by WAPE, or metrics rolled up by dimension. |
| `list_backtest_cutoff_metrics` | Per-cutoff WAPE/MAE/MAPE, sortable and filterable by date window. |
| `list_backtest_cutoff_results` | Per-cutoff actuals, forecasts and quantile bands, paged. |
| `export_backtest_csv` | Full-run predictions as CSV, via a short-lived download URL. |
| `compare_backtest_runs` | Deterministic comparison of 2–6 single-series runs, joined on forecast creation date. |

The backtest tools are available on paid plans. `create_forecast` is on every plan.

A grouped run returns pooled metrics only. Per-member figures live in
`list_backtest_series_metrics` — which also supplies the `series_id` the
cutoff-grain tools need. Metrics are fractions, not percentages.

### Scoring, charts and sharing

| Tool | Purpose |
| --- | --- |
| `score_forecast` | Score a forecast against actuals over an evaluation frame. |
| `score_forecast_arrays` | Score aligned `{forecasts, actuals, index}` arrays over an optional date range. |
| `plot_time_series` | Render a brand-styled chart PNG. Returns the image plus a short-lived download URL. |
| `create_share_url` | Build a link that opens a dataset in [Retrocast](https://app.retrocast.com) at a given mode, model, scope, horizon and cutoff. |

`create_forecast`, `run_backtest` and `get_backtest_run` lead with a
plain-language reading of the result — horizon, interval, which level to trust —
and attach it as structured content, with the compacted raw payload after it.
The backtest tools include an `app_url` that opens the run focused in the app.

## Guided workflows

Two prompts encode the method rather than leaving it to the model:

- `forecast_workflow` — detect the hierarchy, backtest each level, forecast at
  the level that backtests best, and recommend it citing that evidence.
- `forecast_report` — profile the data, forecast at your current operating
  points, score every forecast identically, and write a like-for-like accuracy
  comparison.

Both take an optional `dataset_id`.

## Interactive forecast viewer

Clients that support MCP Apps render `create_forecast` results as a live chart
instead of JSON. Every other client gets the same summary and payload as text —
nothing is hidden behind the viewer.

## Errors

| Status | Meaning |
| --- | --- |
| `401` | Missing or invalid token. Reconnect so the client can run the OAuth flow again. |
| `403` | Authenticated, but this account isn't allowed to use the server. |
| `404` | Unknown dataset, run or attachment. |
| `422` | Invalid tool arguments. |
| `429` | Rate limited, or the day's free-tier forecasts are used up. |

## Getting help

Ask in the chat inside [Retrocast](https://app.retrocast.com), or email
`support@theforecastingcompany.com`.