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.
Read your saved screener results
Section titled “Read your saved screener results”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.
Bind research for research-scoped results
Section titled “Bind research for research-scoped results”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.
A practical MCP sequence
Section titled “A practical MCP sequence”| Step | Tools and checks |
|---|---|
| Discover graphical fields | ata_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 rule | Use 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 declaration | ata_render_screener_python renders the read-only SCANNER declaration; it does not convert the rule into executable Python |
| Save | ata_create_screener_screen saves the name, universe, interval, and Standard rule; daily history is fixed at 250 bars; supply an idempotencyKey |
| Revise | Read with ata_get_screener_screen, then update with ata_update_screener_screen and its expectedRevision |
| Price and execute | Read ata_quote_screener_run, then call ata_run_screener_screen with screenId, asOfDate, and a stable retry idempotencyKey |
| Read the result | Poll ata_get_screener_run; after success, page through ata_get_screener_run_rows, checking coverage and all statuses |
| Recover the tested definition | ata_get_screener_run_definition returns the frozen rule, universe, lookback, and revision admitted for that run |
| Inspect and share | ata_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 screens | ata_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.
Example: a small dated research screen
Section titled “Example: a small dated research screen”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.
Reuse prepared Standard fields
Section titled “Reuse prepared Standard fields”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.
- Save a Standard Daily screen. A schedule always belongs to a saved screen; it cannot target an unsaved draft.
- 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.
- Choose Daily or Weekly, with a time and, for weekly runs, a weekday.
- 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.
Storage and retained results
Section titled “Storage and retained results”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.
Review monitoring changes
Section titled “Review monitoring changes”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 saved results
Section titled “Check for new saved results”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.