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., "@Tail-Risk-Toolkit Estimate 99.9% VaR and ES on these daily losses using EVT"
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.
An MCP server that gives an LLM agent a set of extreme value statistics tools for tail risk: peaks-over-threshold GPD fitting, Value-at-Risk and Expected Shortfall, return levels, threshold-stability diagnostics, and out-of-sample VaR backtesting.
Extreme value theory is the same machinery whether the tail is a flood or a portfolio loss. A 100-year return level and a 99% VaR on annual data are the same quantile of the same fitted distribution. This server exposes that machinery as agent-callable tools, so a model can be asked "how heavy is this tail, and does the risk model hold up out of sample?" and answer it with a real estimator rather than a plausible-sounding number.
The tools are deliberately opinionated about statistical practice:
Threshold choice is the main judgement call in a POT analysis, so tailrisk_threshold_stability exists to make an agent check it rather than accept a single fit.
tailrisk_var_es returns EVT, historical and Gaussian estimates side by side, because the gap between them is the argument for using a tail model at all.
Backtests are strictly out of sample: every forecast is fitted on trailing data only.
Errors explain what to do next ("lower the threshold", "the sample is too short at this confidence level") instead of failing silently or returning a fit that should not be trusted.
Related MCP server: SportsQuant MCP Server
Tool | Purpose |
| Fit a generalised Pareto distribution to threshold exceedances |
| VaR and Expected Shortfall by EVT, historical simulation and Gaussian baseline |
| Level exceeded once per return period, with the equivalent VaR confidence |
| Rolling-window backtest with Kupiec, Christoffersen and conditional coverage tests |
| Refit across candidate thresholds to check the fit is in the asymptotic regime |
| Read a numeric column from a local CSV so a series can be analysed |
All tools are read-only and side-effect free.
git clone https://github.com/John-Amal/Tail-Risk-Toolkit.git
cd Tail-Risk-Toolkit
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytestRequires Python 3.10+ and MCP SDK 2.x.
Add to your client's server configuration (for Claude Desktop, claude_desktop_config.json):
{
"mcpServers": {
"tailrisk": {
"command": "/absolute/path/to/Tail-Risk-Toolkit/.venv/bin/python",
"args": ["-m", "tailrisk_mcp.server"]
}
}
}The server speaks stdio. Use mcp.run(transport="streamable-http") in server.py for a remote deployment.
On 5,000 draws from a Student-t with 4 degrees of freedom, asking for the 99.9% loss quantile:
Method | VaR (99.9%) | Expected Shortfall |
EVT (POT, threshold at the 95th percentile) | 7.52 | 9.97 |
Historical simulation | 8.51 | 10.02 |
Gaussian | 4.41 | not defined here |
The true value is 7.17. The Gaussian figure understates it by 39%, which is the practical point: at the 99.9% level a normality assumption discards most of the risk. Historical simulation happens to land close here but cannot go beyond the largest observed loss at all, so it stops working exactly where the question gets interesting.
Reproduce with:
python examples/demo.pyExceedances above a threshold u are modelled with a GPD by maximum likelihood, giving shape xi and scale sigma. The tail is
P(X > z) = zeta_u * [1 + xi (z - u) / sigma] ** (-1 / xi)where zeta_u is the empirical exceedance rate. Inverting it gives both VaR (set the exceedance probability to 1 - q) and return levels (set it to 1 / T). Expected Shortfall follows in closed form as (VaR + sigma - xi*u) / (1 - xi) and is reported as undefined when xi >= 1, since the tail then has no finite mean.
Backtesting uses the Kupiec proportion-of-failures test for breach frequency and the Christoffersen test for breach independence, combined into a conditional coverage statistic.
References: Coles (2001); McNeil and Frey (2000); Kupiec (1995); Christoffersen (1998).
pytest runs 17 tests. The statistical ones simulate from distributions with known tail behaviour and check the estimators recover it: a Pareto(3) sample should return a shape near 1/3, and EVT VaR on Student-t data should match the analytic quantile within 10%. The calibration test evaluates coverage across several random seeds, because with around 20 breaches per run the independence statistic is noisy enough that a single seed will occasionally reject correctly specified data.
Observations are assumed independent and identically distributed. Real financial returns are volatility-clustered, so a production implementation would filter with a GARCH model first and fit the GPD to the standardised residuals, following McNeil and Frey. This server fits the raw series.
Parameter uncertainty is not propagated: no confidence intervals on VaR, ES or return levels. Profile likelihood or a bootstrap would be the next addition.
No multivariate or dependence modelling, so nothing here addresses portfolio aggregation across risk factors.
MIT.
Backtest a VaR model out of sample with Kupiec and Christoffersen tests.
Each forecast uses only trailing data, so the result is a genuine out-of-sample assessment of whether breaches occur at the right rate and without clustering. This is the evidence a model validation report needs.
Returns:
str: JSON with n_forecasts, n_breaches, breach_rate,
expected_breach_rate, the Kupiec, Christoffersen and conditional
coverage statistics with p-values, and a plain-language verdict.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint and idempotentHint provided by the annotations, the description adds extra behavioral value: 'Each forecast uses only trailing data, so the result is a genuine out-of-sample assessment.' It also discloses the exact JSON fields returned, which is meaningful detail beyond the annotated safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the core purpose, and includes a structured return list rather than prose. Each sentence earns its place: purpose, no-lookahead guarantee, use-case context, and explicit output fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich input schema, clear output description, and safety/lookahead disclosures, an agent has everything needed to invoke the tool correctly. No important invocation detail appears missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description itself does not elaborate on parameters, but the input schema already provides rich per-property descriptions for tail, method, values, window, and confidence. Since the schema does the heavy lifting and the description does not contradict or extend it, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description leads with a specific verb and resource: 'Backtest a VaR model out of sample with Kupiec and Christoffersen tests.' This clearly differentiates the tool from siblings such as tailrisk_fit_gpd, tailrisk_var_es, and tailrisk_return_level, which deal with fitting and estimation rather than backtesting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: it is the 'evidence a model validation report needs' for assessing whether VaR breaches occur at the right rate and without clustering. It stops short of explicitly naming alternative tools or stating when not to use it, so it earns a 4 rather than 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fit a generalised Pareto distribution to threshold exceedances.
Use this first when asked how heavy a tail is. The shape parameter is the headline number: above zero means a heavy tail with no upper bound, near zero means exponential decay, below zero means a finite worst case.
Returns:
str: JSON with keys threshold, shape, scale,
n_observations, n_exceedances, exceedance_rate,
log_likelihood and an interpretation string.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context: how to interpret the shape parameter and what keys the returned JSON contains. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: purpose first, usage signal second, interpretation guidance third, and return format last. Every sentence earns its place without redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a statistical fitting tool, the description covers purpose, usage timing, interpretation, and return keys. Combined with the detailed nested schema and annotations, this is nearly complete; only minor gaps like default threshold behavior are left to the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain how to set tail, threshold, threshold_quantile, or values, even though schema description coverage is reported as 0%. The schema itself contains useful parameter descriptions, but the tool description provides no compensating guidance for parameter selection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a precise action: fit a generalised Pareto distribution to threshold exceedances. It also clarifies the headline result (shape parameter) and what its sign means, making the tool's purpose unmistakable and distinct from sibling tail-risk tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this first when asked how heavy a tail is,' giving clear when-to-use guidance. It does not, however, name sibling tools or describe when to prefer tailrisk_var_es, tailrisk_return_level, or the others instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one numeric column from a local CSV so a series can be analysed.
Call this before the analysis tools when the data lives in a file rather than in the conversation. Non-numeric and empty cells are skipped and counted so data quality is visible.
Returns:
str: JSON with values (the parsed numbers), count,
skipped_rows and truncated.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and idempotentHint=true, covering safety. The description adds valuable behavioral context by mentioning that non-numeric and empty cells are skipped and counted, and that truncation may occur (via the 'truncated' return field). This goes beyond what annotations provide without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short paragraphs with a structured 'Returns' section. The main purpose is front-loaded, every sentence adds value (usage timing, data quality behavior, return format), and there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the return format and the skipping/truncation behavior, but with 0% schema coverage it leaves parameter semantics completely unexplained. The output schema may exist (indicated by 'has output schema: true'), which lightens the need to document return values, but the missing parameter explanations are a notable gap for a loading tool that an agent must call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for explaining parameters, but it does not. It never mentions 'path', 'column', or 'max_rows' by name, nor clarifies that 'column' is a header name or that 'max_rows' limits parsing. While parameter names are somewhat self-explanatory, the lack of description means an agent may misinterpret expectations, especially given the 0% coverage signal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Read'), resource ('one numeric column from a local CSV'), and purpose ('so a series can be analysed'). It clearly distinguishes from sibling analysis tools by positioning itself as the loading step, and the phrase 'Call this before the analysis tools' reinforces its distinct role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Call this before the analysis tools when the data lives in a file rather than in the conversation', which gives clear context and implies when not to use it. However, it does not name specific alternatives or exclusions (e.g., when data is already in memory), which would have improved guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Estimate the level exceeded once per return period.
This is the same POT quantile as VaR in a different vocabulary: a 100-period return level equals the 99% VaR on data at that frequency. Use it when the question is phrased as a 1-in-N event rather than a confidence level.
Returns:
str: JSON with return_period, return_level,
equivalent_var_confidence, threshold and shape.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds conceptual context (POT quantile equivalence to VaR) and lists the output fields, which is useful but largely mirrors an existing output schema. No contradiction exists between description and annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact paragraphs with zero filler: core purpose front-loaded, a single sentence of routing guidance, and a Returns stanza. Every sentence earns its place and the VaR-equivalence explanation is the highest-value content positioned early.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a read-only, idempotent estimation tool: purpose, routing, sibling differentiation, and output format are all covered. The parameters are exhaustively documented in the schema and an output schema exists, so the description isn't required to restate them. Minor gap: no mention of edge cases like insufficient data or threshold validity, though the schema's constraints partially cover this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is richly documented - every parameter (tail, values, threshold, return_period, threshold_quantile) carries a clear description, so the schema does the heavy lifting despite the 0% coverage signal suggesting otherwise. The description bolsters this by explaining what equivalent_var_confidence means via the VaR-equivalence framing, adding interpretive value beyond the raw field names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair ('Estimate the level exceeded once per return period') and immediately distinguishes itself from the sibling tailrisk_var_es by explaining the vocabulary mapping ('a 100-period return level equals the 99% VaR'). An agent can tell this from Var/ES and fit_gpd without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to prefer this tool: 'Use it when the question is phrased as a 1-in-N event rather than a confidence level.' This gives clear routing against VaR phrasing. It does not, however, name the exact sibling tool (tailrisk_var_es) to switch to, nor state explicit when-not cases, only the positive trigger condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Refit across candidate thresholds to test whether the tail fit is stable.
Threshold choice is the main judgement call in a POT analysis. Call this before trusting a single fit: if the shape parameter drifts steadily with the threshold, the estimate is not yet in the asymptotic regime.
Returns:
str: JSON with a scan list (one record per threshold, each with
quantile, threshold, shape, scale, modified_scale,
n_exceedances), the shape_range across the scan, and a
stability verdict.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read operation. The description adds valuable context: that the tool performs a scan across thresholds and provides a stability verdict, which goes beyond the annotations. There is no contradiction. It could detail the return format more, but the output schema covers that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: it starts with the main purpose, then provides the key usage trigger, and ends with a precise return format. Each sentence earns its place, and there is no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of a rich output schema (detailing the scan list fields), the description is complete for an agent to decide when to call it and what to expect. The description plus annotations and output schema cover all necessary aspects: purpose, usage context, parameter meanings, and return structure. No critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite schema description coverage being 0%, the description explicitly explains the `tail` parameter's usage: 'Use 'upper' for a loss series where large positive values are bad, 'lower' for a return series where large negative values are bad.' This adds significant meaning beyond the schema's enum. The `quantiles` parameter is described as 'Candidate threshold quantiles' with a default sweep, and `values` is straightforward. The description of the output scan list compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Refit across candidate thresholds to test whether the tail fit is stable.' It identifies the specific verb (refit/test), resource (thresholds for tail fit), and the analytical goal. It also distinguishes itself from sibling tools like tailrisk_fit_gpd by focusing on stability across thresholds, not a single fit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: 'Call this before trusting a single fit' and explains the conditions that indicate instability ('if the shape parameter drifts steadily with the threshold'). It implies that tailrisk_fit_gpd is for single fits and should be used with this tool for validation. While it doesn't name the sibling explicitly, the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Estimate VaR and Expected Shortfall by three methods for comparison.
The EVT estimate extrapolates beyond the observed sample, the historical estimate cannot, and the Gaussian estimate is a deliberately naive baseline. A large gap between the EVT and Gaussian figures is the quantitative case for using a tail model at all.
Returns:
str: JSON with an evt object (var, es, shape,
threshold), historical and gaussian objects, plus
evt_vs_gaussian_ratio and the confidence level. Individual
methods report a note instead of a number when undefined.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as readOnly and destructiveHint=false; the description adds valuable behavioral context by explaining that EVT extrapolates beyond observed data, historical cannot, and Gaussian is deliberately naive. It also discloses that individual methods report a 'note' instead of a number when undefined, which is useful runtime behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and uses a structured Returns section. The middle paragraph about EVT vs Gaussian is somewhat conceptual but earns its place by explaining why the comparison matters, so the overall length is appropriate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only estimation tool with annotations and a detailed nested schema, the description is reasonably complete. However, the lack of usage guidance and parameter-semantics compensation leaves an agent without clear direction on when to call this tool versus siblings or how to set lower-tail conventions beyond what the schema already provides.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is reported as 0%, so the description must compensate for parameter meaning, but it adds almost no input parameter guidance. It mentions 'threshold' and 'confidence' in the return shape, but does not explain how to set tail, threshold, threshold_quantile, or confidence for the call.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Estimate VaR and Expected Shortfall by three methods for comparison.' It clearly distinguishes this tool from siblings like tailrisk_fit_gpd or tailrisk_backtest_var by focusing on joint VaR/ES estimation with a three-method comparison.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the methods do conceptually but provides no explicit guidance on when to choose this tool over siblings. It does not mention alternatives, exclusions, or conditions such as 'use this when comparing tail models' or 'for backtesting use tailrisk_backtest_var.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0tailrisk_backtest_vartailrisk_fit_gpdtailrisk_load_csv_seriestailrisk_return_leveltailrisk_threshold_stabilitytailrisk_var_esScored across 6 tools
Each tool targets a distinct stage of tail-risk analysis: data loading, threshold diagnostics, GPD fitting, VaR/ES estimation, return levels, and backtesting. Even the related VaR/ES and return-level tools are clearly separated by phrasing (confidence level vs. return period).
All tools share a consistent tailrisk_ prefix and use snake_case, making the family instantly recognizable. However, the second part mixes verb-object forms like fit_gpd and backtest_var with noun phrases like var_es and threshold_stability, so the naming is not perfectly uniform.
Six tools is well-scoped for a specialized tail-risk toolkit. Each tool contributes a necessary part of the workflow without redundancy or bloat.
The toolkit covers the full practical workflow: loading data, assessing threshold stability, fitting the GPD, computing VaR/ES and return levels, and backtesting the VaR model. There are no obvious dead ends or missing core operations for the stated domain.
Portfolio and strategy stress diagnostics with hedge-break detection and regime outlook. Free tier.
Deterministic company valuation and corporate finance tools for AI agents — IRR, NPV, MOIC, DCF, WACC, enterprise value, EV multiples, CAPM, beta and sensitivity analysis via Model Context Protocol. Useful for financial analysis, equity analysis, quantitative analysis, financial projections, financial formulas and financial modeling.
Market analyst tools + AI agent: crypto, US equities, options, Korea, fundamentals, macro, backtests
Deterministic time-value-of-money and fund-performance tools for AI agents — future value, present value, CAGR, annuities, perpetuities, loan payments, payback, discounted payback, DPI, RVPI and TVPI via Model Context Protocol. Useful for corporate finance, financial projections, financial analysis, quantitative analysis, financial formulas and financial modeling.