Skip to main content

MCP Troubleshooting

This page covers the errors and failure modes most likely to interrupt an MCP session, with the actual symptom each one shows.

For setup steps, see Setup. For permission errors, see Scopes.

Tools do not appear in the client​

Symptom: the client connects, OAuth completes, but tools/list returns nothing or an empty subset.

Likely causes:

  • Token was issued at mcp:read but the client expected mcp:trade and ignored read tools. Reauthorize at the scope the workflow needs.
  • Add-on is below v1.13.0. Several tools are gated on the running add-on version. Update inside NT8.
  • NT8 is not running. Tools that need a live NT8 instance hide when no add-on connection is registered.

Fix: call GetMcpCapabilities and look at the features list and nt8_version. If the add-on side is empty, NT8 is not connected.

OAuth fails​

Symptom: consent screen never opens, redirects fail, or the client returns an invalid_grant error.

Likely causes:

  • Browser is signed in to a different CrossTrade account.
  • A previous registration was deleted by an admin.
  • System clock is far enough off that PKCE / token timestamps fail.

Fix:

  1. Sign out of CrossTrade in the browser tab.
  2. Retry from the client and complete the consent screen.
  3. If invalid_grant persists, check system time.

403 Elite requirement​

Symptom: tools list works, but every tools/call returns:

{"error": "MCP requires an Elite subscription"}

Fix: upgrade at Subscriptions. REST and WebSocket remain on Pro; only the MCP transport requires Elite.

Add-on version too old​

Symptom: GetMcpCapabilities returns a warning string or a smaller features list than expected. Backtest, NinjaScript compile, or deployment tools may be absent.

Fix:

  1. Open NT8.
  2. Open the CrossTrade Add-On panel.
  3. Update to v1.13.0 or newer.
  4. Reconnect.

NT8 disconnected​

Symptom: tools that need a live NT8 instance hang, time out, or return addon_disconnected.

Likely causes:

  • NT8 is closed.
  • The CrossTrade Add-On panel inside NT8 shows disconnected.
  • A broker connection is down and the add-on is waiting on reconnect.

Fix:

  1. Open NT8.
  2. Check the CrossTrade Add-On status panel.
  3. If the broker side is down, restart the connection from NT8's Connections menu.
  4. Retry the tool.

Scope mismatch​

Symptom:

{"error": "insufficient_scope", "required": "mcp:trade"}

Fix: reauthorize at mcp:trade from the AI Clients page if the workflow legitimately needs write access. Otherwise rewrite the prompt to keep the agent in read-only mode.

Tool call timeout​

Symptom: tool call returns a timeout error or hangs past the client's deadline.

Likely causes:

  • Long-running operation. RunStrategyBacktest, CompileNinjaScript, and parameter sweeps are jobs that may exceed a default client timeout.
  • NT8 UI is blocked.

Fix:

  • Use the job-pattern tools: a long call returns a job_id quickly, then poll GetMcpJob until complete. Most clients do this automatically when the tool returns a job descriptor.
  • If NT8 itself is blocked, switch to NT8 and clear any modal dialogs.

Backtest job stuck​

Symptom: RunStrategyBacktest returns a job_id but GetMcpJob keeps reporting running for longer than expected.

Fix:

  1. Confirm the job is actually running: ListMcpJobs should show it with a recent timestamp.
  2. Look at NT8 directly. If the Strategy Analyzer window is showing progress, the job is healthy.
  3. If NT8 is idle and the job is stale, call CancelMcpJob and start a smaller backtest to isolate the issue.

Backtests with very wide parameter sweeps can run for many minutes. If the sweep was large, the right action is patience plus periodic polling, not cancellation.

Strategy deployment failed​

Symptom: DeployStrategy returns an error, or GetDeployedStrategyState shows the strategy as deployed but is_trading: false.

Likely causes:

  • The strategy was not compiled. Compile first, write the file, then deploy.
  • The account or instrument in the deploy request is not connected.
  • The strategy depends on a chart that does not exist. Open the chart with OpenChart first or include the chart parameters in the deploy request.
  • The strategy attached to a chart cannot be toggled via StrategiesGrid.StrategyEnable. Use the strategy-on-chart workflow instead.

Fix:

  1. Verify compile passed: GetCompileResult should show success.
  2. Verify the account: ListAccounts and GetConnections.
  3. After a successful DeployStrategy, call GetDeployedStrategyState and look at is_trading and errors.

Order rejected​

Symptom: PlaceOrder returns a rejection or the order shows as rejected in GetOrder.

Likely causes:

  • Max contracts breach for the account.
  • Daily loss lockout already triggered.
  • News-window restriction (firm-specific).
  • Symbol not subscribed or instrument expired.
  • Account disconnected or replay not running.

Fix:

  1. Read GetAccountSummary and GetWatermarks for risk constraints.
  2. Read GetConnections to ensure the account is live.
  3. Re-read the rejection reason in GetOrder.execution.last_error or equivalent.
  4. If the rejection is firm-driven (max contracts, daily loss), do not retry. The reject is the rule working.

Compile errors​

Symptom: CompileNinjaScript returns a compile failure with C# diagnostics.

Fix:

  • The agent should call LookupNinjaScriptSymbol for any unresolved symbol and adjust.
  • For unresolved method overloads, call GetNinjaScriptHelp with the method name.
  • Re-run CompileNinjaScript(in_memory: true) until clean before any WriteNinjaScriptFile.

Read-only token tries to write​

Symptom: a tool that requires mcp:trade returns insufficient_scope.

Fix:

  • If the workflow truly needs to write, revoke the current token and reauthorize at mcp:trade.
  • If the workflow should be read-only, rewrite the prompt to prevent the agent from attempting the write.

This is a common pattern. Treat it as the safety system working, not a bug.

Where to get support​

Include the following when filing a support issue:

  • Client name and version (Claude Desktop, Claude Code, Cursor, etc.)
  • Approximate time of the failure in UTC
  • The tool name that failed
  • The error string returned
  • The output of GetMcpCapabilities if available

Do not paste tokens, full account identifiers, or webhook secrets into support tickets. Redact aggressively. CrossTrade can correlate from add-on version and timestamps without those values.