MCP Tools Reference

TradeStaq's MCP server exposes 47 tools organized into 10 categories. Each tool can be called by any MCP-compatible AI client.

Authentication Scopes

For remote OAuth clients, tokens carry one of three scopes, hierarchical — mcp:live implies mcp:paper implies mcp:read. Session-cookie (dashboard) users bypass scope checks entirely.

When a call needs a scope your token doesn't hold, the server returns 403 insufficient_scope. check_auth returns your current token's scope, tier capabilities, and Strategy Lab wallet balance — call it first to preflight what you can do before attempting a paid or live-money action. See Authentication for the full OAuth flow.

Tools that charge your Strategy Lab wallet (generate_strategy, start_optimization_run) follow a two-step confirm pattern: call once without acknowledgeCost to get a cost estimate with nothing charged or queued, then call again with acknowledgeCost: true after the user approves the spend.

Authentication (7 tools)

login

Sign in with email and password credentials. Returns an authentication token for subsequent requests.

authenticate

Start a browser-based OAuth flow — opens a login page in your browser, you authenticate there, and the token is saved automatically. No credentials enter the chat.

check_auth

Preflight check before invoking other tools. Returns the authenticated user, OAuth scope on the current token, tier capabilities (allowLiveTrading, allowAIBuilder, allowNewsTrading, allowMcpServer), Strategy Lab wallet balance, and the OAuth client name/expiry. Cached server-side for 30 seconds per token.

set_token

Manually set a JWT token for the current session — for headless environments, CI/CD, or passing tokens between systems.

connect_exchange

Connect a real exchange account with API credentials. Supports Binance, Bybit, OKX, Hyperliquid, and 10+ others. Keys are encrypted and never exposed back to the client.

create_paper_exchange

Create a paper-trading exchange with a simulated balance — no API keys required. Lets an agent test strategies, deploy bots, and place trades without risking real money.

Scope: mcp:paper or mcp:live. Session-cookie (dashboard) users can always call this.

logout

Sign out and invalidate the current session token.

Market Data (4 tools)

get_price

Get the current real-time price for a trading pair on a specific exchange — bid, ask, last price, 24h change.

get_candles

Fetch historical OHLCV candlestick data for a trading pair — for technical analysis, backtesting prep, or trend review.

list_exchanges

List every exchange TradeStaq supports, including markets, connection status, and feature support.

search_markets

Search for trading pairs across all connected exchanges.

Portfolio (2 tools)

get_portfolio

View total balance, holdings, allocation, and 24h P&L across all connected exchanges.

get_positions

List all open trading positions — entry price, current P&L, leverage, margin, liquidation price.

Strategies (12 tools)

list_strategies

Browse strategies — either the public marketplace or your own library.

get_strategy

Get full details for a strategy by ID — description, market/timeframe, performance stats, rating, and (if you own it or it's forkable) the code.

explain_strategy

Get a plain-English explanation of what a strategy does, its risk profile, and the market conditions it suits.

compare_strategies

Compare 2-5 strategies side by side on ROI, max drawdown, win rate, Sharpe ratio, rating, and active bot count.

create_strategy

Save a new strategy from existing TradeDroid code to your library. Use this when you already have the code (hand-written, or produced by generate_strategy).

update_strategy

Update one of your own strategies — name, description, category, tags, or the code itself. Code edits write to a draft version only; nothing live changes until you promote it.

generate_strategy

Generate a complete strategy from a natural-language description using AI (FORGE) — no coding required.

Scope: mcp:live. Wallet-charging — see Authentication Scopes above for the two-step confirm pattern.

list_strategy_versions

List the full version history for one of your own strategies — every stored version, its validation status, and which channel (stable, beta, or none) it currently serves. stable is what every bot without a channel override actually runs.

validate_strategy_version

Run the automated validation pipeline (syntax check, entry/exit logic check, quick real-data backtest) against the current draft version of a strategy. Required before that version can be promoted to stable. Async — poll list_strategy_versions and watch validationStatus go pending → running → passed/failed.

The backtest runs on the version's own primary timeframe (falling back to the strategy's, then 1h) with its multi-timeframe config, over a bounded window of about 2,160 candles capped at 90 days: 2 days of 1m, 8 of 5m, 23 of 15m, 45 of 30m, 90 of 1h and above. The window stretches to cover at least 20 candles of the highest MTF timeframe, but never past 8,640 candles.

compare_strategy_versions

Backtest a candidate version and the current stable version on the same candles, score both the way the Strategy Lab optimizer does, and judge whether the candidate is worse. Async: it returns a jobId at once; poll get_version_comparison every 30-60 seconds. A run takes from a few minutes to about two hours (6 pairs x 2 years of 4h is 12 backtests), and is cut at 120 minutes. Free: not billed, not counted against backtest quotas, and no orders are placed. One comparison queued or running per user. Only the strategy's author (or an admin) can run it.

Verdict. Each pair is scored per version, and the pairs are compared the way the optimizer judges a candidate against its baseline. The verdict is worse when the candidate is newly disqualified on a pair, loses money where the stable version did not, collapses on a pair, loses more pairs than it wins, becomes undersampled where the stable version was not, or its blended score falls below the stable version's. It is inconclusive when any pair errored or did not run, better when the blended score rises clearly and it wins more pairs than it loses, and not_worse otherwise. Both versions run with the same parameters source (their own defaults, or the preset's overrides) on the same full window, so the result is in-sample: it compares the two versions on history, it does not predict live results. The caveats list says so, and flags overlap with the window the candidate was optimized on.

get_version_comparison

Poll a comparison started with compare_strategy_versions. Returns the status and progress while it runs; once completed, per-pair and total metrics and scores for both versions side by side, the verdict with its reasons, the caveats, and freshness: whether the stable version is still the one compared against and whether either version was edited since. freshness.promotable is true only when the comparison would pass the promote gate at the default tolerance. A comparison stuck for 20 minutes without progress is reported as failed.

promote_strategy_version

Promote a specific version to the stable or beta channel. Promoting to stable is the step that actually changes the code every bot on the default channel runs — editing (update_strategy) or validating a version has no effect on deployed bots until this is called. stable requires validationStatus: 'passed'; beta has no gate.

With requireComparison: true, a stable promote is refused (409) unless a completed compare_strategy_versions run of exactly this version against exactly the current stable version, with neither edited since, judges it not worse. The refusal carries a code (comparison_missing, comparison_running, comparison_failed, comparison_stale_baseline, comparison_preset_mismatch, comparison_stale_preset, comparison_stale_inputs, comparison_inconclusive or comparison_worse) and the comparison summary. A comparison counts only for the preset it ran with: pass the same presetId to promote on a preset comparison; without presetId only a comparison run without a preset counts. Recommended flow: compare_strategy_versions, poll get_version_comparison until completed, then promote with requireComparison: true.

Strategy Lab (4 tools)

AI-powered strategy optimization — see the Strategy Lab overview for how the underlying engine works. Every capability here is also available from the dashboard.

start_optimization_run

Start an AI optimization run on one of your own strategies — repeatedly mutates the code, backtests each variant, and keeps only the improvements, walk-forward validated on data no experiment trained on. This is different from generate_strategy, which writes one new strategy from a description; this iteratively improves an existing strategy you already own.

Scope: mcp:live. Wallet-charging per experiment — see Authentication Scopes above. Only one run can be active per user at a time.

Multi-pair runs. With more than one pair in symbols, every candidate is tested on every pair. Pricing is $0.50 per experiment plus $0.10 per extra pair per experiment (up to $27 for 5 pairs x 30 experiments), billed per pair actually evaluated. The first call always returns a cost_estimate with a quoteId, the pairs, the maximum cost and an estimatedMinutes time estimate; a run time limit may cut the experiments requested (clampedFrom). Confirm by re-sending the same arguments with acknowledgeCost: true and the quoteId; the bill is never above the quote. If the price rose or the arguments changed, the response is a fresh estimate with quoteChanged: true to confirm again. A multi-pair result is only adopted if it beats the original on most pairs, wrecks no pair and loses money out of sample on no pair; otherwise it is held for you to review.

get_optimization_status

Check progress of a run started with start_optimization_run. Each experiment typically takes 1-2+ minutes — poll every 15-30 seconds rather than tight-looping. A completed or failed run stays queryable for 24 hours. Multi-pair runs report per-pair results (progress.bestPerAsset against progress.baselinePerAsset, and progress.validation.perAsset), and a run waiting to start shows its queue position and etaMinutes.

cancel_optimization_run

Cancel a run you started. Takes effect after the current experiment finishes, not instantly — confirm with get_optimization_status. The best version found so far is kept but held, so the strategy only changes if you accept it.

send_optimization_guidance

Inject live, free-text steering into a running optimization. Applies starting with the next experiment, not the one in flight — overwrites any previously-injected guidance for this run.

Backtesting (3 tools)

what_if_backtest

Run a backtest on a strategy against historical data. Async, typically 30-120 seconds.

get_backtest_results

Check status and results of a previously started backtest.

export_backtest

Get export links for a completed backtest — CSV and PDF download URLs.

Bot Management (9 tools)

list_bots

List all your bots with status and performance.

get_bot_status

Get detailed status, configuration, and live performance for a specific bot — run status, strategy/symbol/exchange, paper or live, P&L, win rate, trade count, risk config. Read-only.

deploy_bot

Deploy a strategy as a trading bot. Defaults to paper trading for safety — whether a bot trades real money is determined by the exchange account it's attached to, not by a flag alone.

Scope: mcp:paper for a paper exchange target; mcp:live for a live exchange target.

start_bot

Activate a bot so it starts opening new positions on its next scheduled interval. Newly deployed bots come up paused by default.

stop_bot

Stop a bot from opening new positions. Existing open positions stay open — close those separately with close_position. Reversible; restart with start_bot.

update_bot

Edit a deployed bot without redeploying it: rename it, switch it to another strategy or apply a preset, change its timeframe, execution mode or strategy parameters, or adjust its risk settings, notifications and stop-after-close. Everything you pass goes in one update, so a strategy switch never lands half-done.

• Merging. The bot's current settings are read first and your changes go on top: position sizing, spin settings and parameter overrides are merged, never wiped by a partial change.
• Size and leverage change only when you pass positionSizePercent / leverage, also when you switch strategy or apply a preset.
• Strategy or timeframe changes need the bot to be flat (no open position, no working order). Otherwise the change is refused with OPEN_POSITION and nothing is written: the new strategy would adopt a position it did not open. Pause it first with stopAfterClose: true, wait until get_bot_status shows no open position, then switch. A switch starts the strategy state over and drops the old strategy's parameters, preset and stale owed exits. A paused bot stays paused: start it with start_bot.
• Presets. presetId applies the preset as the dashboard does when you pick it: its strategy, parameter overrides, timeframe, execution mode and interval, and version. Anything you pass explicitly wins.
• Returns the resulting configuration (strategy, version and channel, timeframe, mode, parameter overrides, size, leverage, status) and any server warnings, such as the exchange not having enough candle history.

Scope: mcp:paper for a paper bot; any change to a live bot (including a rename) needs mcp:live.

delete_bot

Permanently delete a bot and its configuration — irreversible. Refused if the bot still has an open trade recorded; close_position and stop_bot it first.

export_bot_trades

Export a bot's trade history — every closed trade with entry/exit prices and P&L, plus a performance summary.

close_position

Close an open position at market price, fully or partially. Moves real money when the position is live.

Trade History (2 tools)

get_trade_history

View complete trade history — entry/exit prices, P&L per trade, timestamps, triggering strategy.

get_performance_metrics

Get aggregated performance metrics — total P&L, win rate, average return, Sharpe ratio, max drawdown — over 7d/30d/90d windows.

Copy Trading (2 tools)

list_top_traders

Discover top-performing traders on the leaderboard — win rate, total return, drawdown, followers.

follow_trader

Start copy trading a top-performing trader — their trades mirror automatically on your connected exchange.

Scope: mcp:paper for a paper exchange target; mcp:live for a live exchange target.

AI Advisor (2 tools)

suggest_strategies

Get AI-powered strategy recommendations based on current market conditions, portfolio, and risk tolerance.

get_market_context

Get a real-time market analysis snapshot — trend direction, volatility, support/resistance, sentiment.

Next Steps

• Setup Guide — Configure your AI client
• Authentication — How to authenticate
• Strategy Lab Overview — How AI optimization works
• Troubleshooting — Common errors and fixes