MacroStress
This MCP server lets you run MacroStress stress-testing workflows: convert a textual event into a scenario, estimate models, simulate paths, and analyze portfolio losses.
Read agent working guides and manage workspace/job state, logs, cancellation, and waiting.
Search, inspect, add, and update data series with publication-date awareness.
Search and manage scenario and model corpora, including indexing and fetching documents.
Create, validate, list, and retrieve scenarios; run reverse stress searches for worst loss or cheapest loss-reaching scenario; support bench workflows.
Start, monitor, inspect, and list simulation runs, including forecasts and portfolio loss reports with optional position contributions.
Manage portfolios: save, delete, check against a scenario, and value exposures.
Work with macro and satellite model versions: list, describe, estimate, backtest, inspect plugins, and manage model inputs.
Elicit a model’s required judgments through resumable question-answer steps.
Coordinate multi-agent input interviews: track progress, claim/release keys, restart stopped agents, audit answers, accept/reopen, and view history/journal.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MacroStress stress test my portfolio with the policy rate at 21% for the next year"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MacroStress
MacroStress answers one question: what happens to a portfolio if a given event occurs. A person states only the event, in words: "the central bank raises the policy rate to 21 % and holds it for a year", or "fertiliser exports are banned". An LLM agent turns the event into a scenario, a formal record the models can compute, using a corpus of sources known at the calculation date: news, regulator decisions, descriptions of past episodes. The person checks and approves the scenario. The models then simulate the economy under it, level by level, and reprice every position on the same paths. The result is the distribution of portfolio losses month by month.
flowchart LR
E["Event<br/>a person, in words"] --> A["LLM agent"]
K["Corpus of sources"] -.-> A
A --> S["Scenario"]
S -->|approved by the person| M["Models by level"]
M --> R["Loss distribution"]The platform itself names no model: macro models, satellite models and asset types are plugins, and a new one is a package added without edits to the core. The agent works through MCP; every step is also a command.
Event and scenario
An event is what a person expects to happen, said in words and possibly without numbers. The models cannot compute words: they need to know which values the event decides and which outcomes it requires. The agent writes this down as a scenario $s=(N,I,\mathcal A)$:
Part | What it holds | For "the policy rate is cut to 16 % in December" |
$N$ | the event in text, with links to the sources of its numbers | the text and the regulator's statement |
$I$ | interventions: decisions of a subject outside the models, a value set or shifted, with a law when the number is not exact | the key rate set at 16 % in months 1 to 3 |
$\mathcal A$ | observations: what the event requires of the outcome, a condition on a path, a mean or a probability | the rouble down 10 % by month 3 |
A statement is an intervention when a subject outside the models fixes the value: a decision on the policy rate, an export ban, the price of oil for an economy it acts on from outside. It is an observation when it names an outcome the system itself produces: the exchange rate after sanctions, the fall of output. The same number can be either, and the difference changes the consequences.
Every number in $I$ and $\mathcal A$ is labelled by its origin: the event itself, a named source, or an explicit assumption. If the event leaves the direction of a move open, the agent writes one scenario per direction, and each is computed separately. The agent does not start the calculation until the person approves the scenario.
The platform executes the interventions in the structural form the model declares: in the default form a set value replaces only its own cell and a shift moves only its own path. Then it changes the law of the other coordinates as little as possible so that the observations hold. The size of that change, $\mathrm{dist}(s)=\mathrm{KL}(P_s\Vert P)$, is reported as the scenario price: the higher it is, the less the scenario agrees with the models. A scenario names no model versions, horizon or number of paths: the calculation request names them, so one file is computed on any system of models, and the spread of the results shows how much the answer depends on that choice.
Related MCP server: PA MCP Server
Levels of the economy
Quantities are split into levels $l=0,\dots,L$, from the general to the particular: for example the economy, an industry, a company. Each level has its own model, which takes the paths of the levels above it as inputs. The last level holds the target indicators.
Level | Model | Example quantities |
$0$ | macro model: joint paths of the macro variables | policy rate, inflation, exchange rate, output |
$1,\dots,L$ | satellite model of the level: its quantities from the levels above plus its own noise | overdue loans of an industry, a company's share price, a bond spread, housing prices |
flowchart LR
H["History"] -.-> M0
S["Scenario"] --> M0
M0["Level 0<br/>macro model"] --> M1["Level 1<br/>satellite model"] --> ML["Level L<br/>target indicators"]
M0 --> P["Positions<br/>loss distribution"]
M1 --> P
ML --> PThe definitions are in docs/concept/formalization.en.md.
Plugins
Kind | What it models | Shipped examples |
macro | level 0: shocks and paths of the macro variables |
|
satellite | a level above 0: its quantities from the paths of the levels above |
|
position | an asset type: the value of a position on the paths |
|
The macro model is chosen when it is estimated. A quantity goes to the satellite model that
declares it, or to the one named explicitly. A position goes to the plugin of its asset type.
Every shipped plugin describes its model in REFERENCE.en.md next to the code.
python -m mst.plugin new my_model --kind macro # a package with plugin.py, a model and tests
python -m mst.plugin check my_model # the contract checks
python -m mst.plugin demo-run my_model # a calculation on a toy workspaceThe platform finds a plugin in mst.plugins, through an entry point of the group mst.plugins,
or in a directory listed in MST_PLUGINS_PATH. The guide is
docs/howto/plugins.en.md.
The shipped models are examples under development and change between releases. The episode backtest scores every version on historical events against a random walk with drift. Its episodes and the other check sets with known answers are in bench/.
Data
The series, their sources and release lags are configuration: src/mst/data/sources.toml, the
variable registry src/mst/macro/registry.toml and the driver registry
src/mst/drivers/registry.toml. The shipped set is a sample. Every value keeps its release
date, so a model estimated as of a date sees only what was published by then. Data are not part
of the repository; you download them under each source's terms.
Output
For every month of the horizon: quantiles of the target indicators and of the portfolio loss ($P_5$, $P_{50}$, $P_{95}$), ES95 (the mean loss over the worst 5 % of paths) and the scenario price. The reverse search answers the opposite question: the worst loss among scenarios no dearer than a given price, or the cheapest scenario that reaches a given loss.
Working with an agent
The server speaks MCP, so any MCP client can drive it: Claude Desktop, Claude Code, Cursor,
Codex. It offers seven tools: jobs, series, corpus, scenario, run, portfolio,
model; long operations run as jobs. The dsh/ folder holds a plugin for DeepSeek Harness (DSH)
with three skills, among them scenario-from-corpus, the agent's instructions for turning an
event into a scenario, and a workspace summary in the agent prompt. All state lives in one
workspace directory: there is no web interface, database or scheduler.
Install
Python 3.12 or newer and uv are enough.
git clone https://github.com/LeoLourson/MacroStress-DSH
cd MacroStress-DSH
uv sync
uv run macrostress --workspace C:/data/macrostressThe server talks over stdio, prints only errors and waits for a client. Connecting a client: docs/howto/mcp.en.md; the DSH plugin: docs/howto/install.en.md.
First session
series(action="update"): the history.model(kind="macro", action="estimate", as_of=...): level 0.series(action="update", quantity=...), thenmodel(kind="satellites", action="estimate", version=...): the levels above.corpus(action="search", ...),scenario(action="save"),scenario(action="validate"): the scenario from the event.run(action="start"),run(action="result"): the forecast and the portfolio report.
Step by step: docs/howto/first-session.en.md.
Documentation
Layer | File | Question |
Concept | What the system computes: levels, scenario, overlay, result, quality metrics | |
Concept | How the scheme maps to code: packages, workspace, model versions, jobs | |
Concept | The first BVAR method; outdated, kept for history | |
How-to | Installing the Python package and the DSH plugin | |
How-to | Connecting any MCP client and fixing common errors | |
How-to | The first session, from series to report | |
How-to | Adding a macro model, a satellite or an asset type as a plugin | |
Reference | What the MCP tools and | |
Reference | The contracts: position, paths, model, registry, run and report |
Every document exists in Russian (*.md) and English (*.en.md); the index is
docs/README.en.md. Every package folder has its own README naming its files.
Development
uv sync
uv run pytest -q -m "not slow"
uv run ruff check .The slow tests estimate the macro models and take minutes; the nightly workflow runs the full
suite. CI runs the fast suite on Linux and Windows with Python 3.12 and 3.13.
Contributing and license
Contributing rules and the release process are in CONTRIBUTING.md; vulnerabilities go through SECURITY.md. The code is MIT-licensed, see LICENSE; the license does not cover the data you download. Citations are described in CITATION.cff.
Available Tools
10 toolscorpusScenario corpusB
The scenario corpus and the model corpus. Actions: search, get, list, add, index, fetch.
corpus="model" works with the corpus of the models — the material a model's
elicitation reads: episodes, the state at the date, transmission reviews, market
expectations — which has its own manifest and index under corpus-model/.
search and get read the index as it was on as_of; list shows what the
manifest holds; add registers a file downloaded by hand under its key. index
and fetch are tasks on the corpus resource. Inside a bench session every call and
its answer go to the journal of the event.
Inputs: action (required), k, id, ids, +9 more. Returns: object
elicitThe questions of a model and the answers the agent writesA
Answer a macro model's questions in small resumable steps.
Start with next and model_id/as_of. It gives one small question, its schema and
answer_call. Copy answer_call with your answer object as payload to answer;
the result saves it and gives the next question. Continue until complete=true.
Each response step asks nine numbers, not a full shock table. Partial answers survive
a restart and never count as a completed input. Never substitute placeholders or ask
the human for numbers. next resumes the first missing step.
A model that declares inputs is estimated from the agent's own answers, not from the
series: list names every input key on the date and status repeats the summary.
Full question/write operations belong to model(kind="inputs"), not this interview.
The agent is the expert: the numbers are its own judgements, not the
human's and not the fixtures of the tests. When nothing is missing, build the version:
model(kind="macro", action="estimate", model_id=..., as_of=...) starts a job, and
jobs(action="wait", id=...) holds until it ends. The same actions are kind="inputs" of
the model tool.
Inputs: action (required), key, agent, as_of, +3 more. Returns: object
guideWorking guidesARead-onlyIdempotent
The working guides of the agent: how to do the work, whatever the client.
Without name, the list. scenario-from-corpus turns an event into a scenario;
read it before scenario save.
Inputs: name. Returns: object
interviewThe interview of a model: who answers which input and how farA
Track the interview of a model: ownership, progress, review and corrections.
progress names every input key with its state, owner, answered parts and
publication; call it before handing a shock to an agent. claim gives one key to
one agent; a live claim of another agent refuses a second writer. release drops
the caller's claim. restart resumes an agent whose run stopped — a network error,
a timeout, a crashed client: it renews that agent's claim and returns the first
missing part, so the same agent continues where the saved parts end and nothing is
asked twice. audit lists the advisory findings of one published answer or
of every one. accept records that the warnings were reviewed, with the reason;
reopen asks named parts again, keeps the old answer as a version and makes the
key missing until it is complete again. history lists the versions of one answer
and journal the last events of the interview.
This tool never writes an answer: the numbers come only through elicit. The
orchestrating agent owns the process: it hands one shock to one subagent, reads the
warnings and either accepts the answer or reopens the steps they name.
Inputs: as_of (required), action (required), model_id (required), key, +5 more. Returns: object
jobsWorkspace and job stateADestructive
Workspace and task state. Actions: state, status, log, cancel, wait.
wait polls the job server-side, so one call replaces the loop of status and
log calls an agent would otherwise run while a long job works; it returns the
record status returns, and running says whether to call it again.
Inputs: action (required), id, tail, timeout_sec. Returns: object
modelModel versions and pluginsA
Model versions and plugins. kind: macro, satellites, inputs, catalog.
The episode check of the models is backtest (python -m mst.metrics).
Actions for macro: list, describe, base, estimate, backtest; for satellites:
list, describe, estimate; for catalog: list, the installed model plugins.
base gives p5, p50 and p95 of the macro variables under the base s_0 by month, up
to horizon, in the model scale, for only the variables named; it starts no job.
model_id names the macro model to estimate or backtest — the only one installed
when omitted; assignment maps a quantity to the satellite model that estimates
it in an estimate of the satellites, overriding the model that declares it.
version is the version hash describe and base read and the macro version the
satellites of an estimate are built on; list takes no version.
inputs is the elicitation a model that declares inputs is estimated from; the
elicit tool serves the same four actions and is the one to call when the user asks
for the answers of a model's questions. list and status name every key written
or missing, question gives the text the agent reads before answering and write
checks the answer's form and stores it. The inputs are written by the agent itself and
no human approves them — read guide(name="model-inputs") first — and model_id and
as_of name the model and the date; a refused answer comes back with the field it
was refused for.
Inputs: kind (required), action (required), key, only, +6 more. Returns: object
portfolioStored portfoliosBDestructive
Stored portfolios. Actions: list, get, save, delete, check, exposure.
save checks the contract and writes portfolios/<id>.json; check names every
position the scenario's macro and satellite versions cannot serve, with the reason of a
driver the out-of-sample check rejected, and warns what an impact on a macro variable
reaches through the positions' drivers, with the long-run loading of each one (below 0.1
it barely reacts); exposure values the positions at the calculation month of the
scenario's macro version.
Inputs: action (required), id, spec, scenario. Returns: object
runScenario runsA
Runs on the paths of a scenario. Actions: start, status, result, list.
Read guide(name="run-report") first. start draws the scenario's paths and
calculates a portfolio's positions — or the positions given in the call — on them,
as a job on the runs resource; status reports that job and what the run has
written, result the per-position results, the conditional forecast of the
targets (forecast.json: P5/P50/P95 of every target driver by month, in its own
unit; every driver when targets is omitted) and the report of a portfolio run,
list every run of the workspace. base_currency is the base of positions; a
portfolio brings its own.
Inputs: action (required), id, seed, draws, +6 more. Returns: object
scenarioStored scenariosADestructive
Stored scenarios. Actions: list, get, save, validate, reverse.
Read guide(name="scenario-from-corpus") before building one. save checks the
contract and writes scenarios/<id>.json; validate loads the macro and satellite
versions the file names and names every problem that keeps the scenario from being
computed, including corpus fragments not visible on the calculation day when the index
exists, and reports how the elements are marked and what the scenario leaves unsaid
under labels and warnings. reverse searches the scenario's family on
portfolio: the worst loss under the price kappa, or the lowest price whose loss
reaches level. bench returns the text of the bench event and starts its
journal of corpus calls; build the scenario by the guide, then bench_save checks
spec and keeps it with the journal and notes in the bench results, beside an
empty review the expert fills. A bench scenario is never approved and never computed.
Inputs: action (required), id, seed, spec, +6 more. Returns: object
seriesStored seriesC
Stored series. Actions: search, get, add, update.
update fetches the named ids; with quantity it instead discovers the
objects of that driver quantity and fetches their series.
Inputs: action (required), id, ids, text, +3 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
The tools are organized around distinct resources, but there is real overlap between elicit and model(kind="inputs"), and between jobs status/wait and run status. The rich descriptions help, but an agent can still hesitate over which tool owns an operation such as checking a run or supplying model inputs.
Names are consistently lowercase and mostly resource-oriented, which is readable across the set. Minor deviations are 'elicit' as a verb and 'jobs' as a plural among otherwise singular resource nouns.
Ten tools is a reasonable count for a complex macro stress-testing server. However, each tool packs many actions and modes, so the effective surface is much larger than the count suggests, and a few tools such as model and elicit could be cleaner if separated.
The surface covers the core lifecycle: series, portfolios, scenarios, models, elicitation, interviews, runs, and jobs. The main gaps are missing delete operations for several resources such as series, scenarios, and corpus entries, but these are not central blockers for the main workflows.
Maintenance
Related MCP Connectors
Stress-test portfolios against hundreds of regime-aware simulated futures for real markets.
Portfolio scenarios with instrument checks, Monte Carlo analysis and interactive reports.
Crypto portfolio risk analysis: VaR, scenarios, liquidity and correlation engines as MCP tools.
Portfolio and strategy stress diagnostics with hedge-break detection and regime outlook. Free tier.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides AI agents with quantitative risk tools such as VaR, expected shortfall, GARCH volatility, backtesting, stress testing, tail risk analysis, and credit scoring using synthetic or user-supplied data.71MIT
- FlicenseNot gradedqualityBmaintenanceEnables AI agents to run probabilistic portfolio analysis workflows, including input validation, instrument verification, simulation preparation, and approved interactive reporting.-
- FlicenseNot gradedqualityBmaintenanceEnables translating structured macroeconomic events into personalized travel, work-time, mortgage, fuel, and everyday-life impact scenarios via MCP tools.-
- AlicenseNot gradedqualityBmaintenanceEnables quantitative portfolio tail-risk analysis, option Greeks, Monte Carlo stochastic simulations, fixed-income duration/convexity, and Nelson-Siegel yield-curve interpolation through MCP tools.7MIT