Skip to content
Algo Trade Analytics Docs

Screener MCP and monitoring

Screener’s MCP tools work with the same saved screens and run records as the app. An external agent can compose a Standard rule, save it, run a dated screen, and inspect retained rows. Availability depends on the environment and your MCP access. Start with MCP client setup and Security, scopes, and credits.

For an ordinary saved Standard screen, call ata_list_screener_screens, then ata_get_screener_results with its screenId. This reads compatible prepared values using the saved filters and timeframe. Browser-local unsaved edits are excluded. It requires mcp:read and your screener entitlement.

The response defaults to matched rows. Use status to request other rows, and continue with the returned snapshotId, expectedRevision, readReferenceId when present, and nextOffset. Pages contain at most 50 rows and may be smaller to fit the response limit. Restart from the first page if the saved screen or available snapshot changes.

If no compatible data is available, the tool returns not_prepared. It does not start preparation or download bars. Open the screen in the app to load its data. Ownership, connection, expiry and protected-data checks still apply. This reader supports the prepared daily market, daily index and explicit-symbol Standard views. Watchlist and case-study universes still use the research-run workflow below. A session already bound to research must use those scoped tools.

Call ata_context first and follow the MCP research workflow to load a case study, start or resume its research run, and inspect the research contract. Confirm that the connection is bound to that run before calling Screener’s market tools.

Research-scoped MCP market operations require an owned, active research run bound to the connection, with a valid case study and authorized development-data window. This applies to starting runs, polling or listing retained runs, reading their rows, frozen definitions, charts, exports, result links, and notifications, and cancellation. A screen ID alone does not grant market data access.

The entire requested lookback window must fit inside the development window. The authorization covers the exact data-fetch window, including the calendar padding used to obtain enough trading bars. Setting the last bar inside the window is not sufficient if the lookback begins before it.

Pass asOfDate on execution for historical research. Without it, execution uses the latest completed session, which may lie outside the bound window. If access is refused, use an authorized earlier date or a development window that contains the fixed history. Do not change the research window merely to bypass a reserved-data refusal. Retained results also require authorization, including the baseline of an entrants/exits comparison; saved results do not bypass the research boundary.

StepTools and checks
Discover graphical fieldsata_list_screener_fields returns field IDs, formulas, minimum bars, indicator families, and templates; ata_get_screener_field_registry resolves the registry for a specific rule
Compose a graphical ruleUse ata_compose_screener_rule, then inspect the canonical rule and validation; ata_validate_screener_rule checks a supplied rule without reading market data
Inspect its declarationata_render_screener_python renders the read-only SCANNER declaration; it does not convert the rule into executable Python
Saveata_create_screener_screen saves the name, universe, interval, and Standard rule; daily history is fixed at 250 bars; supply an idempotencyKey
ReviseRead with ata_get_screener_screen, then update with ata_update_screener_screen and its expectedRevision
Price and executeRead ata_quote_screener_run, then call ata_run_screener_screen with screenId, asOfDate, and a stable retry idempotencyKey
Read the resultPoll ata_get_screener_run; after success, page through ata_get_screener_run_rows, checking coverage and all statuses
Recover the tested definitionata_get_screener_run_definition returns the frozen rule, universe, lookback, and revision admitted for that run
Inspect and shareata_get_screener_run_chart returns retained candles and outputs for a symbol; ata_export_screener_run returns CSV or JSON; ata_get_screener_run_link returns the exact app result URL
Manage saved screensata_duplicate_screener_screen creates an independent copy; ata_set_screener_screen_archived archives or restores a screen

Use a rule for a Standard screen. Custom Python creation and execution remain unavailable. Universes can name explicit symbols, case studies, an owned watchlist, a configured index list, or a supported market. Each request must still fit the authorized research scope and execution limits. For example:

{"kind": "symbols", "symbols": ["AAPL", "MSFT"]}
{"kind": "case_studies"}

After creation, use the returned IDs rather than inventing them. Run creation returns a run record immediately; use its id as runId for polling. Receiving that record is not a completed scan. Reuse the same idempotency key when retrying the same intended operation after an uncertain response. A changed screen must be read and updated at its current revision.

Rows can be filtered by matched, not_matched, unavailable, or error. The MCP row page defaults to 200 and accepts offset and limit; continue until the returned total is covered. Keep the run ID, revision, as-of date, actual universe, coverage, source/rule digests, and credit receipt with any analysis.

Within an authorized development window, create a Standard screen for an explicit list such as AAPL and MSFT, with a numeric daily RSI condition. Supply an asOfDate whose entire fixed history fits that window. Quote and start the saved screen, retain its returned run ID, and page through all result statuses. To change to 30-minute bars, first discover whether that interval is available and verify that the full intraday window and every selected symbol fit the research binding.

Discover saved runs without reading observations

Section titled “Discover saved runs without reading observations”

Request ata_list_screener_runs with view: "metadata" to discover run IDs, revision, status, interval and lifecycle timestamps, with observedFieldsWithheld: true. Follow nextCursor to discover older runs. This list does not reveal counts, symbols, comparisons, errors or calculated values and does not record market-data exposure. The owned active research binding is still required.

Use a returned run ID with the result tools when you intend to read observations. Omitting view preserves the observed history response; explicit view: "observed" returns the same counts, comparisons and provenance. That protected page retains the 10,000-symbol authorization budget, including comparison baselines. Reducing the page size does not help when one run plus its baseline already exceeds that budget; metadata discovery remains available without weakening result authorization.

When prepared screening is enabled, start with the read-only ata_quote_screener_fields for an owned saved Standard screen or exact draft configuration. It returns a calculation/storage estimate and, when available, a signed consent for one preparation. Quoting does not acquire price history, record market-data exposure, reserve work or start a job.

Review that estimate before calling ata_prepare_screener_fields. Send consentToken: consent.token with exactly the same request and owned research binding. The token expires after 90 seconds; an expired token, changed request or changed access needs a fresh quote and review. A token is not transferable to another account, research run or calculation scope.

Use a deliberate refreshKey only for a new attempt, and include that same key in both quote and preparation. After an uncertain response, retry the identical request and key; an already admitted attempt can be joined without another initial reservation. Actual worker retries still consume work. For a later attempt or an expired approval, obtain a fresh quote rather than changing or reusing the token. Preparation freezes its owned research binding and does not bypass quotas. Neither tool enables Follow or a recurring subscription for an external agent.

Poll ata_get_prepared_screener_fields with the returned snapshotId. Pending preparation does not provide a complete result population. The snapshot identifies its execution mode. Reusable fields allow different thresholds over the available calculated values. Exact rule results preserve the engine’s original decisions, scores and temporal evidence; changing a condition requires a new preparation. Search, status and sorting browse the complete published population in either mode. Follow navigation.nextOffset until null; one page is not the full market. New fields or a changed calculation scope can also require new preparation. Daily indicator history is 250 bars; intraday history is 260 bars with at most 500 explicitly selected symbols and a minimum interval of ten minutes. Basic daily quote-only preparation uses two bars and does not calculate RSI or other indicators. Prepared scheduled Daily runs use the full fixed 250-bar calculation window, including screens with only price conditions. Their compact saved results retain calculated values and provenance, without original candles.

For session-aware relative volume at time v2, use the registry field for relative_volume_at_time_v2 with its configured sessions and minSessions; its identifier is relative_volume_at_time_v2_{sessions}_{minSessions}. V2 supports only the primary 10-minute, 15-minute, 30-minute or 1-hour stock/ETF interval. The server supplies and binds session evidence; clients do not manufacture it. Missing or non-comparable observations remain unavailable. V1 fields retain their original semantics; selecting v2 does not enable Follow or increase execution limits.

ata_get_prepared_screener_chart reads original retained chart pages when the snapshot includes history. Follow its own pagination. Quote-only snapshots and exact rule-result snapshots do not retain original chart history; this is not evidence of a missing live price. Expired or unavailable snapshots must be handled explicitly. ata_cancel_prepared_screener stops pending preparation under its original binding; uncertain dispatched work stays accounted for until settled. Existing completed snapshots are preserved.

Open the exact result and retrieve its source

Section titled “Open the exact result and retrieve its source”

Run responses include links.runUrl and links.screenUrl. The run URL pins the saved run, so it does not substitute the screen’s latest result. To open a particular symbol’s chart drawer, call:

{"runId": "<returned run ID>", "symbol": "AAPL"}

with ata_get_screener_run_link. The symbol must belong to that run’s universe. Give the user the returned links.runUrl as a clickable link. The recipient must sign in with access to the screen; the link does not grant access or start another scan. Screen responses also include their app url.

Use ata_get_screener_run_definition for historical Python, rather than reading the screen’s current source. If an older run has no retained snapshot, the tool returns screener_definition_unavailable; it does not invent a definition. ata_get_screener_run_chart reads retained candles without fetching new bars. ata_export_screener_run takes format: "json" or "csv" and returns a file’s filename, mimeType, and content. JSON includes the retained definition, provenance, and rows; CSV includes row fields and reasons.

Duplicating a screen copies its definition into an independent screen, without copying results. Archiving disables its schedule. Restoring with archived: false does not re-enable monitoring.

App interaction and MCP are different entry points

Section titled “App interaction and MCP are different entry points”

The in-app Algo Agent inspects and proposes edits to the current draft. It does not execute a scan through its chat reply. Applying a proposal returns to the normal app preparation/execution flow. Its result-inspection tool reads a completed saved run, not the current prepared-only table. An external MCP agent can explicitly call Screener tools, but must satisfy the owned research binding on every protected operation.

The app’s interactive prepared view can reuse values when a user changes a numeric threshold. Standard intraday preparation supports up to 500 selected symbols and 260 completed bars per symbol. MCP also requires an owned research binding for the symbols and data window. Mixed-interval prepared screens are available through the app. Use the returned capabilities and quote for the particular MCP request. Use quote, prepare, read, chart, and cancel tools for MCP prepared data; there is no MCP lookup-only or Daily-match selection dialog tool. The app’s selected-symbol view read and configuration-file import are not MCP operations. Export completed MCP runs as CSV or JSON.

Follow is unavailable in the current app release. MCP preparation is one-shot. It does not enable viewer Follow, unattended intraday updates, or a saved-screen schedule. Monitoring below requires its own released app capability.

Enable daily or weekly scheduling in the app

Section titled “Enable daily or weekly scheduling in the app”

Schedules require the environment’s scheduling capability. If the app reports that scheduling is unavailable, the instructions below do not enable it. Email notifications require their separate capability as well.

Where scheduling is enabled, use the Screener page to enable a schedule. MCP can list schedules, read one with ata_get_screener_schedule, disable one with ata_upsert_screener_schedule and enabled: false, or remove one with ata_delete_screener_schedule; it cannot enable recurring monitoring. MCP research uses explicit dated runs within its bound development window.

  1. Save a Standard Daily screen. A schedule always belongs to a saved screen; it cannot target an unsaved draft.
  2. Open Schedule (clock icon) and choose its Saved screen. You can select a different saved screen from the one currently open, without changing your workspace. The dialog loads the selected screen’s existing schedule and identifies its saved revision.
  3. Choose Daily or Weekly, with a time and, for weekly runs, a weekday.
  4. Choose when to notify, optionally enable email, then save the schedule.

Intraday scheduling is deferred. Manual intraday scans remain separate. Switch an intraday screen to Daily and save before scheduling it. If you select the screen currently open in your workspace, save its unsaved changes before enabling its schedule. You can still select and schedule a different saved screen without saving the workspace draft. Existing schedules can be paused or removed without saving draft edits.

New schedules start paused with email off. Each saved screen has at most one schedule. The initial account limit is 3 active schedules; paused schedules do not occupy a slot. The dialog shows the active count and limit. Existing workload allowances may prevent enabling a schedule even below that count. Pause another screen’s schedule to free a slot. Use Open → Schedules to manage monitoring.

Stock and ETF schedules use completed New York daily sessions; holidays are skipped. Crypto schedules use completed UTC days. The New York clock follows daylight saving time. Runs start on a maintenance tick, rather than promising second-level execution. When prepared scheduling is enabled, supported Daily market screens prepare fields or exact rule results in bounded steps and may wait for workload or storage capacity. A scheduled time does not guarantee completion at that time or within an hour. Preparation that does not finish within 24 hours fails; inspect Run history for its reason. Rules not supported by prepared execution still use the bounded scan path and can encounter its workload limits. Previously configured intraday recurrence is paused before new execution while the release capability is disabled.

Each run freezes its interval, cutoff, session boundaries and saved definition. Forming bars are excluded. A symbol with no bar at the required cutoff is unavailable, not silently evaluated from stale data. Entry/exit comparisons use the same interval. Only one run per screen can be active. Missed ticks coalesce to the latest completed cutoff rather than creating a backlog. Data-access failures, provider throttling and capacity limits remain visible in history. Intraday Algo Lab handoff is unavailable until its exact cutoff can be preserved.

Schedules use the latest completed session and the screen’s saved definition at the time of each run. They do not use the page’s historical As of selection or unsaved editor changes. Python scheduling is unavailable in the first release; Python remains Coming soon.

Prepared fields and saved scan results both count toward storage allowances. If a run is refused for storage, open the saved screen’s Run history, export anything you need, and remove unneeded results. Retained audit metadata still occupies space, so removing results does not necessarily reduce usage to zero. Compact prepared runs already omit candles; retrying without chart history does not free their retained result storage. Expired preparation is reclaimed through maintenance when its work has settled.

Agents can read the latest 50 notifications with ata_get_screener_notifications, optionally using unreadOnly or runId. The tool authorizes every referenced run and its comparison before returning payloads. If a notification is outside the current research scope, the page is refused; filtering to an authorized runId can narrow the request. Its unread count covers the returned page. Use ata_mark_screener_notifications_read with an explicit nonempty list of notification ids to mark those items read.

Open Run history to compare results and the schedule dialog to inspect its next run, last run, and consecutive failures. The first successful run of a definition can notify you of existing matches; subsequent entry/exit notices depend on comparable evaluations of the same definition.

Missing bars or errors do not become an entry or exit. Check unavailable comparisons and universe changes in the run record when a symbol disappears from a comparable set. Equity holidays are skipped; delayed provider data is shown as unavailable rather than a fresh observation.

Repeated failed scheduled runs produce an in-app warning after three failures and disable the schedule after ten. Inspect the run’s error code and resolve data access, capacity, or execution problems before enabling it again. Use the schedule switch to disable monitoring or Remove to delete the schedule.

See Screener overview for retained definitions and exports. Custom Python remains Coming soon.

Check for new results is off by default. When enabled for a saved screen, the visible browser tab checks completion metadata every five minutes. It does not start scans, read market data, reload result rows, or refresh notifications. Choose New results available · View to open the result through the normal access checks. The displayed result stays unchanged until you choose it.

Hidden tabs stop checking. Temporary errors back off with jitter, up to thirty minutes; an access refusal stops checking. Each visible tab checks independently. Recurring execution is configured only through Schedule, with Daily or Weekly runs and at most three active schedules per account.