INITIATIVE / quantitative software engineering
Get free token Discuss a build
Reference

MCP documentation

What this is

quant-swarm exposes three MCP servers derived from the trading swarm: swarm-data-mcp (point-in-time data assembly, derived market/sentiment snapshots), swarm-warden-mcp (pre-trade invariant and leakage auditing), and swarm-gym-mcp (regime-fragility probing and the Shadow Tournament). No tool places, cancels, or routes orders, and no tool accepts provider credentials.

Authentication

Get a token at /mcp/ (free, instant). Set it in each server's environment: 

SWARM_MCP_ACCESS_TOKEN=121_xxxxxxxx

Hosted endpoints accept it as a Bearer credential over streamable HTTP. /api/mcp/verify reports plan, status (active | inactive | exhausted | expired), features, quota and the rates card. A Pro token whose credit pool is empty or past its 90-day window verifies with a non-active status and the free feature set.

Plans, quotas & the credit rate card

  • Free: 250 relay data calls/month, 10 symbols/call, 365-day backfill window. All warden checkers, derived market/sentiment/regime snapshots, cache stats, offline mode, and tournament.leaderboard. No hosted compute.
  • Credit packs (Pro): one-time packs — 10,000 credits (£19) or 100,000 credits (£149), valid 90 days from purchase, no subscription and no auto-renewal. Unlocks the full tool catalog, 50 symbols/call, the full backfill window, hosted compute and the Shadow Tournament.
  • Burst limit: 60 metered calls per 60 seconds per token, durable across instances.
Metered item Credits
relay data call (/data/bars, /data/enrich) 1
hosted single-shot Pro tool (features.build, warden.promotion_verdict, gym.label_regimes, gym.estimate_cloud_run) 1
hosted gym episode (gym.probe_fragility, gym.paired_preview) — 5 regimes × per_regime × seeds (× 2 genomes for paired) 1 per episode
tournament.submit (100 paired episodes vs the live champion) 200 · 100 with contribute=true
tournament.verdict · tournament.leaderboard · warden checkers · cache tools · any tool over local stdio 0

Hosted compute is charged before the tool runs via POST /api/mcp/meter; if the meter refuses or is unreachable the call is refused, never served unmetered. Local stdio execution is never metered.

Tool catalog

Server Free Pro
swarm-warden-mcp warden.validate_order · warden.cost_check · warden.explain_sizing · warden.validate_genome · warden.audit_features warden.promotion_verdict
swarm-data-mcp market.pulse · market.sentiment · market.regime · market.climate · pit.analysis (lite: 1 symbol, top families) · cache.stats · cache.offline features.build · cache.warm · market.microstructure · volume.forecast · market.screen · market.rank · pit.analysis (full: 10 symbols, every family, historical as_of)
swarm-gym-mcp tournament.leaderboard gym.label_regimes · gym.probe_fragility · gym.paired_preview · gym.estimate_cloud_run · tournament.submit · tournament.verdict

Every response is derived-only: ratios, percentile ranks, labels, buckets, and counts. Raw provider values are never echoed. Tools accept optional caller-supplied bars for symbols the shared cache does not carry.

PIT significance verdicts (pit.analysis)

pit.analysis reads the release-gated pit_analysis/v2 store and, per underlying, explains every (dataset|metric|horizon) family: rolling 52-week IR on a size/sector-neutralized metric vs neutralized returns, Newey-West two-sided p (lag ceil(horizon/5)), observation count, coverage and staleness. The verdict is explicit and never guessed: SIGNIFICANT (an L1 survivor of the same run: IR > 0 and Benjamini-Hochberg q ≤ 0.05), NOT_SIGNIFICANT (with the reason), NOT_JUDGED (below the 26-observation floor, stale, or diagnostic-only) or UNVERIFIED (no gate artifact / gate from another run / failed placebo). Point-in-time: release points after as_of are ignored; raw metric values are never returned.

Shadow Tournament

The swarm selects strategies by paired champion-vs-challenger replay on identical episode-seed paths across five labelled regimes, an ELO ledger, and statistical promotion gates. tournament.submit puts a genome into that arena:

  1. warden.validate_genome locally — returns the genome_hash; nothing is sent.
  2. tournament.submit(genome, contribute) → POST /api/mcp/tournament/submit. Charges 200 credits (100 with contribute=true), returns a job_id (HTTP 202). Payload: the genome parameter vector, its hash, the contribute flag — never symbols, bars or credentials. The strategy-contributor tier may additionally send a written disclosure and/or strategy_code: submitted code is never executed — it is read statically by the hosted LLM reviewer, stored as a structured explanation plus a code hash, and the raw code is discarded after review.
  3. The hosted runner replays the genome and the swarm's current champion over 5 regimes × 4 per regime × 5 seeds (100 paired episodes, above MIN_EPISODES=20) on the hosted daily-bar panel and computes: Wilcoxon paired p-value, bootstrap 95% CI of the delta, per-regime deltas, worst-regime margin, hard-constraint and lookahead violations.
  4. Outcome: CHALLENGER_BEATS_CHAMPION (p ≤ 0.05, positive mean delta, non-negative worst-regime margin, zero violations) · CHALLENGER_LOSES (any violation, or a significant negative delta) · INCONCLUSIVE. ELO updates for the challenger and the champion (K=16, start 1500).
  5. tournament.verdict(job_id) → GET /api/mcp/tournament/verdict (owner only, no charge). tournament.leaderboard → GET /api/mcp/tournament/leaderboard (12-char hash prefixes, no identities).

How the swarm selects. Two arenas. Replay: champion vs challenger on identical episode-seed paths across five labelled regimes, Wilcoxon paired test, worst-regime margin, deflated-Sharpe and PBO gates — the fast signal, and where your submission is scored. Forward league: every Sunday each league genome (champion, top-ELO challengers, contributed genomes, and a planner entrant whose weekend moves come from a learned model) seals its positions for the coming week; the commitment hash is stored before the week happens, and the next cycle settles every position against realised closes, net of that genome's own cost model, ranking the field on the identical real week and updating ELO. Each position is recorded as component moves (screen, entry, size, weekend) with decision-time state, so credit is assigned per move and regime. The league opened on 2026-09-02; the swarm runs unchanged for eight weeks to accumulate settlements. Promotion still requires the replay gates; the forward record is reported alongside.

Retention. contribute=false: the vector is deleted from the job record once scored; hash and outcome remain. contribute=true: you license the vector and outcome to the swarm's evolution loop, where it is registered as an external challenger under the same tier caps and promotion gates as the swarm's own mutants (Terms). The outcome is a tournament result, not a promotion: the promotion gate (deflated-Sharpe margin, PBO cap, monotonic trials ledger) runs inside the swarm's registry. Failed runs (panel unavailable, unscorable tier-B/C mutation) are refunded automatically.

Error codes

  • 401 — token rejected, revoked, or missing.
  • 402 — plan/quota refusal with a structured body (reason: quota_exceeded | credits_exhausted | credits_expired | plan_required | inactive) and an upgrade_url. Pro tools on free tokens return UPGRADE_REQUIRED envelopes on stdio; on the hosted endpoint a compute refusal is JSON-RPC -32003 with the same reason and the credits the call would have cost.
  • 429 — burst limit (60 calls/60s).
  • 5xx — service unavailable; provider details are never leaked to clients. A tournament dispatch failure returns 503 and refunds the charge.

Install

uvx --from quant-swarm swarm-data-mcp
uvx --from quant-swarm swarm-warden-mcp
uvx --from quant-swarm swarm-gym-mcp

Hosted endpoints: https://swarm-mcp-503318750546.europe-west1.run.app/mcp/data · /mcp/warden · /mcp/gym. Source: github.com/blink1217/trading-swarm-mcp. Not investment advice — see Terms.