qtsurfer-mcp: dead default API domain (api.qtsurfer.com) + backtests/sweeps never complete

[leonardojgv]

REPORT: QTSurfer MCP Setup and Integration
Date: 2026-08-12

========================================
WHAT WORKED

1. Installation

   • Native qtsurfer-mcp binary installed via install.sh

2. Registration in Claude Code

   • claude mcp add with "user" scope
   • "qtsurfer" server available across all projects

3. Broken domain diagnosis

   • api.qtsurfer.com was tried first because it's the binary's built-in
     default (--url default) and the domain documented in the mcp-java
     README's example Claude Code config
   • It turned out to be a dead Vercel deployment
     (header x-vercel-error: DEPLOYMENT_NOT_FOUND)
   • Found the correct, live domain: api.qtsurfer.net (found empirically
     by trying the .net TLD as a hypothesis after .com failed — this
     domain is NOT mentioned anywhere in the mcp-java or strategy-skills
     documentation; worth flagging to QTSurfer as a doc gap)
   • Reconfigured the server with --url pointing to api.qtsurfer.net

4. Authentication

   • The API key worked correctly against the .net domain
   • Final status: Connected

5. Data exploration

   • list_exchanges -> Binance
   • list_instruments -> 1,872 pairs available
     BTC/USDT with data from 2026-03-30 to 2026-08-12

6. Strategy authoring

   • Cloned the QTSurfer/strategy-skills repo (git clone; npx skills add
     was blocked by the permission classifier)
   • Built EmaCrossoverStrategy: 9/21 EMA crossover using CrossDetector

7. Bug found and fixed

   • The first sweep failed because a @StrategyProperty without an
     explicit JavaBean setter cannot be swept
   • Added setFastPeriod / setSlowPeriod / setWindowSeconds
   • This is not documented in the official skill

========================================
WHAT FAILED

1. Backtest 6FEFDG2wYsejzk4hiOc10O
   BTC/USDT, 3 days (2026-08-10 -> 2026-08-12)
   Result: got stuck in EXECUTING indefinitely (10+ min with no state
   change). There is no cancel operation for individual backtests
   (only for sweeps). Abandoned.

2. Sweep swp_76ef979908fd2f3b (66 runs)
   Error: NoSuchMethodException: setSlowPeriod
   Cause: missing JavaBean setters on the strategy

3. Sweep swp_024500d618deac2a (window 2026-08-11 -> 2026-08-12, 1 day)
   Error: "Tiered data not ready for BTC/USDT: 24 missing hours"
   Cause: window sitting right at the most recent edge of available data

4. Sweep swp_41006933b729575d (window 2026-08-04 -> 2026-08-05, 1 day)
   Same tiering error, despite being far from the recent edge.
   Conclusion: a 1-day window appears insufficient for data
   warm-up/tiering, regardless of how recent it is.

5. Sweep swp_1d2af950d3c9055b (66 runs, 4-day window 07-01 -> 07-05)
   Passed data validation and went RUNNING, but did not advance past
   0/66 runs for several minutes. Cancelled manually.

6. Sweep swp_eb838ace9300f186 (6 runs, same window 07-01 -> 07-05)
   Error: "prepared dataset must contain at least one ticker"
   Likely cause: dataset cache left in a bad state by the previous
   cancelled sweep on the same window/instrument.

7. Sweep swp_0e2f88ff0d1ae06f (6 runs, new window 06-01 -> 06-05)
   Passed data preparation (RUNNING) but also never advanced past 0/6.
   Cancelled by the user.

========================================
CONCLUSION

MCP server connectivity and configuration ended up fully functional:
connection, authentication, and the instrument catalogue all worked
without issues.

The recurring problem was on the QTSurfer execution engine/backend
side: no run ever reached completion, neither the individual backtest
nor any sweep, regardless of date window or grid size. This suggests
the engine's compile-and-execute pipeline was slow or degraded on the
day of testing.

Recommendation: report this to the QTSurfer team, or retry later.

========================================
NOT YET TESTED

Of the 11 tools exposed by the qtsurfer MCP server, 9 were exercised
(list_exchanges, list_instruments, submit_backtest, get_job_status,
submit_sweep, get_sweep_status, cancel_sweep, list_jobs, version).
Two remain untested because they require a completed run:

• get_equity_curve: needs a jobId from a COMPLETED backtest
• get_sweep_sensitivity: needs a sweep with leaderboard rows

version was called separately and confirmed:
qtsurfer-mcp 0.10.0
API: https://api.qtsurfer.net/v1

========================================
RELEVANT FILES

Fixed strategy (with setters): EmaCrossoverStrategy.java (kept in the
session scratchpad)

MCP configuration (claude mcp get qtsurfer):
Args: --url https://api.qtsurfer.net/v1
Scope: user

[mrmx]

Thanks for the detailed writeup — this was genuinely useful. Triaged into pieces:

Fixed and shipped

• cancel_backtest tool (mcp-java 0.10.2) — the backend has always had a single-backtest
  cancel endpoint and the SDK already wrapped it; only the MCP tool surface was missing it.
  A stuck backtest can now be cancelled the same way a stuck sweep can.
• @StrategyProperty + JavaBean setter requirement, documented in strategy-skills
  (qtsurfer-java-strategy skill) — and the skill's own dual-EMA example, which had the
  exact bug you hit, is fixed to match.
• Split out as its own issue, since it needs a product decision rather than a doc tweak:
  Default --url points at a dead domain (api.qtsurfer.com); api.qtsurfer.net undocumented #4 (dead .com default / undocumented .net).

Likely already resolved, worth a re-test

The "Tiered data not ready: 24 missing hours" errors (items 3 and 4 in your report,
including the one far from the recent edge) and the "prepared dataset must contain at
least one ticker" after a cancelled sweep (item 6) look like the same class of bug we
root-caused and fixed the same day you were testing — a stale cached verdict from an
earlier attempt getting replayed instead of the request getting a fresh retry. If your
testing session ran before that landed, these should behave correctly now. If you still
see either after a fresh attempt, that's a different bug and we'd want to know.

Still open, under investigation

The single backtest and the two sweeps that got stuck in EXECUTING/RUNNING and never
advanced (items 1, 5, 7) aren't explained by the above — that one's still being looked
into on our end.

Not addressed yet

The get_equity_curve / get_sweep_sensitivity gap is just a consequence of nothing
completing — should sort itself out once the above is confirmed fixed or resolved.

[mrmx]

Follow-up: root-caused and fixed the "stuck in EXECUTING/RUNNING with zero progress" issue
(items 1, 5, 7 in the original report).

Any strategy using java.time.Duration — the documented pattern for
.window(name, Duration.ofSeconds(n), listener) — was failing at execution time with a
sandbox classloader rejection. That failure then permanently drained the affected queue of
a worker with no replacement, so a single such job could leave a queue unable to process
anything ever again. Fixed on both ends: java.time/java.text are now whitelisted, and
the worker pool replaces a lost worker instead of running one short forever. Deployed to
pre and verified live — a backtest using Duration now completes normally.

Separately, still open: submit_sweep on some windows fails instantly with "prepared
dataset must contain at least one ticker" (your item 6) — confirmed this is a distinct bug
from the one above, still being investigated.

[leonardojgv]

Update: retested on 0.10.3 — the two main issues are fixed 🎉

Upgraded from 0.10.0 to 0.10.3 and re-ran the same checks from the original report.

Confirmed fixed

• Dead default domain. api.qtsurfer.com is still a dead Vercel deployment
  (x-vercel-error: DEPLOYMENT_NOT_FOUND), but the 0.10.3 default --url now correctly points
  at api.qtsurfer.net, which works.
• Backtests/sweeps stuck forever. This was the big one. Re-submitted the same backtest that
  had been stuck in EXECUTING for days — it completed within minutes of upgrading. Ran several
  fresh backtests and sweeps afterwards (grid and random samplers, get_equity_curve,
  get_sweep_sensitivity marginals and interaction surface) — all completed normally. Whatever
  sdk-java 0.10.1's JWT-refresh fix addressed looks like it was the actual root cause of the
  hangs, not just the 401s it explicitly targeted.
• No cancel for individual backtests. cancel_backtest (0.10.2) is present and accepts
  requests correctly.

New findings from further retesting have been split out to #6 to keep this thread to the
original report and fix confirmation.

[leonardojgv]

Moved this finding (walk-forward sweeps never progressing) to #6, along with two other new findings from the same retesting session — keeping this thread to the original report + fix confirmation.

[mrmx]

Independent confirmation (via qtsurfer-mcp 0.10.4):

Both original blockers from this report are resolved and confirmed on my side too:

• Dead default domain: the built-in --url now points at api.qtsurfer.net (shipped in 0.10.3); hermes mcp test qtsurfer connects cleanly.
• Backtests/sweeps never completing: backtests and sweeps now complete normally end-to-end.

The remaining findings from this thread (metric reporting, lhs sampler, cancel_backtest race, walkForward, sweep param injection) have all been split upstream into #5, #6 and #7, so this original report no longer has anything outstanding.

Suggest closing this one. Happy to close it myself if you'd like.