@quantventure/mcp

Stdio MCP server for QuantVenture.

Lets Claude Desktop, ChatGPT custom GPTs, the MCP Inspector, or any other client that speaks the Model Context Protocol read your QuantVenture build — watchlists, strategies, backtests, the concept guide — and optionally manage watchlists and run backtests on your behalf.

Tokens come in two flavors:

• Read-only (recommended): the assistant can summarize your build, explain rules, and analyze backtests. Cannot create or modify anything.
• Read + write (advanced): adds the ability to create / modify / delete watchlists and run backtests. Pick the flavor at token-creation time in Settings → Integrations.

Always off-limits. Neither token flavor can place real or paper orders, approve pending alerts, change live-trading toggles or daily caps, manage broker connections, or revoke MFA. The MCP surface intentionally has no scope for any of it. Anything that touches real money flows through the QuantVenture UI behind 2FA + per-order approval.

Quick start

1. Generate an access token

Sign in to QuantVenture, open Settings → Integrations → AI access tokens, enter a label ("My Claude Desktop"), and click Generate token. Copy the token — it's shown exactly once.

2. Configure your MCP client

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "quantventure": {
      "command": "npx",
      "args": ["-y", "@quantventure/mcp"],
      "env": {
        "QUANTVENTURE_TOKEN": "qvt_paste_your_token_here"
      }
    }
  }
}

Restart Claude Desktop. You should see "quantventure" in the MCP server list with 12 tools available (8 read + 4 write).

Local development (using a clone)

If you've cloned the QuantVenture repo and want to run the MCP server from source rather than the npm package — handy when testing changes against your local dev server:

{
  "mcpServers": {
    "quantventure": {
      "command": "node",
      "args": ["C:\\path\\to\\QuantVenture\\mcp\\dist\\index.js"],
      "env": {
        "QUANTVENTURE_TOKEN": "qvt_paste_your_token_here"
      }
    }
  }
}

Run npm install && npm run build in the mcp/ directory first.

3. Optional: point at a different deployment

By default the server hits the hosted production URL. To talk to a local dev server or a staging deployment, set QUANTVENTURE_API_URL:

"env": {
  "QUANTVENTURE_TOKEN": "qvt_...",
  "QUANTVENTURE_API_URL": "http://localhost:3000"
}

Tools

Read tools (any token)

| Tool | What it returns | |------|------------------| | quantventure_get_flow | One-shot snapshot of your whole build (watchlists, strategies, brokers). Best first call. | | quantventure_list_watchlists | All watchlists with their symbol arrays. | | quantventure_list_strategies | All strategies with live config + rolled-up counts. | | quantventure_get_strategy | Strategy detail with current rule version and recent backtests. | | quantventure_list_backtests | Recent backtests across all strategies, filterable by strategyId + limit. | | quantventure_get_backtest | Single backtest with full equity curve and trade ledger. | | quantventure_list_concepts | The QuantVenture concept guide (Sharpe, drawdown, live routing, etc.). Call once to ground your vocabulary. | | quantventure_get_concept | A single concept entry by id. | | quantventure_list_pending_alerts | Alerts the user's strategies have fired that are awaiting approval. Filterable by state + strategy. | | quantventure_get_alert | Single alert with the firing strategy's rule version, recent backtests, current quote, and 30-day fire history. Use for substantive second-opinion review. |

Write tools (read + write token required)

| Tool | What it does | |------|--------------| | quantventure_create_watchlist | Create a new watchlist. Symbols validated against the platform's market-data cache; unknown tickers fail with a list of misses. | | quantventure_modify_watchlist | Rename, recolor, change description, or add/remove symbols. Multiple changes batch into one update. | | quantventure_delete_watchlist | Permanently delete a watchlist. Cannot be undone. | | quantventure_run_backtest | Run a new backtest against an existing strategy. Goes through the same engine + tier-cap as the UI. | | quantventure_propose_strategy | Propose a new strategy as a 24-hour draft. Returns a review URL the user opens to commit the strategy via the rule builder. This tool does NOT save the strategy directly — the user must click Save in the UI for it to land. |

Tokens without the matching write scope get a 401 from the API and the tool fails with a clear "your token may be missing the required scope" message.

How the propose flow works

1. Assistant calls quantventure_propose_strategy with a full spec (name, conditions, sizing, risk, etc.) plus a one-line summary for the drafts list.
2. The platform stores the spec as a StrategyDraft row with a 24-hour TTL — not as a real strategy yet.
3. The tool returns { draftId, reviewUrl }. The assistant should present the reviewUrl to the user explicitly.
4. The user opens the URL → the rule builder loads pre-filled with the proposal, the user edits anything that doesn't look right, and clicks Save.
5. Save creates the real strategy and marks the draft consumed.
6. Pending drafts also show in a section at the top of /strategies for asynchronous review.

This is intentional: the assistant proposes, the user authorizes by clicking Save. Real-money execution still flows through the existing UI approval chain.

What an assistant can do with this

• Act as a second reviewer on pending alerts before you approve them. Ask "anything need my attention?" — the assistant lists what fired, pulls deeper context on the interesting ones (rule version + recent backtest stats + current quote + how often this strategy has fired lately), and gives you a substantive read. You still click Approve or Dismiss in the UI — there's no MCP tool to action alerts.

• Summarize the state of your build: "You have 4 strategies; 2 have been backtested this month, 1 is wired to live trading at a $1,000 daily cap. Of the 2 backtested, the Oversold Mean Reversion run outperforms with +12.4% return and a 1.4 Sharpe — but check the drawdown windows in the equity curve before drawing conclusions."

• Explain QuantVenture-specific terms in plain English by grounding in the platform's concept guide rather than guessing.

• Read a rule's conditions and explain what it does: "Your Volatility Compression Watch strategy fires when ATR(14) is below the 30th percentile of its 60-day range and Close crosses above the 20-day MA. The position sizing is 2% of equity per trade, stop-loss is 3%, take-profit 6%."

• Compare two backtests' stats side by side, or compute things the UI doesn't show (drawdown durations, trades clustered by month, etc.) using the raw equity curve + trade ledger from get_backtest.

What an assistant cannot do

Independent of token flavor:

• Place a paper or live order.
• Approve a pending alert.
• Change a strategy's daily cap, broker connection, or live-trading toggle.
• Enable or disable 2FA.
• Manage broker connections (add/edit/remove API keys).
• Issue or revoke MCP tokens.

These all remain interactive in the QuantVenture UI behind 2FA. The MCP surface intentionally has no scope for them — there's nothing to grant.

Security notes

• The token is stored only as a SHA-256 hash on the server. The plaintext is shown once at creation and never recoverable.
• Revoke any token instantly from the same Settings page. A revoked token returns 401 on every endpoint.
• Tokens are scoped to one user's workspace. Cross-workspace access is not possible.
• This server has no persistent storage; the token lives only in your MCP client's config.

License

MIT