Frequently Asked Questions

Q: What is the difference between volume and lots?

A: This server uses volume in units, not lots.

The lot size (units per 1 standard lot) for each symbol is available via the get_symbols tool. Call get_symbols with the symbol name to look up its lot size.

To convert: volume = desired_lots × lotSize from the symbol catalog.

Always call get_symbols to verify the actual lot size before placing an order.

Q: How do I find a symbol’s FIX Symbol ID?

A: The easiest way is to read the ctrader://symbols resource or call get_symbols, which returns the full symbol catalog with IDs, lot sizes, digits, and asset classes.

Alternatively, in cTrader:

1. Open the Active Symbol Panel
2. Click Symbol info dropdown
3. Find FIX symbol ID at the bottom

Symbol IDs are broker-specific. EURUSD might be ID 1 with one broker and ID 100 with another. Always verify with your broker.

Reference: https://help.ctrader.com/fix/getting-credentials/

Q: What is the difference between paper and live mode?

A:

Aspect	Paper	Live
Risk checks	All 8 executed	All 8 executed
Journal logging	Yes	Yes
Orders sent to broker	No	Yes
Real execution	No	Yes
Real money at risk	No	Yes

Paper mode is for testing. Orders are validated and logged but never sent to the broker. Live mode sends real orders with real financial consequences.

Q: How do I switch from paper to live mode?

A: The operating mode is set at connection time via the OAuth credentials form. To change it:

1. Disconnect the MCP connector (in Claude Desktop: Settings → MCP Servers → remove/disconnect; on claude.ai: disconnect the integration)
2. Re-authorize — reconnect and go through the OAuth form again
3. Change Trading Mode from paper to live
4. Click “Connect”

When you re-authorize with different settings (mode, risk limits, etc.), the server automatically invalidates your old session and creates a new one. If you reconnect with the same settings, your existing session is reused.

After reconnecting, call check_health to verify mode: "live".

Important: In live mode, all orders execute with real money. Test thoroughly in paper mode first.

Q: How does the kill switch work?

A: The kill switch blocks ALL trading when active.

Automatic triggers:

• Daily realized loss exceeds the daily loss limit
• State reconciliation detects discrepancies (circuit breaker)

Deactivation:

• Daily loss trigger auto-resets at 17:00 New York time (DST-adjusted)

Q: A symbol I want to trade is not available. What do I do?

A: The available symbols are managed by the server administrator. Use get_symbols to see what’s currently configured. If a symbol you need is missing, contact your server administrator to have it added. They can import symbols from the broker’s symbol catalog.

Q: What happens when the FIX connection drops?

A: The server handles disconnections with two mechanisms:

Automatic reconnect (up to 10 attempts with exponential backoff):

1. Connection loss detected (heartbeat timeout or TCP error)
2. State transitions to DISCONNECTED
3. Automatic reconnection attempts begin (5s, 10s, 20s, … up to 60s)
4. On reconnect: Logon -> Reconciliation -> Active
5. During reconciliation, trading is blocked (RECONCILING error)
6. Once ACTIVE, trading resumes normally

Manual reconnect (after auto-reconnect gives up): If all 10 auto-reconnect attempts fail, use reconnect_trade_session or reconnect_quote_session to force a fresh connection. This is common after weekends when markets are closed.

check_health shows the current session state and last disconnect reason.

Positions and daily PnL are persisted to disk, so they survive restarts.

Q: How do I reconnect after a weekend or network outage?

A: Call check_health to see the current session state. If fixState is not “ACTIVE”:

1. Call reconnect_trade_session — this tears down the old connection, opens a new one, and reconciles positions/orders from the broker
2. If you also need live quotes, call reconnect_quote_session — it reconnects and restores all symbol subscriptions

Both tools are idempotent — if the session is already active, they return “already connected”.

Q: When does the daily PnL reset?

A: At 17:00 New York time (DST-adjusted; 22:00 UTC in winter, 21:00 UTC in summer), which is the standard FX market rollover. This is not configurable. The kill switch daily loss trigger also resets at this time.

Q: What currency is PnL reported in?

A: All PnL values (realizedPnL, unrealizedPnL) are reported in USD, regardless of the instrument’s quote currency. For example, a USDJPY trade’s PnL is converted from JPY to USD using the live mid-price.

Each response includes both the USD value and the raw quote-currency value for transparency:

• realizedPnL — USD (primary, use this for decisions)
• realizedPnLRaw — original value in quote currency
• quoteCurrency — the instrument’s quote currency (e.g. “JPY”)
• conversionRate — the rate used: rawPnL × conversionRate = usdPnL
• pnlCurrency — “USD” when converted, or the quote currency code if conversion was unavailable

If the QUOTE session is down or the conversion pair is not available, PnL falls back to the raw quote-currency value and pnlCurrency indicates the actual currency (e.g. “JPY” instead of “USD”).

Q: How does the QUOTE session work?

A: The server supports two separate FIX connections:

• TRADE session: Orders, positions, and trade confirmations
• QUOTE session: Real-time bid/ask market data

The QUOTE session is enabled by default. It connects to the broker’s Price gateway (typically same host, different port) and subscribes to market data for configured symbols.

get_quote returns live bid/ask prices from the QUOTE session for a single symbol. Use get_quotes (plural) to fetch prices for multiple symbols in one call — up to 50 at once. If the QUOTE session is disabled or disconnected, both tools fall back to the last fill price from trade history.

To check QUOTE session status: read the ctrader://health resource and look at the quoteSession object.

Q: How do I check if the server is healthy?

A: Call the check_health tool or read the ctrader://health resource. Both return the same data:

• Overall status: HEALTHY / DEGRADED / UNHEALTHY
• TRADE session FIX connection state
• QUOTE session state (if enabled): connection, subscriptions, cache size
• Position and order counts
• Daily PnL and risk limit usage percentages
• Kill switch status

The check_health tool is preferred as it’s actively callable by the AI agent.

Q: What is a ClOrdID?

A: A Client Order ID (ClOrdID) is a unique identifier automatically generated by the server for each order. It is returned in the clOrdId field of order responses and used to track and reference orders (in modify_order, cancel_order). You never need to create one yourself.

Q: My MARKET order was rejected because the market is closed. What can I do?

A: MARKET orders require an active trading session for immediate execution. When the market is closed (weekends, holidays, outside trading hours), they will be rejected.

Use a pending order instead:

• LIMIT — place a buy/sell at a specific price, executes when market opens and price matches
• STOP — triggers when price reaches the stop level after market opens
• Note: STOP_LIMIT is not supported by the cTrader broker

Set timeInForce: "GTC" so the pending order persists until the market reopens and fills (or until you cancel it manually).

Example: To buy EURUSD at 1.0800 when the market reopens:

{
  "symbol": "EURUSD",
  "side": "BUY",
  "volume": 100000,
  "orderType": "LIMIT",
  "price": 1.0800,
  "timeInForce": "GTC"
}

Q: My positions look outdated / don’t reflect recent trades. What should I do?

A: Position data is cached in local state and updated only by trades placed through this server. Trades made directly in cTrader, in another tool, or in a different Claude chat are not automatically reflected.

To force a fresh sync from the broker, call get_positions with refresh: true:

{ "refresh": true }

This fetches fresh position data from the broker and waits for the current position snapshot before returning. Use this any time you’ve interacted with the trading platform outside of this MCP server session.

Q: How do I set SL/TP on a position?

A: Use the 3-step linked order workflow:

1. Open position: Place a MARKET order → the response includes positionId
2. Set Stop-Loss: Place a STOP order with the positionId from step 1 (opposite side, at your SL price)
3. Set Take-Profit: Place a LIMIT order with the same positionId (opposite side, at your TP price)

The positionId parameter links the pending order to the position, so when the STOP or LIMIT triggers, it closes the position instead of opening a new one.

Example (BUY EURUSD with SL at 1.0750 and TP at 1.0950):

1. place_order: BUY MARKET EURUSD 100000 → positionId: "12345"
2. place_order: SELL STOP EURUSD 100000, stopPrice: 1.0750, positionId: "12345"
3. place_order: SELL LIMIT EURUSD 100000, price: 1.0950, positionId: "12345"

OCO: When the position closes (SL/TP fill or close_position), the server automatically cancels all remaining linked pending orders — no manual cleanup needed.

Q: What FIX version does this use?

A: FIX 4.4, which is the version supported by cTrader.

Q: How does the server keep the agent accurate and safe when trading?

A: Safety is enforced by the server; the agent is the execution layer.

1. The server enforces all risk controls regardless of what the agent does: automated risk-guard checks (volume, position size, daily-loss limit, rate limits), the kill switch, and operating-mode gating (readonly rejects, paper validates without sending, live executes). The agent cannot bypass these.

2. Server instructions (sent during MCP init) frame the agent as the execution assistant for the authenticated account: confirm the order once with the user, then execute — showing the volume in both lots and units and cross-checking the magnitude (a misplaced zero is a 10× error). This is accuracy guidance, not a reason to refuse a clear, consented trade.

3. Tool annotations: trading tools carry destructiveHint: true so MCP clients can surface their own confirmation UI.

4. Pre-trade checklist prompt: the pre-trade-checklist prompt offers an optional readiness and volume-accuracy check before your first live order.

5. One-time risk acknowledgment: surfaced once per session, with the first live order.

Important: these mechanisms guide the agent but cannot guarantee correctness. Review the volume (in lots and units) before you confirm, especially in live mode.

Q: What are tool annotations and how do MCP clients use them?

A: Tool annotations are metadata hints defined in the MCP protocol spec:

Annotation	Meaning	Trading tools	Read-only tools
readOnlyHint	Tool does not modify state	false	true
destructiveHint	Tool may make irreversible changes	true	false
idempotentHint	Repeated calls have no additional effect	false	true
openWorldHint	Tool interacts with external systems	true	varies

MCP clients (Claude Desktop, Cursor, etc.) may use these to:

• Require user confirmation before destructive operations
• Auto-approve read-only tool calls
• Warn when non-idempotent tools are called repeatedly

Q: How do I see my past trades?

A: Call get_trade_history to see recently closed positions with P&L, close reason, duration, and optional aggregate statistics (win rate, profit factor).

{ "limit": 10, "includeStats": true }

Trade history is kept in memory (up to 200 trades per session). It resets when your session ends.

Q: Why is unrealizedPnL always 0 in get_positions?

A: cTrader does not provide P&L data for open positions directly. This is a known limitation of the cTrader FIX API.

The server calculates unrealized P&L automatically from live bid/ask prices when the QUOTE session is active and a quote for the symbol is in the price cache.

Fix: warm the price cache before calling get_positions:

1. get_positions → discover which symbols are open
2. get_quotes ["EURUSD", "XAUUSD", ...] → warms the price cache for all symbols in one call
3. get_positions again → unrealizedPnL is now calculated from live prices

(You can also call get_quote per symbol individually, but get_quotes is faster for multiple symbols.)

Each position in the response includes a priceSource field:

• "live_quote" → P&L is accurate (calculated from bid/ask)
• "unavailable" → no live price; call get_quote first

Q: How does the multi-tenant HTTP mode work?

A: The server supports multiple users, each with isolated sessions. Authentication is handled via OAuth — each user enters their credentials in a browser form, and the server encrypts and stores them securely. Header-based auth is also supported for programmatic clients.

Each session gets a dedicated FIX connection, trading state, risk guard, and journal. Sessions are isolated — one trader’s positions and risk limits cannot affect another’s.

Q: What happens if my HTTP session disconnects mid-trade?

A: The FIX connection to the broker remains open for 30 minutes after the last MCP request (idle timeout). If you reconnect with the same credentials within that window, you get the same FIX session, same state, and same positions.

After 30 minutes, the session is cleaned up and a new FIX logon is required on reconnect. During the new logon, the server reconciles positions from the broker, so no trade data is lost.

Q: Are my FIX credentials stored on the server?

A: When using OAuth (the default), credentials are encrypted and stored securely. They are decrypted only when needed to open a FIX connection, and never stored in plaintext.

A one-way session identifier is used for routing and logging — raw credentials never appear in logs, journals, or metrics.

With header-based auth, credentials are passed per-request and not stored at all.

Q: Can I use this with multiple brokers simultaneously?

A: Yes — each OAuth connector session gets its own dedicated FIX connection. Multiple traders with different brokers can connect to the same server instance simultaneously. Each connector session is fully isolated with its own positions, risk limits, and journal.

Q: Can I use this for scripting or algorithmic trading?

A: This MCP server is designed for interactive AI-assisted trading via Claude Desktop or claude.ai. For scripting, algo trading, or programmatic integrations, use the axiory:connect Claude Code plugin instead — it provides the same cTrader FIX connectivity optimized for automated workflows.

Q: What is guest mode?

A: When connecting without credentials (before completing the OAuth flow), the server creates a guest MCP session.

Guest sessions expose:

• 2 tools: get_symbols and get_knowledge (read-only, no FIX dependency)
• 12 resources: Knowledge base and symbols work normally; state resources (positions, orders, health) return a “not_connected” message with setup instructions
• 3 prompts: All prompts work, including setup-guide which walks through credential configuration

This lets AI agents discover the server’s capabilities and learn how to connect before providing credentials. Complete the OAuth flow to upgrade to a full trading session.

Q: How do I connect to the server?

A: There are two ways to connect:

OAuth (recommended): Add the server URL (https://mcp.axiory.ai/mcp) to your MCP client. The client opens a browser for credential entry. Tokens refresh automatically — no manual rotation. Works with Claude Desktop, claude.ai, Cursor, Windsurf, Cline, and most MCP clients.

Portal Token (fallback): If your client doesn’t complete the OAuth flow, visit https://mcp.axiory.ai/token-portal in your browser, enter your FIX credentials, and copy the generated token. Paste it into your client’s config as a Bearer token. Portal tokens last 30 days.

For detailed setup instructions per client (Cursor, Manus, Windsurf, etc.), read the getting-started knowledge topic.

Q: How long does an OAuth session last?

A: Access tokens expire after 1 hour. Refresh tokens last 7 days.

Claude Desktop automatically refreshes the access token using the refresh token, so you stay connected for up to 7 days without re-entering credentials. After 7 days, you’ll need to re-authorize through the browser form.

Q: Can I revoke OAuth access?

A: Yes. Disconnect the MCP connector from your client (Claude Desktop or claude.ai) and reconnect. When you re-authorize, the server automatically revokes old tokens and creates a new session.

Access tokens expire after 1 hour, refresh tokens after 7 days. If you need immediate revocation for security reasons, reconnecting with the same or different credentials triggers automatic invalidation of the old session.

Q: What if I change my FIX password?

A: After changing your FIX password:

1. Disconnect the MCP connector from your client
2. Reconnect — the OAuth flow will re-open the browser
3. Enter your new FIX credentials

The server detects that your credentials changed and automatically invalidates the old session.

Q: How do I change connector configuration (mode, risk limits, server, account) mid-session?

A: Use the reset_session tool. It invalidates your current session and triggers re-authentication, where you can reconfigure all parameters including trading mode, risk limits, FIX server, and account.

What happens on reset:

• All active sessions for your account (including other connected clients) are terminated immediately
• Active quote subscriptions are dropped
• In-memory trade history and session state are cleared
• In-flight tool calls on other sessions may be interrupted

What is NOT affected:

• Open positions on the broker
• Pending orders on the broker
• Journal entries on disk

Edge case: If a position closes during the reset window, linked OCO orders (stop-loss/take-profit) may not be auto-cancelled — check and cancel them manually after reconnecting.

After reset, call any tool (e.g. check_health) — this triggers automatic re-authentication and the browser opens the configuration page.

reset_session is only available in HTTP multi-tenant mode (OAuth-enabled deployments).

Q: Can I set custom risk limits per session?

A: Yes. When connecting via OAuth (browser form), expand the “Risk Limits” section to customize your risk guardrails:

• Max Position Size (per asset class) — separate limits for FX, Indices, Crypto, Commodities, and Stocks
• Max Open Positions — how many positions can be open simultaneously (default: 20)
• Daily Loss Limit — realized loss threshold that triggers the kill switch for the day
• Max Orders per Minute — throttles order submission rate

Rules:

1. All fields are optional — leave empty to use sensible defaults.
2. Each field has a maximum allowed value to prevent misconfiguration.
3. To change limits mid-session, you must disconnect and re-authorize (limits are set at connection time).
4. Re-authorizing with different settings automatically invalidates your old session.

After connecting, call check_health — the riskLimits.configured section shows your effective limits.

Q: How do I report a bug or request a feature?

A: Use the submit_feedback tool. For bugs, call check_health first and include the output in the environment field. The tool returns a feedback ID — use get_feedback_status to check for updates.

For full details on best practices, rate limits, and how feedback is handled, read the feedback knowledge topic: get_knowledge({ topic: "feedback" }).

Q: Why was my FIX host rejected?

A: The server only allows connections to explicitly configured broker servers. If your host is not in the dropdown on the OAuth form, it has not been configured yet. Contact the server administrator to add your broker server.

Each server requires its own symbol catalog (IDs differ between broker environments). Adding a new server is a configuration change — contact the server administrator.

Q: What if OAuth doesn’t work with my client?

A: Use the Token Portal as a fallback:

1. Visit the Token Portal URL in your browser
2. Enter your FIX credentials (same form as OAuth)
3. Click “Generate Token” to receive a 30-day Bearer token
4. Copy the token and add it to your client’s config

The token works with any MCP client that supports custom HTTP headers. Store it in an environment variable (e.g., CTRADER_TOKEN) — never hardcode tokens in config files.

To revoke all portal tokens, visit the Token Portal again and use the “Revoke All Portal Tokens” button.

Q: How long do portal tokens last?

A: Portal tokens expire after 30 days from creation. You can generate a new token at any time by visiting the Token Portal. Old tokens remain valid until they expire or are revoked.

You can have up to 5 active portal tokens per account. When generating a 6th, the oldest is automatically revoked.

Q: Which AI agent clients are supported?

A: The server works with any MCP-compatible client. Tested and documented clients include:

• Claude Desktop / claude.ai — OAuth (built-in connector)
• Claude Code CLI — OAuth or Bearer token
• Cursor — OAuth or Bearer token
• Windsurf — OAuth or Bearer token
• Cline — OAuth or Bearer token
• Continue — Bearer token
• OpenAI / ChatGPT — OAuth or Bearer token (Developer Mode)
• Google Gemini CLI — OAuth or Bearer token
• Perplexity — OAuth or API key
• Manus — OAuth or Bearer token
• OpenClaw — Bearer token

All clients connect via StreamableHTTP transport to the same server URL.

Q: What happens if I enter wrong credentials on the connection form?

A: The server validates your credentials against the broker before issuing tokens. If your password is wrong or you selected the wrong server, you will see an error message on the form immediately — not a success page.

Two types of errors can occur:

• “Credentials rejected by broker” — your password or SenderCompID is incorrect. Double-check your FIX API password (not your cTrader account password) and SenderCompID.
• “Could not reach broker” — the server couldn’t connect to the broker. Check that you selected the correct server and that your FIX API access is enabled.

After 5 consecutive failed attempts, the account is temporarily locked for 15 minutes to prevent brute-force attacks.

Q: Why does re-authentication work differently when I have an active session?

A: The cTrader broker allows only one FIX connection per SenderCompID. When you re-authenticate while a session is active, the server cannot open a second connection to validate your credentials — it would be rejected.

The server handles this with smart logic:

• Same configuration (mode, risk limits, server unchanged): Validation is skipped entirely. Your active session already proves the credentials are valid.
• Changed configuration (e.g., switching from paper to live mode): The server closes your existing FIX session first, then validates the new credentials. If the new credentials fail, you’ll see: “Your previous session was closed. New credentials were rejected by broker.”
• Password change: Changing your FIX password at the broker creates a different identity. The server cannot find your old session to close it. Wait for the old session to expire (idle timeout) or use reset_session from your existing session before changing the password at the broker.

Q: Is this a local or cloud service?

A: This is a cloud-hosted remote MCP service. You connect to it over HTTPS via OAuth or Bearer token. The server runs on managed cloud infrastructure — you do not have access to the underlying server, containers, processes, environment variables, logs, or filesystem.

All interaction happens exclusively through MCP tools. For detailed architecture and troubleshooting, read the service-model knowledge topic: get_knowledge({ topic: "service-model" }).

Q: What can I do when the service is unresponsive?

A: Use the built-in recovery tools in this order:

1. check_health — diagnose the current state
2. reconnect_trade_session — if TRADE FIX session is down
3. reconnect_quote_session — if QUOTE session is down
4. Disconnect and reconnect the MCP connector in your client settings
5. If the issue persists, use submit_feedback to report it

Do not attempt to restart processes, check logs, or perform any server-side actions — you do not have access to the server infrastructure.

Q: Why can’t I restart the server or check logs?

A: This is a multi-tenant cloud service. You connect to it the same way you connect to any web service — via a URL. You do not have SSH access, Docker access, or any way to interact with the server infrastructure. The service is managed by the platform operator.

If you are experiencing issues, use check_health to diagnose and the reconnect tools to recover. For persistent problems, report them via submit_feedback.

Q: How do I troubleshoot connection issues?

A: Follow this escalation path:

1. Call check_health — check fixState and quoteSession.state
2. If fixState != “ACTIVE” → call reconnect_trade_session
3. If quoteSession.state != “ACTIVE” → call reconnect_quote_session
4. If reconnect fails → wait 30 seconds and retry (broker may be temporarily unreachable)
5. If still failing → markets may be closed (weekends: Friday evening → Sunday evening) or the broker may be under maintenance
6. Last resort → disconnect and reconnect the MCP connector in your client settings to get a fresh session

Q: My FIX password contains special characters (| = @ # etc.) — is that supported?

A: Yes. Passwords (and other credential fields) may contain any printable characters, including pipe (|), equals (=), and symbols. The only characters not allowed are control characters (which a real password would never contain). Enter your password exactly as set in your cTrader FIX API settings. If authentication fails with a valid password, the trading gateway may simply be temporarily unreachable (see “troubleshoot connection issues” above) — that returns a clear error and does not lock your account.