ctrader-mcp-servers

Top-5 critical quirks (inline teaser)

The following 5 quirks are the most consequential as of the audit date. Full Detect / Workaround / Verify-fixed / Removal-criteria content lives in references/known-quirks.md; the rows below are link-only teasers. See also references/self-healing-playbook.md for the named recovery patterns.

Self-healing principle

Both ctrader-remote-mcp and ctrader-local-mcp ship as-is with documented runtime behaviors last re-verified on 2026-05-14 against rest-proxy 1.0.18 (Remote) and local build observed-on 2026-05-14 (Local). Six Remote quirks remain ACTIVE on 1.0.18 (Q-R1, Q-R2, Q-R3, Q-R5, Q-R8, Q-R10). Two quirks had their error-message format refined (Q-R4 and Q-R7 now return plain-string error envelopes with actionable hints instead of JSON envelopes — both DETECT signatures cover both formats). One quirk is likely fixed (Q-R11 — get_deals propagation lag — passed Verify-fixed on session 1 of 5; not yet removed pending 4 more confirmations). This skill describes SEMANTICS, GOTCHAS, and RECOVERY; the MCP JSON-Schema is the source of truth on SHAPE. Never duplicate schema content in this skill. Every claim about runtime behavior in this skill carries a build-stamp — either an as-of: header on a reference file, or an Observed-on: line on a quirk in references/known-quirks.md.

Every quirk in the ledger is self-deprecating: it carries a Verify-fixed probe (a session-local check the agent can run) and a Removal criteria condition (the explicit signal that the server has been fixed and the entry should be deleted). When the server is fixed, delete the matching entry from references/known-quirks.md — that is the entire cleanup cost. Optional follow-up: grep for any stale QUIRK breadcrumbs across the reference files and remove them.

On unexpected server behavior (anything deviating from BOTH the MCP JSON-Schema AND the ledger), do NOT improvise — follow references/self-healing-playbook.md. The playbook names the pre-flight gates (quote sanity, side-direction, SL/TP sidedness, volume-step, schema-fields-only, pipettes-vs-display detection, required-fields), the post-flight verification rules (re-read after every mutation; for Remote amend_position, always re-read to confirm BOTH SL and TP legs survived per Q-R10), the error-classification matrix (Zod / INVALID_REQUEST / 502 uProxy / plain-text Local / available:false / truncated / hasMore), the unknown-quirk decision tree (4 steps from STOP to provisional ledger entry), and the named patterns (P-AMEND-SAFE, P-REMOTE-MARKET-RELATIVE (preferred for MARKET+SL/TP), P-REMOTE-MARKET-2STEP (fallback for absolute-price SL/TP on MARKET), P-REMOTE-MARKET-RANGE, P-LOCAL-OLDEST-FIRST, P-REMOTE-HISTORY-CHUNK).

Per-broker overlay extension point

The skill's quirks ledger uses the Q-B<n> prefix as a reserved slot for future per-broker overrides (lotSize divergences, symbol-naming variants, broker-specific SL/TP behaviors). A future assets/broker_overrides.example.json overlay would carry these per-broker values without restructuring this skill. NOT shipped this iteration — added on demand when broker-specific divergences become a blocking class.

Tool-surface routing: Local HTTP (ctrader-local-mcp) vs Remote HTTP (ctrader-remote-mcp)

The bound tool surface determines which cTrader MCP server is in front of you. Inspect tool names and response DTO shape to identify the family. Apply the routing rule below at the start of every cTrader-related interaction; cache the result for the session.

Units conventions across the two servers

The two servers encode the same trading concepts in different units and identifier types; passing Local values to Remote (or the reverse) silently produces wrong sizes, wrong prices, or schema rejections.

Stop loss and take profit: pip distance vs absolute price

Order-placement tools take SL / TP as pip distance from entry; position-amendment tools take SL / TP as absolute price. The convention depends on which TOOL is called, not which server.

When the user says "SL 30 pips below entry", convert to the form the target tool needs by running scripts/pip_math.py. Input: --pip-size <float> --digits <int> --reference-price <float> --pips <int>. Output: {"absolute_price": <float>, "pip_size_used": <float>}. The script handles both directions.

Dynamic-leverage margin calculation

Brokers apply dynamic-leverage tiers: leverage falls as the exposure grows past tier upper bounds. Required margin is computed PER TIER and summed. Tier exposure volumes are stated in USD regardless of the traded symbol; the resulting margin in USD is then converted to the account currency.

Example. Account currency USD. Order: 1 000 000 EURUSD long @ 1.21345. Notional in USD = 1 000 000 × 1.21345 = 1 213 450 USD. Tier curve: 1:500 up to 1 000 000 USD, 1:200 from 1 000 000 to 5 000 000 USD, 1:100 above 5 000 000 USD. Margin = (1 000 000 / 500) + (213 450 / 200) = 2 000 + 1 067.25 = 3 067.25 USD.

Invoke scripts/tiered_margin.py compute to compute this for arbitrary tier curves. Input: --volume-base-units <int> --quote-rate-usd <float> --tiers '[{"upper":1000000,"leverage":500},{"upper":5000000,"leverage":200},{"upper":null,"leverage":100}]'. Output: {"margin_usd": <float>, "per_tier_breakdown": [...]}. Convert the USD margin to the account currency with scripts/conversion_rate.py compute-chain.

Currency conversion: quote currency vs account currency

When a symbol's quote currency differs from the account currency, every money figure returned by the server (commission, swap, realized P&L, pip value, margin) requires conversion through a chain of spot rates. Example chains: P&L on USDJPY for a EUR account requires JPY -> USD -> EUR (using USDJPY and EURUSD); P&L on AUDCAD for an NZD account requires CAD -> USD -> NZD or a direct AUD -> NZD chain. The cTrader backend builds the shortest available chain; replicate that logic locally with scripts/conversion_rate.py.

Invoke scripts/conversion_rate.py compute-chain to derive the rate. Input: --from-asset <CCY> --to-asset <CCY> --quotes '{"EURUSD":1.0850,"USDJPY":150.3,...}'. Output: {"rate": <float>, "chain": ["EURUSD","USDJPY",...], "warnings": [...]}. Fetch the quote map up front via get_spot_prices for Local (one symbol per call) or get_spot_prices(symbolId:[...]) for Remote (batched).

Hedging vs netting accounts

Hedging accounts allow simultaneous long AND short positions on the same symbol (each gets its own positionId). Netting accounts collapse them: opening the opposite side automatically closes (or partially closes) the existing position to the net delta. Before placing the second leg of a hedge, read the existing position and the account's hedging mode (visible in get_balance and account-info responses); if the account is netting, "opening a hedge" is impossible — surface this to the user and propose either a stop-loss adjustment or a full close instead.

Stop-out and margin level

Brokers force-close positions when margin level = (equity / used margin) × 100% falls to or below the stop-out level (commonly 50% or 30%, broker-set). Two policies exist: fair (closes the single position consuming the most margin) and smart (closes the smallest set of positions sufficient to restore margin level above the stop-out). Before sizing additional risk, read current equity and used margin; if (equity − required_new_margin) / used_margin_after_open × 100% drops below 2× the stop-out level, warn the user before proceeding.

Swap accrual timing

Swap (overnight financing) accrues at broker server time rollover (commonly 23:59:59 server time). Many brokers triple-charge swap on Wednesday (the Wed -> Thu rollover absorbs the weekend value date for T+2 instruments like forex). When projecting swap over a holding period, multiply by 3 for any Wednesday in the window. Read swap and commission values directly from get_positions and get_deals responses (they are server-computed); do not re-derive them from rate tables.

Composable trader workflows

Seven end-to-end trader workflows are described step-by-step in references/trader-workflows.md. W0 (session bootstrap) auto-runs once at session start; W1–W6 are dispatched by user-intent triggers. When the user request matches any trigger, read references/trader-workflows.md and follow the corresponding recipe — do not improvise from scratch.

0. W0 — Session bootstrap — auto-runs at session start; identifies server family, probes live build, caches symbol precision baseline from assets/symbol_precision_table.json, resolves active account, and sets the idempotency-key prefix. No user trigger needed.
1. Position sizing by risk % — select this recipe when the user asks "how much to buy / sell", "size for N pips SL", "risk X% of my account on this trade", or any sentence combining a risk fraction with a stop-loss distance.
2. Pre-trade briefing — select this recipe when the user asks "should I trade X", "give me a snapshot of X before I enter", "what does X look like right now", or combines symbol-details + price + recent history requests into one ask.
3. Cost-of-trading comparison — select this recipe when the user asks "which is cheaper to trade, A or B", "compare spreads / commissions / swap across symbols", or ranks tradeable instruments by cost.
4. Place + visualize a trade with risk/reward annotation — select this recipe when the user asks "place the trade and show it on the chart", "draw the R:R on EURUSD", and the Local HTTP server is bound (this workflow requires drawings).
5. Multi-window historical backfill — select this recipe when the user asks for more bars than a single get_trendbars call returns (1000 cap on Local), e.g., "give me 5000 H1 candles of XAUUSD" or "show me the last year of D1".
6. Safe flatten — select this recipe when the user asks "close everything", "cancel all my orders", "flatten my book", or any request to bulk-close pending orders and open positions on one or more symbols.

Server-specific reference files

When the bound tool surface includes Local HTTP tools (ping, get_accounts_list, list_charts, listChartIndicators, listPlugins, show_notification, get_server_time), read references/local-http-server.md for the Local capability map, encoding rules, pagination caps, identifier types, active-chart targeting, drawing-object anchor requirements, and the destructive-operations checklist.

When the bound tool surface includes Remote HTTP tools (get_version, get_assets, integer symbolId-keyed tools, moneyDigits in responses), read references/remote-http-server.md for the Remote capability map, encoding rules, the 9-value period enum, server-side validations, timeInForce semantics, dealStatus enum, and the cache-discipline rules for get_symbols.

When both surfaces are bound, read both files.

Bundled scripts

Non-trivial computation lives in scripts/. Invoke a script whenever the math goes beyond a single multiplication or addition. Every script accepts CLI flags only (non-interactive), prints JSON to stdout, prints diagnostics to stderr, and documents itself via --help.

Post-order validation loop

After any mutating call (place_*_order, create_order, amend_order, amend_position, close_position, cancel_order), re-fetch the affected entity (get_positions, get_pending_orders, or get_position_details) and verify that volume, side, entry price (for fills), SL, TP, and dealStatus match the user's stated intent. If any value mismatches, identify the mismatch class:

• Encoding error -> re-run scripts/units_encoding.py or scripts/pip_math.py and retry with corrected inputs.
• Broker rejection (dealStatus: REJECTED / INTERNALLY_REJECTED / ERROR) -> surface the rejection reason from the server response to the user and stop.

Do not assume the order is filled just because the call returned without an exception.