MCP Tools Reference

Complete reference for all 18 Lona MCP tools. These tools are available to any MCP-compatible client (Claude.ai, Claude Code, ChatGPT, custom agents).

Overview

Safety Annotations

Every tool includes MCP safety annotations to help clients make informed decisions:

Credit Usage Envelope

Every tool response includes a usage object with credit consumption data for the current billing period:

{
  "content": [{ "type": "text", "text": "..." }],
  "usage": {
    "credits_consumed": 5,
    "credits_remaining": 95,
    "credits_total_monthly": 100,
    "period": "2026-02"
  }
}

Key behaviors

• Promotional mode (default): All tools cost 0 credits — usage is visible but credits never decrease.
• Per-tool costs: Operators can assign different credit costs per tool via MCP_TOOL_CREDIT_COST_MAP.
• Quota exhaustion: When credits are exhausted, tool calls return isError: true with a message containing "Monthly credit quota exhausted for {period}".
• Upgrade CTA: Depending on the detected MCP provider (Anthropic or OpenAI), the exhaustion message may include an upgrade URL. This is controlled by ANTHROPIC_SHOW_UPGRADE_CTA and OPENAI_SHOW_UPGRADE_CTA.
• Error responses: The usage envelope is present on all responses — successful results, errors, and quota exhaustion messages.
• Monthly rollover: Credits reset at the start of each calendar month.

Strategy Management

lona_list_strategies

List trading strategies with pagination support.

Returns: Array of strategy objects with id, name, description, version, language, created_at, updated_at.

Safety: readOnlyHint: true

lona_get_strategy

Get details about a specific trading strategy.

Returns: Strategy object with id, name, description, version, language, created_at, updated_at.

Safety: readOnlyHint: true

lona_get_strategy_code

View the Python Backtrader source code of a strategy.

Returns: Object with code field containing the Python source code.

Safety: readOnlyHint: true

lona_create_strategy

Upload existing Backtrader Python code as a new strategy.

Returns: Object with strategyId and confirmation message.

Safety: readOnlyHint: false, openWorldHint: true

Example:

{
  "name": "SMA Crossover",
  "description": "Buys when fast SMA crosses above slow SMA",
  "code": "class Strategy(bt.Strategy):\n    params = (('fast', 10), ('slow', 30))\n    ..."
}

lona_update_strategy

Modify an existing trading strategy. Creates a new immutable version.

Returns: Object with strategyId (new version), previousStrategyId, isNewVersion flag.

Note: Updates create a new version with a new ID. The returned strategyId represents the latest version.

Safety: readOnlyHint: false, openWorldHint: true

AI Strategy Generation

lona_create_strategy_from_description

Create a trading strategy from a natural language description. This is the recommended way to create strategies.

Returns: Object with jobId, status (“PENDING”), and polling instructions.

Pipeline stages: PENDING → GENERATING → SAVING → COMPLETED (or FAILED)

Note: This tool returns immediately. The returned jobId can be passed to lona_get_strategy_creation_status to check progress. Typical polling interval: 10-15 seconds (usually completes within 3-5 minutes).

Safety: readOnlyHint: false, openWorldHint: true

Example:

{
  "description": "A momentum strategy that buys when RSI crosses above 30 and sells when it crosses below 70, with a 2% trailing stop loss",
  "provider": "anthropic",
  "model": "claude-opus-4-6"
}

lona_get_strategy_creation_status

Check progress of an async strategy creation job.

Returns:

Safety: readOnlyHint: true

Market Data

lona_list_symbols

List available market data symbols for backtesting.

Returns: Array of symbol objects with id, name, description, data_type, is_global, metadata, created_at.

Safety: readOnlyHint: true

lona_get_symbol

Get details about a specific market data symbol.

Returns: Symbol object with id, name, description, data_type, is_global, metadata, created_at, updated_at.

Safety: readOnlyHint: true

lona_get_symbol_data

Preview actual OHLCV price data for a symbol.

Returns: Object with data array of OHLCV points (timestamp, open, high, low, close, volume).

Safety: readOnlyHint: true

Data Acquisition

lona_download_market_data

Download cryptocurrency market data for backtesting.

Returns: Object with symbol_id, name, symbol, interval, start_date, end_date, candle_count, size_kb.

Practical data limits by interval:

Safety: readOnlyHint: false, openWorldHint: true

Example:

{
  "symbol": "BTCUSDT",
  "interval": "1h",
  "start_date": "2024-01-01",
  "end_date": "2024-12-31"
}

lona_upload_market_data

Upload custom CSV market data for backtesting.

Returns: Object with symbol_id, name, rows, size_kb, columns_detected.

CSV requirements:

• Header row with column names
• Minimum 10 data rows recommended
• Maximum ~15 MB file size
• Auto-detects common column names and timestamp formats (ISO 8601, Unix timestamps, date-only, slash format)

Safety: readOnlyHint: false, openWorldHint: true

Backtesting

lona_run_backtest

Run a strategy against historical market data. Backtests execute asynchronously.

Returns: Object with reportId and message. Poll with lona_get_report_status.

Safety: readOnlyHint: false, openWorldHint: true

Example:

{
  "strategy_id": "abc-123",
  "data_ids": ["symbol-456"],
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "initial_cash": 100000,
  "commission": 0.001
}

lona_get_report_status

Check progress of a running backtest.

Returns: Object with status, progress, isComplete, isFailed.

Status values: PENDING → EXECUTING → PROCESSING → COMPLETED or FAILED

Safety: readOnlyHint: true

lona_get_report

Get backtest report summary with key performance metrics.

Returns: Report object with id, name, status, strategyId, totalStats (performance metrics), error, timestamps.

Key metrics included: total return, annualized return, Sharpe ratio, max drawdown, win rate, number of trades.

Safety: readOnlyHint: true

lona_get_full_report

Get comprehensive backtest results with trade history and per-symbol breakdown.

Returns: Full report with total_stats, trades array (entry/exit details), symbol_stats (per-symbol P&L), symbols list, error, stderr.

Note: If the backtest FAILED, the stderr field contains execution output for debugging.

Safety: readOnlyHint: true

lona_get_report_chart

Get interactive candlestick chart data with buy/sell markers.

Returns: Chart data with OHLCV candles, trade markers, equity curve fallback, status, mode (candlestick, equity, or empty).

Note: Only works for COMPLETED reports.

Safety: readOnlyHint: true

lona_list_reports

List backtest reports with optional filters.

Returns: Array of report objects with id, name, status, strategyId, totalReturn, sharpeRatio, trades, created_at, error.

Safety: readOnlyHint: true

Authentication

lona_register_agent

Provisions a session token for the AI agent. If already authenticated, the call is rejected to prevent accidental session resets. Call this tool only for initial setup in API-key mode.

Returns: Object with token, partner_id, partner_name, permissions, expires_at.

Registration methods:

• With LONA_AGENT_REGISTRATION_SECRET: Uses the fast path (no rate limits)
• Without a secret: Automatically requests an invite code (rate limited to 3/hour per IP, invite codes expire after 1 hour)

Important: The token is only returned once. The MCP server stores it automatically for subsequent tool calls.

Safety: readOnlyHint: false, openWorldHint: true

Error Codes

MCP Connection

Claude Code / Claude Cowork

{
  "mcpServers": {
    "lona": {
      "command": "npx",
      "args": ["@lona/mcp-server"],
      "env": {
        "LONA_GATEWAY_URL": "https://gateway.lona.agency",
        "LONA_API_KEY": "your-api-key",
        "LONA_USER_ID": "your-user-id"
      }
    }
  }
}

Claude.ai (OAuth)

• Endpoint: https://mcp.lona.agency/mcp
• Auth: OAuth 2.1 with PKCE (automatic via Claude.ai Connectors)

ChatGPT

Available as an MCP Action in ChatGPT with the same tool names and parameters.

Further Reading

• Agent Onboarding — Registration methods and token management
• Agent Workflow Guide — Step-by-step workflow from creation to analysis
• Getting Started — Platform introduction