MCP Server

tradectl embeds a Model Context Protocol (MCP) server inside the running bot. This lets AI assistants like Claude Code query your bot's live state — positions, fills, shadow optimization, sessions, triggers, and more — in real-time through standardized tool calls.

How It Works

Claude Code / AI assistant
  │
  │  JSON-RPC over stdio or HTTP SSE
  ▼
tradectl mcp (stdio proxy)  ──POST──►  MCP SSE server (:9101)
                                           │
                                           ▼
                                      Arc<BotState>
                                           │
                                    ┌──────┴──────┐
                                    ▼              ▼
                              Live runner      Shadow engine

The MCP server runs as a tokio task inside the bot process. It reads from the same shared BotState that the runner writes to — positions, fills, tickers, and shadow results are always up-to-date with zero additional overhead.

The server uses SSE (Server-Sent Events) transport, the standard MCP wire protocol. Clients connect to /sse for the event stream and POST tool requests to /message.

Enabling MCP

Add a mcp block to your config:

{
  "mcp": {
    "enabled": true,
    "host": "127.0.0.1",
    "port": 9101
  }
}

Key	Default	Description
enabled	false	Start the MCP server
host	127.0.0.1	Bind address (localhost only by default)
port	9101	Server port

Claude Code Setup

Register the bot as an MCP server in Claude Code:

# Recommended — stdio proxy with JSON-RPC framing:
claude mcp add tradectl-bot -- tradectl mcp

# Direct HTTP (alternative):
claude mcp add --transport http tradectl-bot http://localhost:9101/sse

# Custom port:
claude mcp add tradectl-bot -- tradectl mcp --port 9102

Once registered, Claude Code can call any of the 23 tools below. Ask it natural questions like "how are my positions?" or "which symbols are performing best?" and it will call the right tools automatically.

Tools

Shadow Optimization (7 tools)

Tool	Description
get-shadow-results	Variant rankings: score, PnL%, drawdown, trade count, eligibility. Filter by symbol.
get-shadow-details	Drill-down into top variants: positions, exits, entries, win/loss, recent trades.
get-shadow-config	Per-strategy shadow config: ranges, evaluation window, promotion mode, thresholds.
get-promotion-pending	Candidates awaiting manual approval with score and margin over live.
get-promotion-history	Recent promotion history — accepted and rejected — with timestamps.
approve-promotion	Approve a pending promotion. The variant's params replace live params.
reject-promotion	Reject a pending promotion. Records the rejection in history.

Live Bot State (8 tools)

Tool	Description
get-bot-status	Strategies, symbols, mode (live/paper), uptime, balance, exchange provider.
get-positions	Open positions: side, avg entry, quantity, unrealized PnL, TP/SL prices. Filter by symbol.
get-recent-fills	Last N fills (default 20): timestamp, symbol, side, price, qty, realized profit. Filter by symbol.
get-strategy-state	Strategy internals: current params, indicator values, custom state. Filter by symbol.
get-market-data	Current bid/ask/spread per symbol.
get-active-orders	Pending entry orders and active exit orders (TP/SL) per symbol.
get-api-metrics	API call counts by operation type, rate limit weight usage %, pause state.
get-config	Full bot config with API keys and secrets redacted.

Sessions, Triggers & Health (3 tools)

Tool	Description
get-session-state	Per-symbol session state: streak, cooldown timer, size multiplier, threshold.
get-trigger-state	Active triggers, blacklisted symbols, pending trigger queues.
get-strategy-health	Per-symbol health: staleness alerts, edge decay status, pause state.

Computed Insights (3 tools)

Pre-calculated metrics — saves the AI from iterating raw data.

Tool	Description
get-performance-summary	Win rate, profit factor, avg win/loss, total PnL, PnL by symbol, current streak.
get-risk-assessment	Total unrealized PnL as % of balance, per-position distance to TP/SL, exposure breakdown.
get-symbol-comparison	All symbols ranked: trade count, win rate, PnL, avg PnL per trade, position state.

Strategy & Control (2 tools)

Tool	Description
get-strategy-description	Strategy documentation from STRATEGY.md. Returns one or all strategy docs.
resume-strategy	Resume entries for a symbol paused by edge decay.

Security

• Localhost only by default. External access requires explicitly setting host: "0.0.0.0".
• No authentication needed for localhost connections.
• get-config redacts API keys, secrets, and Telegram tokens before returning.
• Only 3 tools perform writes: approve-promotion, reject-promotion, resume-strategy. No tool can place orders, modify strategy params directly, or stop the bot.

STRATEGY.md

Strategy authors can write a STRATEGY.md file in their crate root documenting how the strategy works, its parameters, and intended market conditions. The pipeline:

1. tradectl build copies STRATEGY.md alongside the compiled binary
2. tradectl run loads it at startup
3. MCP tool get-strategy-description returns the full markdown
4. The AI agent includes it in its system prompt for strategy-specific context

Example Queries

Once MCP is connected, you can ask Claude Code questions like:

• "What's the current PnL across all symbols?"
• "Which symbols are underperforming?"
• "Are there any pending shadow promotions? Show me the details."
• "Why hasn't ETHUSDT traded in the last hour?"
• "What's my current risk exposure?"
• "Approve the shadow promotion for BTCUSDT."
• "Is any symbol paused by edge decay?"