MCP tools reference
This is the reference for the Lona MCP tools. The catalog is assembled in
packages/lona-mcp-server/src/tools/index.ts.
The names and input fields below are the MCP contracts; gateway-only agent
routes are not additional MCP tools.
Catalog
| Category | Count | Tools |
|---|---|---|
| Credit | 1 | lona_get_credit_usage |
| Strategy | 4 | lona_list_strategies, lona_get_strategy, lona_create_strategy, lona_update_strategy |
| Strategy documentation | 1 | lona_get_strategy_documentation |
| Symbols and market data | 4 | lona_list_symbols, lona_search_symbols_by_name, lona_get_symbol, lona_download_market_data |
| Backtesting | 2 | lona_run_dry_run_backtest, lona_run_backtest |
| Optimization | 12 | lona_list_optimizations, lona_show_optimizations, lona_get_optimization, lona_show_optimization, lona_show_time_window_optimization, lona_get_latest_optimization_by_strategy, lona_wait_for_optimization, lona_list_optimization_results, lona_show_optimization_results, lona_cancel_optimization, lona_run_optimization, lona_run_time_window_optimization |
| Walk-forward analysis | 6 | lona_list_walk_forward_analyses, lona_get_walk_forward_analysis, lona_show_walk_forward_analysis, lona_preview_walk_forward_analysis, lona_run_walk_forward_analysis, lona_wait_for_walk_forward_analysis |
| Reports | 4 | lona_list_reports, lona_get_report, lona_list_report_trades, lona_wait_for_reports |
Older code-view, CSV-upload, and asynchronous-generation entries are omitted
from this catalog. lona_get_strategy returns the strategy’s complete source
code, and lona_create_strategy accepts code directly.
Common behavior
All tools require an authenticated MCP session. Mutating tools can consume
credits or create resources, so an agent should explain the action and obtain
approval when appropriate. Tool responses may include a usage object with
current credit information:
{
"credits_consumed": 250,
"credits_remaining": 2750,
"credits_total_monthly": 3000,
"period": "2026-02"
}The backend is authoritative for plan limits and balances. A tool’s response
may also include an MCP App widget or a lona:// resource; those are
presentation affordances and do not change the tool contract.
Credit
lona_get_credit_usage
Get the authenticated account’s credit limit, current balance, and remaining free optimizations when applicable.
Parameters: {}
Returns: Credit usage and entitlement information.
Safety: Read-only.
Strategy authoring
lona_get_strategy_documentation
Return the authoritative Lona strategy-authoring documentation. Call this before authoring or modifying Backtrader code. It describes the execution environment, supported APIs, multi-data rules, order handling, parameters, and visualization behavior.
Parameters: {}
Returns: The complete strategy-authoring documentation as text.
Safety: Read-only.
lona_list_strategies
List the authenticated user’s saved strategies without source code.
| Parameter | Type | Required | Default / limits |
|---|---|---|---|
skip | integer | No | Non-negative; omitted means the first page |
limit | integer | No | 10 by contract; 1–50 |
Returns: A paginated list of strategy summaries. Use
lona_get_strategy for one strategy’s complete details and code.
Safety: Read-only.
lona_get_strategy
Get one saved strategy, including its complete source code.
| Parameter | Type | Required |
|---|---|---|
id | string | Yes |
Returns: Strategy metadata and Python source code.
Safety: Read-only.
lona_create_strategy
Create a saved strategy from complete Python code authored by the calling
agent. Before calling it, fetch the authoring documentation and successfully
run lona_run_dry_run_backtest with the complete source.
| Parameter | Type | Required | Default |
|---|---|---|---|
name | string | Yes | — |
description | string | No | Empty description |
code | string | Yes | — |
version | string | No | 1.0.0 |
The code must define a bt.Strategy subclass. Do not add imports; the
execution environment provides bt. Use tuple-form strategy parameters,
initialize indicators in __init__, and implement trading logic in next().
Returns: The backend-created strategy result, including its id.
Safety: Creates a resource; obtain approval before saving when the user has not already requested it.
lona_update_strategy
Modify an existing strategy’s metadata and/or source. Updating creates an immutable new strategy version and returns the new backend ID.
| Parameter | Type | Required |
|---|---|---|
id | string | Yes; current strategy version |
name | string | No |
description | string | No |
code | string | No |
When changing code, fetch the authoring documentation and dry-run the complete updated source before saving. The previous version is replaced in normal listings, but its version identity remains part of the version history.
Returns: The backend update result, including the new strategy id.
Safety: Creates a new version; obtain approval before saving.
Symbols and market data
Global data is shared pre-loaded data. When a requested symbol is not already
cached globally, lona_download_market_data downloads full-history OHLCV data
through the Tiingo-backed data service and stores it as a global symbol. The
MCP server does not expose a CSV upload tool.
Global data availability is asset-class dependent:
- Equities and ETFs:
1donly. - Forex, including metal pairs such as
XAU/USD, and crypto:5m,15m,1h,4h, and1d. - Symbol search accepts ticker/name forms such as
AAPL,BTC/USD,XAU/USD,XAUUSD, andgold.
User-uploaded symbols may carry their uploaded frequency. Always inspect
data_availability or the symbol metadata before choosing a frequency.
lona_list_symbols
List available symbols. If is_global is omitted, both global and the user’s
own symbols are returned.
| Parameter | Type | Required | Default / limits |
|---|---|---|---|
skip | integer | No | Non-negative; omitted means the first page |
limit | integer | No | 20; 1–50 |
is_global | boolean | No | Omitted: both; true: global only; false: user-owned only |
asset_class | enum | No | One of crypto, equity, etf, forex, index |
Returns: Paginated symbol metadata, including ownership and frequency availability.
Safety: Read-only.
lona_search_symbols_by_name
Search global and user-owned symbols by ticker, name, or prefix.
| Parameter | Type | Required |
|---|---|---|
symbolName | string | Yes |
The field is camelCase exactly as shown. For example:
{"symbolName": "XAU/USD"}Returns: Matching symbol metadata and frequency availability.
Safety: Read-only.
lona_get_symbol
Get one symbol’s public metadata, including source type, asset class, exchange, quote currency, and available frequencies.
| Parameter | Type | Required |
|---|---|---|
id | string | Yes |
Returns: Symbol metadata and data_availability by frequency.
Safety: Read-only.
lona_download_market_data
Download full-history OHLCV data for a stock, ETF, forex pair, metal pair, or crypto symbol. Existing global data is reused when available.
| Parameter | Type | Required | Default / limits |
|---|---|---|---|
symbol | string | Yes | Ticker or pair; trimmed and non-empty |
frequency | enum | Yes | One of 5m, 15m, 1h, 4h, 1d |
asset_class | enum | No | equity |
For equity and etf, only 1d is accepted. Intraday requests require
forex or crypto. Supported examples include AAPL, SPY, EUR/USD,
XAU/USD, and BTC/USD. Futures, commodities, and index symbols are not
supported by this download contract.
Returns: The global symbol name and ID, plus download details.
Safety: External, state-changing operation; obtain approval.
Backtesting
lona_run_dry_run_backtest
Execute complete strategy source without saving it. Use this to validate authored or modified code before creating a saved strategy. It is a fixed environment check, not a substitute for a user-requested historical report.
| Parameter | Type | Required |
|---|---|---|
code | string | Yes |
Returns: The complete dry-run execution result, including validation or execution errors.
Safety: Executes code but does not save a strategy.
lona_run_backtest
Submit one asynchronous backtest for a saved strategy. Use symbol IDs returned
by lona_search_symbols_by_name or lona_list_symbols; never invent IDs. Use
an optimization for parameter sweeps instead of submitting many backtests.
| Parameter | Type | Required | Default / limits |
|---|---|---|---|
strategy_id | string | Yes | Saved strategy ID |
data_ids | string[] | Yes | At least one symbol ID |
frequency | string | Yes | Positive integer plus m, h, d, w, or M; must be available for every selected symbol |
start_date | YYYY-MM-DD | Yes | — |
end_date | YYYY-MM-DD | Yes | — |
parameters | object[] | No | Each item is { "name": string, "value": number | boolean } |
initial_cash | number | No | 100000 |
commission | number | No | 0 decimal rate |
leverage | number | No | 1 |
buy_on_close | boolean | No | false |
The request validates that the selected symbols contain the requested
frequency. The result contains a report_id (snake_case). Backtests move
through PENDING and EXECUTING, and then reach COMPLETED or FAILED.
Returns: { "report_id": "..." } and submission details.
Safety: Starts a credit-consuming asynchronous execution; obtain approval.
Optimizations
Optimization is the supported way to sweep one or two numeric parameter grids. The strategy must already be saved. Starting one always requires explicit user approval and may use a free optimization entitlement or credits. Optimization results are historical runs, not recommendations; do not label any run “best” or “top” unless the user explicitly asks for an extreme and you report the selected metric and direction.
lona_list_optimizations
List the user’s optimizations, newest first.
| Parameter | Type | Required | Default / limits |
|---|---|---|---|
skip | integer | No | 0 |
limit | integer | No | 10; 1–100 |
Returns: Paginated summaries with status, strategy, grids, metrics, period, iteration counts, and credit usage.
Safety: Read-only.
lona_get_optimization
Get one optimization and its current status, progress, grids, selected metrics, dates, simulation settings, credit usage, errors, and chart data.
| Parameter | Type | Required |
|---|---|---|
id | string | Yes |
The payload does not contain a “best” or “top” combination. Use
lona_list_optimization_results to inspect historical runs.
Safety: Read-only.
lona_get_latest_optimization_by_strategy
Get the most recent optimization for a strategy, or null when none exists.
| Parameter | Type | Required |
|---|---|---|
strategy_id | string | Yes |
Safety: Read-only.
lona_wait_for_optimization
Wait on the optimization progress stream until it completes, fails, or is cancelled. This can take up to 10 minutes.
| Parameter | Type | Required |
|---|---|---|
id | string | Yes; optimization ID |
Returns: Terminal status, completed/failed iteration counts, and any error.
Safety: Read-only.
lona_list_optimization_results
List bounded pages of historical runs for an optimization.
| Parameter | Type | Required | Default / limits |
|---|---|---|---|
id | string | Yes | Optimization ID |
sort_by | enum | No | Target metric order when omitted; otherwise iteration or one of the metrics below |
descending | boolean | No | Target direction when sort_by is omitted; explicit sort defaults ascending |
skip | integer | No | 0 |
limit | integer | No | 20; 1–100 |
Allowed metric values for sort_by, target_metric, and
additional_metrics are:
realized_pnl, total_return, cagr, calmar_ratio, recovery_factor,
sharpe_ratio, maximum_drawdown_percentage, std_dev_returns,
profit_factor, payoff_ratio, expectancy, average_trade,
percentage_of_winning_trades, avg_bars_held, hpr_drawdown_ratio, and
number_of_trades. CAGR and Calmar require periods of at least one year for
ordinary optimizations and cannot be WFA targets.
When all runs are requested, continue with skip += limit while the response
indicates another page.
Returns: Iteration, swept parameters or excluded_period, status,
available statistics, and errors.
Safety: Read-only.
lona_cancel_optimization
Cancel a pending or executing optimization. Remaining work may refund unused reserved credits.
| Parameter | Type | Required |
|---|---|---|
id | string | Yes |
Safety: State-changing; requires explicit user approval.
lona_run_optimization
Submit a one- or two-parameter grid optimization for a saved strategy.
| Parameter | Type | Required | Default / limits |
|---|---|---|---|
strategy_id | string | Yes | Saved strategy ID |
name | string | Yes | Non-empty |
data_ids | string[] | Yes | 1–10 symbol IDs |
frequency | enum | Yes | 5m, 15m, 1h, 4h, or 1d; available for every selected source |
start_date | ISO 8601 string | Yes | — |
end_date | ISO 8601 string | Yes | — |
grids | object[] | Yes | 1–2 items, each { name, min, max, step }; step positive and max >= min |
parameters | object[] | No | []; fixed { name, value }, where value is a number or boolean |
simulation_parameters | object | No | { initial_cash: 100000, commission_schema: { commission: 0, leverage: 1 }, buy_on_close: false } |
target_metric | enum | Yes | One of the metric values listed above |
target_direction | enum | Yes | maximize or minimize |
additional_metrics | enum[] | No | []; metric values listed above |
use_free_optimization | boolean | No | false; set true only when the user explicitly asks to use one |
simulation_parameters must contain exactly initial_cash,
commission_schema.leverage, commission_schema.commission, and
buy_on_close. The server adds its internal lookahead setting; agents do not
send it.
Returns: { "success": true, "optimization_id": "..." } and tracking
details.
Safety: Starts a credit-consuming asynchronous operation; obtain approval.
lona_run_time_window_optimization
Run one backtest per excluded period with all strategy parameters fixed. Each period blocks new entries; exits from existing positions remain allowed.
Uses the same required strategy, name, data, dates, simulation settings, target
metric, and direction as lona_run_optimization, but takes excluded_periods
instead of grids. It does not accept use_free_optimization.
Each excluded period must explicitly include both fields:
weekdays: one or more integers, Monday0through Sunday6, ornull.time_window:{ "start_time": "08:00", "width_hours": 1 }, ornull. The start is a UTC clock time and the width is greater than 0 and at most 24 hours. Time-window exclusions require intraday data.
At least one field must be non-null. With both set, only time windows starting on those weekdays are excluded. Intervals include the start and exclude the end.
For Day-of-Week, send one period per trading weekday, for example:
{
"excluded_periods": [
{ "weekdays": [0], "time_window": null },
{ "weekdays": [1], "time_window": null }
]
}For Time-of-Day, send one period per selected UTC slot:
{
"excluded_periods": [
{ "weekdays": null, "time_window": { "start_time": "08:00", "width_hours": 1 } },
{ "weekdays": null, "time_window": { "start_time": "09:00", "width_hours": 1 } }
]
}These snippets show the period field only; include the common required inputs when calling the tool. Use real symbol IDs and check their session calendar and bar frequency before building the period list.
Returns: An optimization_id. Wait with lona_wait_for_optimization, read
with lona_get_optimization and lona_list_optimization_results, or display
with lona_show_time_window_optimization. Each bar describes the full backtest
with that period blocked, not the profit earned during that period. Arbitrary
combined periods may display a table rather than a weekday/slot chart.
Safety: Costs 2 credits per excluded period, with no free optimization entitlement. State the count and total cost and obtain approval before calling.
Optimization display tools
lona_show_optimization displays a grid run’s charts and table;
lona_show_optimization_results displays a page of its results. Both take
id; the results display also supports paging and sorting.
lona_show_optimizations displays a paginated list. Use
lona_show_time_window_optimization with id for weekday and time-slot runs.
Display tools are read-only and should be called when the user asks to see
results; use the corresponding get/list tools for analysis.
Walk-forward analysis
WFA preview and execution require Pro or above. Reading an existing analysis uses the account’s normal ownership checks. See the WFA guide for the UI workflow and how to interpret the results.
lona_preview_walk_forward_analysis
Preview a saved strategy’s windows, total backtests, estimated credits, and
out_of_sample_share without creating a run or executing simulations.
| Parameter | Required | Format / default |
|---|---|---|
strategy_id | Yes | Saved strategy ID |
data_ids | Yes | 1–10 symbol IDs |
frequency | Yes | Available for all symbols: 1d, 4h, 1h, 15m, or 5m |
start_date, end_date | Yes | UTC YYYY-MM-DD; last full-period date is inclusive |
initial_in_sample_start, initial_in_sample_end | Yes | UTC YYYY-MM-DD; IS end is inclusive |
step | Yes | Positive integer value; unit: hours, days, months, or years |
grids | Yes | 1–2 numeric grids, each with name, min, max, positive step |
mode | No | rolling (default) or anchored |
parameters | No | Fixed { name, value } values; numbers or booleans; default [] |
simulation_parameters | No | Same defaults as a grid optimization |
target_metric | No | Default hpr_drawdown_ratio; CAGR and Calmar are excluded |
target_direction | No | maximize (default) or minimize |
additional_metrics | No | Default [] |
Only complete OOS windows are included. Always present the returned schedule, OOS share, backtest count, and credits. OOS share is a fraction of IS plus OOS; it describes the first cycle in anchored mode and each cycle in rolling mode. Returned window ranges include their first and last displayed UTC date or minute. The following OOS range starts immediately after IS; do not alter the returned dates or imply that adjacent periods overlap.
Safety: Read-only; does not consume execution credits.
lona_run_walk_forward_analysis
Uses the preview inputs plus a required non-empty name. Preview first,
then obtain explicit approval for the returned configuration and cost before
submitting the same settings. Each window re-runs its IS grid and tests the
selected combination OOS. The cost is windows × grid combinations × 0.2;
OOS tests are not charged separately. Free optimization entitlements do not apply.
Returns: The created analysis ID and progress information.
Safety: Creates a credit-consuming asynchronous run.
lona_list_walk_forward_analyses
List the user’s analyses, newest first. Optional strategy_id filters by
strategy; skip defaults to 0 and limit to 10 (maximum 25). Rows include
status, window counts, headline OOS metrics, WFE, and a web link.
lona_get_walk_forward_analysis
Takes required id. Returns configuration, progress, combined OOS metrics,
WFE, and every window’s dates, status, selected parameters, and IS/OOS results.
WFE is mean OOS daily return divided by mean IS daily return, as a percentage;
it is undefined when mean IS daily return is non-positive.
lona_wait_for_walk_forward_analysis
Takes required id and waits on progress until the run completes, fails, or
is cancelled. Retrieve the analysis afterward to inspect windows and results.
Do not resubmit a run merely because it has not completed yet.
lona_show_walk_forward_analysis
Takes required id and displays the analysis’s metrics, stitched OOS equity
and drawdown, and per-window table. Use it when the user asks for a visual
report; use the get tool for analysis. List/get/wait/show are read-only.
Reports
lona_list_reports
List backtest reports, newest first, optionally filtered by strategy.
| Parameter | Type | Required | Default / limits |
|---|---|---|---|
skip | integer | No | 0 |
limit | integer | No | 20; 1–50 |
strategy_id | string | No | Filter by saved strategy ID |
Returns: Paginated report summaries and performance statistics.
Safety: Read-only.
lona_get_report
Get one report by ID. Pending and executing reports return status information; completed or failed reports include summary data, recent reconstructed trades, per-symbol performance, diagnostics, and chart data when available.
| Parameter | Type | Required |
|---|---|---|
id | string | Yes; report ID |
Use lona_list_report_trades for the complete available trade history. The
report’s stored statistics are authoritative when reconstructed trade counts or
gross P&L differ because trade reconstruction excludes commissions and fees.
Safety: Read-only.
lona_list_report_trades
List a report’s reconstructed round-trip trades with bounded pagination.
| Parameter | Type | Required | Default / limits |
|---|---|---|---|
id | string | Yes; report ID | |
skip | integer | No | 0 |
limit | integer | No | 50; 1–200 |
Returns: Entry/exit times, prices, quantity, gross P&L, P&L percentage,
total, and has_next. A page is not the complete history when has_next is
true.
Safety: Read-only.
lona_wait_for_reports
Wait for every requested backtest report to reach a terminal state.
| Parameter | Type | Required |
|---|---|---|
report_ids | string[] | Yes; at least one report ID |
This field is plural and snake_case. Pass the array returned by one or more backtest submissions, for example:
{"report_ids": ["report-123", "report-456"]}Returns: { "results": [{ "report_id": "...", "status": "COMPLETED" }] }
for terminal COMPLETED or FAILED statuses.
Safety: Read-only.
Gateway-only agent routes
The gateway also exposes authenticated agent routes under /api/v1/agent for
interviewing and AI code generation. These routes are not part of the 24-tool
MCP catalog:
| Route | Input |
|---|---|
POST /api/v1/agent/interview | { messages: [{ role: "user" | "assistant", content }], provider?, model? } |
POST /api/v1/agent/interview/stream | Same input; streamed response |
POST /api/v1/agent/generate | { requirements: [{ description, importance?, category }], provider?, model? } |
POST /api/v1/agent/generate/stream | Same input; streamed response |
POST /api/v1/agent/strategy/generate | { description, provider?, model? }; minimum description length 10 |
POST /api/v1/agent/strategy/create | { description, name?, provider?, model? }; description 10–10,000 characters |
POST /api/v1/agent/strategy/create-async | Same input; returns a jobId with HTTP 202 |
GET /api/v1/agent/jobs/:id | Poll an async strategy-create job |
These endpoints require the permissions declared by the gateway
(agent:interview, agent:generate, and for strategy creation also
strategies:write).
Connection
For an HTTP MCP client, use:
{
"mcpServers": {
"lona": {
"type": "http",
"url": "https://mcp.lona.agency/mcp"
}
}
}OAuth-capable clients authenticate through the MCP endpoint’s OAuth flow. For direct gateway service-token authentication, see Agent Onboarding.