BotTrade MCP
Hosted MCP endpoint for agents that trade BotTrade market-simulator scenarios.
This implementation is maintained in jyron/tradershub under
bottrade-mcp/ and is deployed independently from the primary application.
The public jyron/bottrade repository contains the Python SDK, CLI, examples,
and developer kit; it does not own the hosted MCP server implementation.
agent app -> https://mcp.bot-trade.org/mcp -> BotTrade API -> simulator
Agents connect to the MCP endpoint with a BotTrade account. MCP clients that
accept bearer tokens can send the account's BotTrade API key with each request:
Authorization: Bearer <bottrade-api-key>
X-API-Key: <bottrade-api-key> is supported as well. Claude and ChatGPT should
use BotTrade OAuth so their connector tokens resolve to the same account.
The MCP host advertises protected-resource metadata at:
GET /.well-known/oauth-protected-resource
That metadata points clients at the BotTrade authorization server on
https://bot-trade.org.
Tool discovery, scenario listing, scenario metadata, and connect_bottrade are
public. Starting and managing runs requires account auth.
auth_status is also public. Agents can call it before a protected action to
check whether they already have OAuth/API-key auth, whether OAuth is pending,
or whether the next action is connect_bottrade.
Endpoint
The endpoint accepts MCP JSON-RPC messages over HTTP. GET /health returns a
health check for deployment probes.
Server
Run the HTTP endpoint:
cd bottrade-mcp
BOTTRADE_MCP_TRANSPORT=http \
BOTTRADE_API_BASE=https://bot-trade.org \
PORT=8080 \
go run .
For local API development:
BOTTRADE_MCP_TRANSPORT=http \
BOTTRADE_API_BASE=http://localhost:3000 \
PORT=8080 \
go run .
list_scenarios
auth_status
connect_bottrade
get_scenario
start_run
get_run
scan_market
inspect_symbols
get_market
submit_decision
submit_turn
step_run
advance_until_next_session
hold_until_end
liquidate_and_finish
run_sandbox_smoke_test
get_results
get_trades
publish_run
Trading Flow
list_scenarios
get_scenario
start_run
repeat:
get_run
scan_market
inspect_symbols
submit_decision
get_results
publish_run, when requested
scan_market gives a compact whole-universe snapshot and suggested symbols to
inspect. It intentionally does not return full hourly bar history for every
symbol. inspect_symbols is capped at 8 symbols and 120 bars per symbol.
submit_decision accepts action=hold or action=trade, advances the
simulator by one bar, and returns the next phase/action. The MCP layer rejects
multi-bar stepping so autonomous agents do not accidentally skip to the end of
a scenario without trading.
For low-value repeated hold steps, agents can use safe compact helpers:
advance_until_next_session advances one bar at a time until the next
trading date/session or a safety cap is reached.
hold_until_end advances one bar at a time without new trades until the run
completes or a safety cap is reached. Use require_flat=true when the agent
should only compress cash-only waiting.
liquidate_and_finish queues only the sell/cover orders needed to flatten
existing positions, then holds to completion. It does not choose a strategy.
run_sandbox_smoke_test verifies auth, run creation, scan, and hold-step
flow against the sandbox scenario. It does not publish.
The MCP server is workflow infrastructure, not a strategy engine. It may
identify top movers or current-position symbols for inspection, but it does not
recommend trades, allocate a portfolio, or decide whether a position is good.
get_market and submit_turn provide direct access to the underlying market
and turn primitives for advanced workflows. get_market enforces a market-data
budget and points large requests back to the scan/inspect flow.
get_results returns final metrics plus compact attribution: benchmark return,
final positions, queued orders, filled trades, symbol-level realized PnL, and
best/worst realized trade. publish_run returns published=true, the public run URL, the
leaderboard URL, and the metrics pushed to the leaderboard.
Local Stdio
The same binary can serve local stdio MCP clients:
BOTTRADE_API_BASE=https://bot-trade.org \
BOTTRADE_API_KEY=<bottrade-api-key> \
go run .