MCP tools reference

This is the reference for the 24 tools currently registered by the Lona MCP server. 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	5	`lona_list_symbols`, `lona_search_symbols_by_name`, `lona_get_symbol`, `lona_get_market_data_sample`, `lona_download_market_data`
Backtesting	2	`lona_run_dry_run_backtest`, `lona_run_backtest`
Optimization	7	`lona_list_optimizations`, `lona_get_optimization`, `lona_get_latest_optimization_by_strategy`, `lona_wait_for_optimization`, `lona_list_optimization_results`, `lona_cancel_optimization`, `lona_run_optimization`
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: 1d only.
Forex, including metal pairs such as XAU/USD, and crypto: 5m, 15m, 1h, 4h, and 1d.
Symbol search accepts ticker/name forms such as AAPL, BTC/USD, XAU/USD, XAUUSD, and gold.

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_get_market_data_sample`

Inspect recent OHLCV candles before backtesting. Use the symbol’s reported availability to choose a stored frequency. The result is capped at 10,000 points and includes a CSV resource for the sample.

Parameter	Type	Required	Default / limits
`id`	string	Yes	—
`frequency`	enum	Yes	`5m`, `15m`, `1h`, `4h`, or `1d`
`limit`	integer	No	50; `1`–`10,000`
`start_date`	ISO 8601 string	No	Inclusive lower bound
`end_date`	ISO 8601 string	No	Inclusive upper bound; a date-only value covers that day

Date bounds may be calendar dates or date-times with an offset. They must be real ISO dates; impossible dates and loose formats are rejected.

Returns: Symbol ID/name, frequency, OHLCV points, and a CSV resource.

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, annualized_sharpe_ratio, maximum_drawdown_percentage, std_dev_returns, profit_factor, payoff_ratio, expectancy, average_trade, percentage_of_winning_trades, and avg_bars_held.

When all runs are requested, continue with skip += limit while the response indicates another page.

Returns: Iteration, swept parameters, 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 string, 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.

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.

MCP tools reference

Catalog

Common behavior

Credit

lona_get_credit_usage

Strategy authoring

lona_get_strategy_documentation

lona_list_strategies

lona_get_strategy

lona_create_strategy

lona_update_strategy

Symbols and market data

lona_list_symbols

lona_search_symbols_by_name

lona_get_symbol

lona_get_market_data_sample

lona_download_market_data

Backtesting

lona_run_dry_run_backtest

lona_run_backtest

Optimizations

lona_list_optimizations

lona_get_optimization

lona_get_latest_optimization_by_strategy

lona_wait_for_optimization

lona_list_optimization_results

lona_cancel_optimization

lona_run_optimization

Reports

lona_list_reports

lona_get_report

lona_list_report_trades

lona_wait_for_reports

Gateway-only agent routes

Connection

Related pages

`lona_get_credit_usage`

`lona_get_strategy_documentation`

`lona_list_strategies`

`lona_get_strategy`

`lona_create_strategy`

`lona_update_strategy`

`lona_list_symbols`

`lona_search_symbols_by_name`

`lona_get_symbol`

`lona_get_market_data_sample`

`lona_download_market_data`

`lona_run_dry_run_backtest`

`lona_run_backtest`

`lona_list_optimizations`

`lona_get_optimization`

`lona_get_latest_optimization_by_strategy`

`lona_wait_for_optimization`

`lona_list_optimization_results`

`lona_cancel_optimization`

`lona_run_optimization`

`lona_list_reports`

`lona_get_report`

`lona_list_report_trades`

`lona_wait_for_reports`