Talking to Your Add-On with AI

Two MCP tools, both Elite-gated, both designed for AI clients (Claude Desktop, Claude Code, Cursor, opencode, and other MCP-capable assistants). They let an AI inspect what your CrossTrade account has been doing without you opening the dashboard or the XT Add-On window.

This page is the terse, factual reference. For a conversational walkthrough, see the docs page on Talking to Your Add-On and the diagnostic learn article on Diagnosing Failed Signals.

Frequently Asked Questions

What is GetSignalHistory?

An MCP tool that returns paginated rows from your CrossTrade Alert History (every webhook signal CrossTrade has received for your account). It's the same data shown at app.crosstrade.io/user/alert-history, but available to an AI assistant over the MCP protocol so it can answer questions like 'why did my last signal fail?' or 'show me the last hour of MNQ alerts' without you doing any clicking. Elite-only. Requires the AI client to be connected to https://app.crosstrade.io/v1/api/mcp and authorized with an active OAuth token.

What arguments does GetSignalHistory accept?

offset (int, default 0) — pagination start. limit (int, default 50, max 200) — number of rows to return. status ('*' | 'success' | 'warning' | 'failed', default '*') — filter to rows of a given status. search (string, optional) — substring filter applied across id, multi-account id, request body, and error fields. direction ('desc' | 'asc', default 'desc') — order by received timestamp. include_help (bool, default true) — when true, attaches a structured help block to failed/warning rows whose error matches a known pattern.

What's in each GetSignalHistory row?

Identifiers (id, multi-account id when relevant), received and forwarded timestamps, resolved account and instrument, the full request payload as received, the resolved command, and the status. For failure rows: an error string (machine-readable, e.g. invalid_secret_key, account_not_connected, position_out_of_sync) and, when the error pattern is known, a help_key plus a help block containing title, explanation, common_causes, and how_to_fix. For warning rows: a warning string with the same shape. The help block lets the AI explain the failure without making a second tool call.

What is GetActivityLog?

An MCP tool that returns recent entries from the XT Add-On's local SQLite log database. This is the same data shown in the Activity Log section of the XT Add-On window inside NinjaTrader. Useful for an AI assistant to verify connection events, order submissions, sync messages, and account state from the add-on's perspective. The add-on must be currently connected; if NT8 is offline, the tool returns an empty result and the AI should report the add-on as offline.

What arguments does GetActivityLog accept?

limit (int 1–500, default 100) — number of rows to return. lookback_hours (int 1–168, default 24) — how far back to look (capped at one week). levels (array of strings, optional, default all returnable levels) — restrict to one or more of 'Info', 'Warning', or 'Hidden'. Error and Debug levels are admin-only by design and are never returned even if explicitly requested in the levels array.

What's in each GetActivityLog row?

A timestamp, the log level ('Info' | 'Warning' | 'Hidden'), a category tag (connection, order, sync, account, etc.), and a human-readable message string. Rows are returned newest first by default. The XT Add-On writes one row per relevant event as it works, so a single trade can produce several rows (signal received, order submitted, fill reported, position updated).

Are Error and Debug log levels available via the AI?

No. Error and Debug are admin-only by policy and the GetActivityLog tool filters them out unconditionally, even if a client passes levels=['Error']. Non-admin users see Info, Warning, and Hidden only. If a user suspects an Error condition they can't see, open the Activity Log inside the XT Add-On window directly, or contact support with the account email and an approximate timestamp.

What plan tier do these tools require?

Elite. The hosted MCP server requires an active Elite subscription and CrossTrade Add-On v1.13.0 or higher. OAuth tokens can be issued to non-Elite accounts (the discovery and consent flow works for everyone), but tools/call returns HTTP 403 with 'MCP requires an Elite subscription' until the account is upgraded. Manage the plan at app.crosstrade.io/user/subscriptions.

How does a user connect their AI client?

Add the CrossTrade MCP server to the AI client's config. The URL is https://app.crosstrade.io/v1/api/mcp. Most clients accept the same JSON shape: { "mcpServers": { "crosstrade": { "url": "https://app.crosstrade.io/v1/api/mcp" } } }. For Claude Desktop, paste that into Settings > Developer > Edit Config. For Claude Code, run claude mcp add --transport http crosstrade https://app.crosstrade.io/v1/api/mcp. The client will trigger an OAuth flow on first use; the user clicks Allow on the CrossTrade consent screen and the client gets a token. See crosstrade.io/docs/api/ai-assisted-development for the full setup walkthrough.

What prompts work well with these tools?

"Show me the last hour of signals." "Which signals failed in the last day and why?" "Did the add-on disconnect overnight?" "Why did my MNQ order fail at 14:22?" "Walk me through what happened around 9:35 AM." "Are there any patterns in my failures this week?" "Find the 'sync' warning from earlier and tell me what to do about it." The AI picks the right tool, applies appropriate filters, and explains the result using the attached help blocks where present.

When does GetSignalHistory attach a help block?

Whenever the row's error code (for failed rows) or warning code (for warning rows) matches a known failure-pattern registered on the CrossTrade side. The block carries title, explanation, common_causes (a list of bullet strings), and how_to_fix (a list of bullet strings). Examples of error codes that produce help blocks: invalid_secret_key, account_not_connected, account_not_found, position_out_of_sync, signal_formatting_error, rate_limit_exceeded, missing_required_field, market_data_unavailable, kill_switch_engaged, closing_only_mode, instrument_format_not_compatible, unknown_field_name, request_timed_out. The full catalog is the same set documented at crosstrade.io/docs/getting-started/alert-history.

What if a failed row has no help block?

include_help=true still applies; the AI just won't get a structured explanation. The raw error string and the raw request payload are always present on the row, so the AI can still describe what failed at face value. A good agent response in this case is honest about the absence of a known pattern and recommends forwarding the Order ID to support if the user wants a deeper look.

How do these tools differ from the REST API?

REST has /v1/api/alerts-history (and similar) for Alert History data. GetSignalHistory is the MCP wrapper around the same underlying surface, designed so an AI client doesn't have to construct HTTP requests, handle pagination headers, or know the path scheme. It just calls the tool by name. There is no REST equivalent to GetActivityLog; the add-on's local log database is only accessible through MCP today. Both tools are registered in the MCP-only handler set, which means they appear in tools/list for any authorized MCP client and aren't reachable as REST endpoints.

What are the per-call limits?

GetSignalHistory: up to 200 rows per call (use offset for pagination). GetActivityLog: up to 500 rows per call, up to 168 hours of lookback. For larger windows or older data, paginate, or fall back to the dashboard's Alert History page and the XT Add-On's local Activity Log window.

Do these tools mutate any state?

No. Both are read-only. They do not place orders, cancel orders, deploy strategies, or modify settings. They are safe to call with the mcp:read scope. A read-only token is sufficient for diagnostic conversations using these two tools.

What does a typical successful GetSignalHistory response look like?

It's a paginated structure with a list of rows. A failed row looks roughly like: { "id": "ord_abc123", "received_at": "2026-05-14T14:08:12Z", "account": "Sim101", "instrument": "MNQ 06-26", "request": "key=...;command=PLACE;account=Sim101;...", "status": "failed", "error": "invalid_secret_key", "help_key": "invalid_secret_key", "help": { "title": "Secret key is missing, invalid, or inactive", "explanation": "...", "common_causes": ["...", "..."], "how_to_fix": ["...", "..."] } }. Successful rows have the same shape minus error/help. The AI client doesn't need to memorize the schema; the response is self-describing.

What does a typical successful GetActivityLog response look like?

A list of rows like: { "ts": "2026-05-14T13:48:09Z", "level": "Warning", "category": "connection", "message": "Rithmic data feed disconnected (reason: idle timeout)" } and { "ts": "2026-05-14T13:48:42Z", "level": "Info", "category": "connection", "message": "Rithmic data feed reconnected" }. Rows are ordered newest-first by default. The category and message strings are the same ones a user sees in the XT Add-On's Activity Log UI.

Can an AI cross-reference both tools in one prompt?

Yes. The recommended diagnostic pattern is exactly this: ask the AI to call GetSignalHistory for the failed signal, then call GetActivityLog for the same timestamp window, and correlate. Example: "An MNQ alert failed about 20 minutes ago. Find it in Signal History, then check the add-on Activity Log for the same window to see whether the connection dropped." A capable client will issue two tool calls and produce a single chronology-aware explanation.