Build a Diagnostic-First Time-Series Forecasting Agent with an MCP Forecasting Server in 2026

By Deepak Bagada, CEO at SaaSNext & Principal AI Architect.

Introduction

The most common enterprise forecasting failure is not a bad model — it is a model chosen in the dark. Zhorly teams pipe raw series straight into a neural forecaster, get plausible numbers, and never notice that the series had a structural break the model never saw, or that a third of the history was null-imputed before training.

A 2026 working paper from Paderborn University's Center for International Economics (CIE Paper 178) tested exactly this problem. Researchers built a hybrid architecture: a business agent acting as orchestrator and a time-series MCP server exposing reusable forecasting tools. In the zero-shot setting, the agent simply compared available tools. In the diagnostic-aware setting, the agent first analyzed data quality, seasonality, stationarity, structural breaks, and influencing factors before selecting a strategy. The diagnostic-aware workflow improved forecast accuracy and explanation quality. Crucially, no single model family dominated: automatic ARIMA scored the highest aggregate accuracy but took the longest runtime, while Chronos-2 and Toto 2.0 offered the best accuracy-runtime trade-offs, and exponential smoothing stayed fast and interpretable.

This workflow turns that research into production code. You build the forecasting MCP server, the diagnostic stage, and the LangGraph orchestrator that audits its own model choice. The full pipeline catalog lives in our AI workflows library, and the server you build here is exactly the kind of tool we track in the MCP directory.

Architecture

graph TD
  A[Business User] --> B[Forecasting Orchestrator Agent]
  B --> C{MCP Forecasting Server}
  C --> D[Diagnostics Tool]
  C --> E[Model Selector Tool]
  C --> F[Forecast Tool]
  C --> G[Backtest Tool]
  D --> H[Data Quality Checks]
  D --> I[Seasonality / Stationarity]
  D --> J[Structural Break Detection]
  E --> K[ARIMA / ETS / Chronos-2 / Toto 2.0]
  B --> L[Explainability Report]

The seven-stage lifecycle: ingest → clean → diagnose → choose → forecast → backtest → explain. The diagnosis stage is the gate that makes the rest trustworthy.

Part 1 — The MCP Forecasting Server

The server exposes structured tools, not chat. Every tool takes a Pydantic schema and returns JSON results the orchestrator can reason over.

.env

MODEL_CACHE_DIR=./models
ARIMA_MAX_ORDER=(3,1,3)
FORECAST_HORIZON=30
MCP_TRANSPORT=stdio

schemas.py

from pydantic import BaseModel
from typing import Optional, List

class SeriesInput(BaseModel):
    series_id: str
    values: List[float]
    timestamps: List[str] = []
    frequency: str = "D"          # D=day, M=month, Q=quarter

class DiagnosisReport(BaseModel):
    series_id: str
    data_quality_score: float
    missing_pct: float
    seasonality_detected: bool
    seasonality_period: Optional[int]
    stationary: bool
    structural_break_at: Optional[str]
    recommended_family: str

tools.py

import numpy as np
from statsmodels.tsa.stattools import adfuller
from statsmodels.tsa.seasonal import seasonal_decompose
from ruptures import Pelt

def diagnose(series: SeriesInput) -> DiagnosisReport:
    y = np.asarray(series.values, dtype=float)
    missing_pct = float(np.isnan(y).mean())
    # stationarity via ADF test
    adf, p = adfuller(y, autolag="AIC")[:2]
    # seasonality via autocorrelation on the detrended series
    seasonality, period = detect_seasonality(y, series.frequency)
    # structural break via PELT with a fixed cost budget
    break_idx = detect_break(y)
    fam = select_family(missing_pct, not (p < 0.05), seasonality, break_idx)
    return DiagnosisReport(...)

server.py

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("forecasting-mcp", host="0.0.0.0", port=9000)

@mcp.tool()
def diagnose_series(input: SeriesInput) -> DiagnosisReport:
    return diagnose(input)

@mcp.tool()
def forecast(input: SeriesInput, family: str, horizon: int = 30) -> dict:
    if family == "auto_arima":
        return run_auto_arima(input, horizon)
    if family == "chronos_2":
        return run_chronos_2(input, horizon)
    if family in ("ets", "toto_2_0"):
        return run_smoothed_or_toto(input, family, horizon)
    raise ValueError(f"unrecognized family {family}")

@mcp.tool()
def backtest(input: SeriesInput, family: str, windows: int = 3) -> dict:
    return rolling_backtest(input, family, windows)

Part 2 — The Diagnostic-Aware Orchestrator

The orchestrator is where the paper's finding becomes policy: no forecast without a diagnosis. It refuses to select a model until tests have run, and it records the reasoning so the choice can be audited later.

graph.py

from langgraph.graph import StateGraph, END

class ForecastState(TypedDict):
    series: SeriesInput
    diagnosis: DiagnosisReport
    model: str
    forecast: dict
    backtest: dict

g = StateGraph(ForecastState)
g.add_node("ingest", ingest)
g.add_node("diagnose", lambda s: mcp.diagnose_series(s["series"]))
g.add_node("route_model", route_by_diagnosis)
g.add_node("forecast_node", run_selected)
g.add_node("backtest_node", backtest_selected)
g.add_node("explain", build_report)

g.set_entry_point("ingest")
g.add_edge("ingest", "diagnose")

# Conditional edge: a broken series is quarantined, never modelled blindly
g.add_conditional_edges("diagnose", route_by_diagnosis, {
    "arima": "forecast_node",
    "chronos_2": "forecast_node",
    "ets": "forecast_node",
    "quarantine": END,
})
g.add_edge("forecast_node", "backtest_node")
g.add_edge("backtest_node", "explain")
g.add_edge("explain", END)

main.py

from mcp import ClientSession, StdioServerParameters

async def main():
    server = StdioServerParameters(command="python3", args=["server.py"])
    async with ClientSession(server) as session:
        state = {"series": load_retail_series("sku-9912")}
        app = build_graph()
        result = await app.ainvoke(state, config={"recursion_limit": 40})
        print(result["explain"]["markdown"])

Retry rules: forecast calls retry with backoff on transient MCP transport errors (1s → 2s → 4s, max 3). Backtests re-run if the forecast horizon crosses a detected structural break; the explain stage then flags the boundary rather than hiding it.

Choosing the Model Family

No single family wins every case — that is the entire reason the diagnostic gate exists. Cost-aware selection is the orchestration pattern, not the model.

Interpretability & Human Oversight

The agent ends with an explainability report: why this family, what the ADF test said, where the structural break sits, and a backtest table. In regulated settings a human approves the final published forecast via a interrupt_before gate. This mirrors how we design every governed pipeline in our AI workflow library.

Production Checklist

1. Diagnose before you model — never let a bare auto_arima shortcut skip the gate.
2. Track matrix per series family; let the break points, not the vendor blog, pick the model.
3. Store every diagnosis report as audit evidence for 12 months.
4. Budget query costs: run backtests in a cheaper model tier, keep diagnostics cheap.
5. Publish confidence as a band, not a single number, when backtests are sparse.

Governance for regulated forecasts

When a forecast feeds a regulatory or capital decision, the pipeline's evidence trail is the deliverable. Every DiagnosisReport — data quality score, ADF p-value, seasonality period, break points, and the routing rule — is persisted beside the forecast so a reviewer can replay the decision. Add two controls: a frozen-model policy (once a family is approved for a product line, candidates must be re-validated on the golden set before any swap, with a documented rollback) and horizon gating (forecasts that cross an approved horizon are flagged rather than silently extended). These are the same governance gates we build into production pipelines in our AI workflows library, and the reusable function library you compose them from is indexed in the MCP directory.

Cost governance for the agentic forecasting loop

The forecasting agent is an LLM-intensive loop, and the cheapest way to control spend is to keep expensive models off the mechanical path. Diagnostics are deterministic and cheap; model selection is rules on top of diagnostics; only the explanation stage needs an LLM, and it can be a mid-tier model. Reserve the flagship tier for genuinely adversarial reasoning. Cap per-run budgets in the orchestrator and route background batch forecasting through a cheaper tier — the same tier-aware routing we describe in our model-economics and latest AI news coverage. Teams that batch 500 series across three backtests will find the cost profile is set by these choices, not by the models themselves.

The data flywheel behind the diagnostics

The diagnostic gate compounds. Every series you run adds labeled examples — break events, seasonal shifts, family selections that were later corrected — and those examples become the feedback set for future routing rules. Treat the DiagnosisReport store as training data, not archive: re-tune the router once a quarter against accumulated outcomes, and re-run the golden set before any routing change goes live. That closes the loop the zero-shot agent lacks: it makes the pipeline's model-selection decisions auditable and, over time, measurably better. Building the evaluation and feedback layer around your forecasting loop is the same instrumentation discipline we document across our AI workflow library — the model changes, the loop stays.

Final tuning notes

Start the first production rollout with a small, high-signal series set where a wrong forecast is cheap and the golden set is unambiguous; expand after two clean backtest cycles. Budget the evaluation loop — a quarterly router re-tune against accumulated DiagnosisReports keeps the selection policy current as data shapes drift. And never ship horizon-crossing forecasts without a flag: the pipeline's value is that it knows the boundary of its own validity, which is the one behavior a spreadsheet-based forecast cannot offer.

Frequently Asked Questions

Q: Why does diagnostic-aware forecasting outperform zero-shot model selection?

A: Because the forecast quality depends on matching method to data shape. Checking seasonality, stationarity, missing values, and structural breaks before choosing a family removes avoidable model-family mismatches and gives the model a correct, auditable reason for its own selection.

Q: Which model family is best for time-series forecasting in 2026?

A: There is no universal winner. CIE 178 found automatic ARIMA most accurate overall but slowest, while Chronos-2 and Toto 2.0 delivered the best accuracy-runtime trade-offs. The correct answer is a routing policy based on diagnostics, not a single model.

Q: When should I quarantine a series instead of forecasting it?

A: When data quality fails (missing percentage above threshold, no stationary transform possible) or when a structural break lands inside the forecast horizon. Pushing those series through a model produces confident nonsense.

Q: How do I justify a forecast model choice to auditors?

A: Persist the DiagnosisReport next to the forecast — ADF p-value, seasonality period, break index, and the routing rule that selected the family — so every prediction carries its own decision record.