@watb/mcp-server

Model Context Protocol (MCP) server for WATB. Exposes 40 tools that let any MCP-capable AI assistant — Claude Desktop, Claude Code, Cursor, VS Code, Continue.dev, etc. — design, backtest, optimise and promote crypto trading strategies on the WATB platform.

WATB is a live + paper + backtest crypto trading platform. This server turns the platform into a first-class AI workspace: the assistant drives the full strategy lifecycle (draft → backtest → sweep → walk-forward → publish) with the worker, the database and the seeded skill bundle in the loop.

Quick start

# 1. Generate an API key at https://watb.app/strategies/mcp
# 2. Configure (interactive, only asks for the API key; writes
#    ~/.watb/config.json with mode 0600 — never echoes the key):
npx -y @watb/mcp-server init

# 3. Sanity check:
npx -y @watb/mcp-server doctor

Then wire it into your MCP client (see Clients below). The minimal client config does not need an env block — the server reads the key from ~/.watb/config.json automatically.

{
  "mcpServers": {
    "watb": {
      "command": "npx",
      "args": ["-y", "@watb/mcp-server"]
    }
  }
}

What you get

• Mandatory session model. watb_session_start locks the pair, timeframe, period, balance and iteration target, and returns the active persona prompt, the mode skill (v4 or v41) and the must-pass goals. Backtests / sweeps / promotion all carry the session_id so server-side audit, iteration budgets and report cadence work out of the box.
• Worker auto-reserve. The first worker-bound tool call reserves the WATB worker for ~3 min (auto-extended by keepalive). Manual watb_reserve / watb_release are available but rarely needed.
• Candidate store (watb_remember_candidate). Avoid re-sending large strategy JSON across calls — store once, reference by candidate_id with an optional path → value patch. Lost on MCP server restart by design.
• Two strategy modes — v4 (single-direction flat strategy) and v41 (three market-state regimes: bull / bear / sideways with optional user-requested extras). Both validated by the same Pydantic pre-flight.
• Guarded saves and promotion. watb_save_strategy and watb_promote_candidate accept structured guards (monthly score, trade count, walk-forward overfit risk, …) and refuse unsafe writes unless force: true.
• Built-in optimisation pipeline. watb_sweep, watb_sweep_then_backtest_top_n, watb_walk_forward, watb_time_filter_heatmap, watb_correlate, watb_compare.
• Live indicator + metadata catalog. watb_list_indicators returns the worker's own registry (params, defaults, multi-output dot notation); watb_indicator_preview previews real values with full date-range support (new in 0.2.x).
• Remote skill + hint + persona bundle. Skills (strategy-schema, v41-three-regime-strategy, first-run-checklist, …) and hint cards (fee_reduction, regime_design, derivative_usage, …) are served from the backend so improvements ship without a client release.
• Per-user memory. watb_add_memory / watb_search_memory / watb_get_memory keep the assistant's lessons-learned scoped to the authenticated user.
• Developer feedback loop. watb_developer_feedback files bugs, feature requests and free-form notes straight into the WATB triage queue.
• Raw access for debugging. watb_get_raw_result slices the full task payload by section (quick_diagnostics, condition_breakdown, per_regime_metrics, pnl_distribution, trades, …) so AI clients don't have to ingest the whole blob.

Tools (40)

The complete tool list, grouped by purpose. All names start with watb_. Call watb_doctor or watb_ping from inside an MCP client to get the live list straight from the server.

Bootstrap & connectivity

| Tool | Purpose | |---|---| | watb_ping | Auth + worker availability + server version sanity check. | | watb_doctor | Config-source + auth + worker + stale-key warnings. No secrets in output. | | watb_session_start | Mandatory first call. Locks session params, returns persona + mode skill + must-pass goals. | | watb_session_status | Current iteration count, last report time, params. | | watb_session_update | Mutate iteration_target, balance, risk, period, goal. | | watb_session_report | Required summary at iteration_target. Unlocks the next batch. |

Discovery

| Tool | Purpose | |---|---| | watb_get_pairs | Active pairs with first_candle/last_candle + index symbols (TOTAL, TOTAL2, TOTAL3, OTHERS). | | watb_get_metadata | Indicators, exit tactics, exit presets, risk guards, strategy guide. Call once per session. | | watb_get_publish_date_range | Standard 1-year publish-test window. | | watb_list_indicators | Live worker indicator registry (params, defaults, multi-output dot notation). | | watb_indicator_preview | Real values + min/max/mean/median. Optional from_timestamp / to_timestamp (ISO date, datetime, epoch s/ms). |

Strategy CRUD & candidate store

| Tool | Purpose | |---|---| | watb_remember_candidate | Store strategy/task snapshot, return short candidate_id (lost on MCP restart). | | watb_save_strategy | Save to AI Strategies library. Guarded; force:true for manual web drafts. | | watb_list_strategies | List caller's strategies; optional folder / visibility filters. | | watb_fetch_strategy_by_id | Fetch existing AI strategy by id. | | watb_validate_strategy | Debug-only preflight. watb_run_backtest already preflights. |

Backtest & optimise

| Tool | Purpose | |---|---| | watb_run_backtest | Run a backtest. Accepts strategy_json / candidate_id / source_task_id (+ optional patch). Omit dates unless the user explicitly requested a custom period; omitted dates use the publish-test window. Pass compare_exit_presets:true on the first real test of a new indicator/entry family to sequentially try balanced/aggressive/conservative and continue from the best candidate_id; do not repeat it for small threshold patches. If inline strategy_json uses a timeframe below 15m, pass force:true so auto-session start is allowed. | | watb_sweep | Parameter grid search. Cap max_combinations: 500. Multi-axis ranges via sweep_ranges. | | watb_sweep_then_backtest_top_n | Sweep → full-backtest top N → apply guards in one call. | | watb_walk_forward | Rolling fold overfit detection. Must not return HIGH before promote. | | watb_promote_candidate | Validate → backtest → guards → optional walk-forward → save IF safe. | | watb_correlate | Multi-strategy concurrent-position overlap. | | watb_compare | 2–N task delta analysis vs baseline. | | watb_time_filter_heatmap | Late optimisation: UTC-hour / WATB-weekday attribution → suggested blocked_hours / blocked_days after the core edge is stable. |

Inspect & audit

| Tool | Purpose | |---|---| | watb_history | Recent backtest tasks (task_id, name, symbol, core metrics). | | watb_get_raw_result | Section-sliced raw task JSON (summary / quick_diagnostics / per_regime_metrics / trades / …). | | watb_get_trades | Filtered, paginated trade rows. | | watb_record_iteration | Mark a successful iteration as persistent or attach a changes note. | | watb_get_failed_iterations | Iterations the session dropped from context. |

Worker reservation

| Tool | Purpose | |---|---| | watb_reserve | Manual reserve (worker calls auto-reserve already). 3-min TTL with keepalive. | | watb_release | Release the worker — resumes background intake. |

Remote knowledge (persona / skills / hints)

| Tool | Purpose | |---|---| | watb_get_persona | The WATB strategy-designer persona prompt. | | watb_list_skills_remote | Skill names served from the backend. | | watb_read_skill_remote | Full skill body by name (strategy-schema, first-run-checklist, v41-three-regime-strategy, …). | | watb_get_hints | Public hint cards, filterable by category (fee_reduction, derivative_usage, regime_design, overfit_avoidance, …) or q. | | watb_get_hint | Single hint card by id. |

Per-user memory

| Tool | Purpose | |---|---| | watb_add_memory | Save a private note tied to the caller. shared_consent:true (default) allows anonymised aggregation. | | watb_search_memory | Substring search across caller's notes. | | watb_get_memory | Fetch a single note by id. |

Feedback

| Tool | Purpose | |---|---| | watb_developer_feedback | File a bug / feature / suggestion / note straight into the WATB triage queue. "We are listening." |

For the recommended end-to-end workflow, candidate/patch patterns and the guarded save/promote payload, call watb_read_skill_remote name="first-run-checklist" from inside your MCP client — it is the live source of truth and ships from the backend.

Clients

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "watb": {
      "command": "npx",
      "args": ["-y", "@watb/mcp-server"]
    }
  }
}

Restart Claude Desktop. You should see 40 watb_* tools.

Claude Code (CLI)

claude mcp add watb -- npx -y @watb/mcp-server
claude mcp list   # verify

If tools don't appear, run npx @watb/mcp-server doctor first to confirm the API key, then restart the Claude Code session.

Cursor

mkdir -p ~/.cursor && cp node_modules/@watb/mcp-server/templates/cursor.json ~/.cursor/mcp.json

Or copy the snippet from templates/cursor.json into your existing ~/.cursor/mcp.json.

VS Code (Continue / Cline / GitHub Copilot Chat)

templates/vscode.json ships a ready-to-paste MCP block. Adapt to your extension's config path.

Environment variable override

WATB_API_KEY and WATB_API_URL always win over ~/.watb/config.json. Useful for CI, Docker, multi-account hosts, or keeping the key out of the filesystem entirely:

{
  "mcpServers": {
    "watb": {
      "command": "npx",
      "args": ["-y", "@watb/mcp-server"],
      "env": { "WATB_API_KEY": "watb_mcp_..." }
    }
  }
}

CLI

| Command | Purpose | |---|---| | npx @watb/mcp-server init | Interactive setup. Prompts only for the API key and writes ~/.watb/config.json (0600). | | npx @watb/mcp-server doctor | Print config source, auth status, worker availability, stale-key warnings. No secrets in output. | | npx @watb/mcp-server (or watb-mcp) | Start the MCP server on stdio. Used by clients via command/args. |

All four bin names work: mcp-server, watb-mcp, watb-mcp-init, watb-mcp-doctor.

Config

~/.watb/config.json (created by init, mode 0600):

{
  "apiUrl": "https://mcp.watb.app",
  "apiKey": "watb_mcp_...",
  "log": { "level": "info" }
}

log.level accepts debug | info | warn | error. The server writes structured tool_call start / done / err lines to stderr so Claude Code, Cursor, etc. surface them in their logs panel.

Tool discovery troubleshooting

Some AI clients cache the tools/list response or only show a subset.

1. Call watb_doctor or watb_ping from inside the client — both print Available tools (N): ... straight from the live catalog.
2. Use canonical names exactly (watb_save_strategy, watb_run_backtest, watb_validate_strategy).
3. Restart / refresh the client so it re-runs tools/list.
4. If the client still hides a tool, treat the doctor / ping output as the source of truth.

Diagnostics

npx @watb/mcp-server doctor

watb_doctor and the CLI doctor share the same report. The report prints the active config source and warning state without printing any API keys.

Backtest summaries include compact indicator diagnostics when the worker emits them. Default summaries do not surface UTC-hour / weekday buckets; use watb_time_filter_heatmap explicitly for late time-filter optimisation. For full signal diagnostics, call:

watb_get_raw_result task_id=<id> section=quick_diagnostics

section also accepts summary | metrics | long_metrics | short_metrics | condition_breakdown | per_regime_metrics | per_regime_pnl_distribution | pnl_distribution | diagnostics | warnings | errors | trades | strategy_snapshot | all.

License

MIT — see LICENSE.