quantdinger-mcp 0.3.0

Model Context Protocol (MCP) server for the QuantDinger Agent Gateway: market data, runtime overview, explicit quick trading, indicator workspace, strategies, backtests, and experiments for AI agents (Cursor, Claude Code, Codex, OpenClaw, NanoBot, ...).

QuantDinger MCP server

Thin Model Context Protocol server that exposes a curated subset of the QuantDinger Agent Gateway (/api/agent/v1) as MCP tools, so AI clients that support MCP (Cursor, Claude-style desktop apps, OpenClaw, NanoBot, etc.) can drive QuantDinger without writing custom HTTP code.

This package is an additive integration. The Agent Gateway REST API remains the source of truth.

Security model

• Order placement is explicit and server-gated. place_quick_order requires T scope and confirm_order=true. If the token is live-capable (paper_only=false), the MCP call also requires confirm_live_trading=true, and the backend still requires AGENT_LIVE_TRADING_ENABLED=true.
• Runtime stop is allowed, gated, and explicit. MCP can read the runtime overview and stop a tenant-owned strategy, but stopping requires T scope and confirm_stop=true.
• Scope gating stays on the server. The MCP layer forwards your agent token; it cannot bypass allowlists or scopes.
• Defense in depth: MCP redacts known credential fields (api_key, secret, passphrase, …) in JSON responses. The Gateway also redacts strategy rows before returning them to agents.
• Bounded long jobs: stream_job_until_done caps event count and duration; wait_for_job caps poll time. Tune via env vars below.
• LLM cost guard: submit_ai_optimize requires confirm_llm_usage=true.
• Payload limits: indicator Python source is capped at 512 KiB on both Gateway and MCP client.

What it exposes

Read-class (R), Workspace write (W), Backtest-class (B), and explicit Trading-class (T) tools.

Tool	Class	Purpose
whoami	R	Inspect the calling token
check_health	—	Public liveness (no token)
list_markets	R	Markets the token may query
search_symbols	R	Symbols within a market
get_klines	R	OHLCV bars
get_price	R	Latest price
list_strategies	R	Tenant's strategies (compact)
get_strategy	R	One strategy (secrets redacted)
runtime_overview	R	Running strategy / position / pending-order overview
stop_strategy	T	Stop a tenant-owned strategy (confirm_stop=true)
place_quick_order	T	Place paper/live quick order (confirm_order=true)
list_jobs	R	Recent async jobs
get_job	R	Poll one job
wait_for_job	R	Poll until terminal or timeout
stream_job_until_done	R	Bounded SSE consumer
get_indicator_authoring_contract	R	Indicator I/O contract + starter template
validate_indicator_code	R	Sandbox validate without save
save_indicator	W	Persist to indicator library
list_indicators	R	Tenant indicator list
get_indicator	R	One indicator with code
create_strategy	W	Create stopped strategy (+ auto-save indicator)
update_strategy	W	Patch strategy fields (blocks status=running)
submit_backtest	B	Queue a backtest (strict_mode, strategy_config, indicator_params)
regime_detect	B	Synchronous regime detection
submit_experiment_pipeline	B	Queue legacy grid pipeline
submit_structured_tune	B	Queue grid/random tuning
submit_ai_optimize	B	Queue LLM optimization (requires confirm flag)
list_portfolio_positions	R	Manual portfolio positions
list_paper_orders	R	Recent paper orders

Install

From PyPI (recommended — works on any machine without cloning the repo):

pipx install quantdinger-mcp
# or, no install at all (cached on first run):
uvx quantdinger-mcp
# or, into a venv:
pip install quantdinger-mcp

Editable install for hacking on the server itself:

cd mcp_server
pip install -e .

Run

Configuration is env-only so the same binary works in desktop and cloud.

Variable	Required	Purpose
QUANTDINGER_BASE_URL	yes	e.g. http://localhost:8888
QUANTDINGER_AGENT_TOKEN	yes	a token issued via /api/agent/v1/admin/tokens
QUANTDINGER_MCP_TRANSPORT	no	stdio (default), sse, or streamable-http
QUANTDINGER_MCP_HOST	no	bind host for HTTP transports (default 127.0.0.1)
QUANTDINGER_MCP_PORT	no	bind port for HTTP transports (default 8000)
QUANTDINGER_TIMEOUT_S	no	upstream HTTP timeout (default 60)
QUANTDINGER_MCP_JOB_STREAM_MAX_EVENTS	no	SSE cap (default 200)
QUANTDINGER_MCP_JOB_STREAM_MAX_SECONDS	no	SSE time cap (default 300)
QUANTDINGER_MCP_JOB_POLL_MAX_SECONDS	no	wait_for_job cap (default 300)

stdio (desktop IDEs)

QUANTDINGER_BASE_URL=http://localhost:8888 \
QUANTDINGER_AGENT_TOKEN=qd_agent_xxxxx \
quantdinger-mcp

SSE / Streamable HTTP (cloud agents, remote IDEs)

QUANTDINGER_BASE_URL=http://localhost:8888 \
QUANTDINGER_AGENT_TOKEN=qd_agent_xxxxx \
QUANTDINGER_MCP_TRANSPORT=streamable-http \
QUANTDINGER_MCP_HOST=0.0.0.0 \
QUANTDINGER_MCP_PORT=7800 \
quantdinger-mcp

The server is then reachable at http://<host>:7800/. Use sse instead of streamable-http for clients that only support the older SSE transport.

Wire into a client

Local stdio client config

{
  "mcpServers": {
    "quantdinger": {
      "command": "quantdinger-mcp",
      "env": {
        "QUANTDINGER_BASE_URL": "http://localhost:8888",
        "QUANTDINGER_AGENT_TOKEN": "qd_agent_xxxxxxxx"
      }
    }
  }
}

Remote HTTP client config

For clients that connect to an MCP server over HTTP/SSE rather than spawning a subprocess, point them at the URL the server is bound to (e.g. http://your-host:7800) and let the client handle protocol negotiation.

Never put production exchange keys or admin JWTs in the MCP config — only agent tokens, scoped to the capabilities the client actually needs.

Recommended scopes:

• Indicator authoring and backtesting: R + W + B
• Runtime overview only: R
• Runtime stop from MCP: R + T (and call stop_strategy with confirm_stop=true)
• Quick order placement: R + T. Paper orders work with paper-only tokens; live orders additionally require paper_only=false, confirm_live_trading=true, and AGENT_LIVE_TRADING_ENABLED=true on the backend.