MCP Tools Reference

TradeStaq's MCP server exposes 45 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 (10 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.

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.

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.

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.

cancel_optimization_run

Cancel a run you started. Takes effect after the current experiment finishes, not instantly — confirm with get_optimization_status. Any improvement already saved stays saved.

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

Update a bot's risk configuration — leverage, position size, stop loss, take profit, or trade notifications — without redeploying it.

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