# Leroy MCP Leroy is a research-only evidence service for external trading agents. Connect your agent to the MCP endpoint and call `evaluate_current_setup` before it makes a decision that needs historical context. ## Connection - MCP endpoint: `/api/mcp` - Authentication: `Authorization: Bearer lr_live_...` - Transport: Streamable HTTP - The API key is created after the account owner explicitly activates MCP in Account. ## Request body Call `evaluate_current_setup` with this JSON body: ```json { "symbol": "AAPL", "side": "buy", "entry_price": 212.34, "holding_horizons": [ 5, 15, 30, 60 ], "stop_price": 209, "target_price": 218 } ``` ### Request fields - `symbol`: Required US equity ticker. Leroy normalizes it to uppercase. - `side`: Required direction: `buy`, `sell`, or `both`. - `entry_price`: Optional proposed entry price, retained as context only. - `holding_horizons`: Optional forward horizons in minutes. Supported values are 5, 15, 30, and 60. - `stop_price` / `target_price`: Optional setup context; neither places an order. - `client_request_id`: Optional caller idempotency key for safely retrying a request. The agent does not upload candles. Leroy resolves the current verified market frame available for the requested symbol. It uses the optional price levels and horizons to describe the setup, not to execute it. If the ticker is not present in the current verified read model, Leroy returns status `unavailable` with an explicit availability explanation and no fabricated market frame or historical result. ## Historical coverage Prepared Market Memory is built from Leroy's immutable point-in-time feature store derived from the January 4, 2010 source corpus. After the required point-in-time warmup, usable historical feature rows cover 4,088 ready sessions from March 31, 2010 through the verified July 1, 2026 session. That historical contract contains 1,800 point-in-time symbols and the registered strategy suite (41 strategies in this release). The response reports the active registry count and lineage rather than assuming that count remains fixed. All eligible source rows are indexed; the artifact separately reports horizon-specific label coverage because boundary rows may not yet have a mature 5-, 15-, 30-, or 60-minute label. Those labels are never inferred. The prepared release may also carry a separately identified forward overlay across the fixed 200-symbol public-replay universe. Its exact verified session count and date boundary are returned in provenance and market_memory.coverage; clients must use those fields rather than assuming a fixed freshness window. market_memory.coverage.forward_overlay_freshness reports current, behind, unavailable, or unknown and includes the latest verified session plus lag in completed sessions. Forward-overlay matches are exposed only when that status is current; a stale overlay is withheld rather than presented as current evidence. It must not be described as 1,800-symbol historical coverage. Provisional open-session data is never inserted until close compaction and verification. Market Memory is a prepared evidence index. Requests never scan raw minute data or the feature-store Parquet tree on demand. ## Evidence Strength Each Market Memory match includes a `match_strength` object. The score is a strict evidence tier: 5/5 is Exact Setup, 4/5 is Cross-Ticker Setup, 3/5 is Signal Pattern, 2/5 is Contextual Analogue, 1/5 is Direction-Only Baseline, and 0/5 is No Comparable Evidence. Leroy selects the strongest available tier; it does not pool lower tiers into the displayed result. ## Response body A response has this shape. This example is intentionally a no-match result and contains no fabricated performance: ```json { "evaluation_id": "eval_example_not_a_live_result", "status": "no_comparable_sample", "request": { "symbol": "AAPL", "side": "buy", "entry_price": 212.34, "holding_horizons": [ 5, 15, 30, 60 ], "stop_price": 209, "target_price": 218 }, "current_market_frame": { "symbol": "AAPL", "source_time": "2026-08-18T14:30:00.000Z", "frame_status": "available", "quote": { "bid": null, "ask": null, "last": null, "spread_bps": null } }, "strategy_states": [], "strategy_coverage": { "realtime_registered_count": 0, "realtime_evaluated_count": 0, "realtime_research_sensor_count": 0, "realtime_execution_adapter_count": 0, "historical_strategy_count": 41, "forward_overlay_strategy_count": 41 }, "active_confluence": null, "setup_geometry": null, "market_memory": null, "historical_evidence": [ { "side": "buy", "horizon_minutes": 15, "availability": "not_available", "reason": "No validated comparable sample was available for this setup.", "sample_size": null, "average_return_pct": null, "win_rate": null, "profit_factor": null, "lift_vs_baseline_bps": null } ], "assumptions": { "matching": "Only exact supported setup matches are returned; no silent broadening.", "costs": "Not included unless explicitly stated in the historical result.", "execution": "No execution result is inferred when spread, latency, fill, or market-impact data is unavailable." }, "provenance": { "evidence_status": "not_matched", "published_at": null }, "research_boundary": { "broker_write_authority": "none", "paper_trading": false, "investment_advice": false, "live_order": false }, "usage": { "lookup_cost": 1, "included_lookups": 100, "used_lookups": 1, "lookups_remaining": 99, "overage_lookups": 0, "overage_amount_usd": 0 }, "presentation": { "format": "markdown", "state": "no_comparable_sample", "text": "## **AAPL** · Buy\n\n🟢 **Market Open**\n\nNo exact historical setup is available for the requested timeframes. Leroy did not substitute a broader baseline.\n\nHistorical observations are descriptive, not investment advice." } } ``` ### Response fields - `presentation`: The ready-to-render human response. Render `presentation.text` verbatim for a user and retain the other structured fields for agent inspection. `format: plain_text` with `state: market_closed` means regular-session trading is closed; it is not a current setup evaluation. `format: markdown` provides the compact live scorecard. - `evaluation_id`: Unique identifier for the evaluation response. - `status`: `evaluated` means comparable evidence was found; `no_comparable_sample` means the exact setup had no validated comparison; `unavailable` or `stale_frame` means the current frame was not usable. A stale-frame response can still include verified historical context, broader baselines, strategy states, and lineage. - `current_market_frame`: The symbol, frame time, availability, and quote context used for the evaluation. - `strategy_states`: The observed states of the supported strategies for the requested symbol and direction. - `strategy_coverage`: Separates the canonical realtime research-sensor count from the retained supervised/paper execution-adapter count and the historical strategy suite used to prepare Market Memory. It also reports forward-overlay freshness and lag when that lineage is available. - `active_confluence`: The strategy and market-context conditions that were active, when available. - `setup_geometry`: Context-only entry, stop, target, risk-per-share, reward-per-share, and reward-to-risk calculations when the relevant prices exist. It never infers an execution. - `historical_evidence`: Per-direction and per-horizon sample size, return, win rate, profit factor, and lift when a validated comparison exists. Unsupported values are null, not estimates. - `market_memory`: Prepared historical analogues, regime buckets, failure evidence, execution limitations, counterfactuals, and lineage. Exact and approximate matches are labeled explicitly. - `market_memory.matches[].match_strength`: The selected match's numeric evidence tier and machine-readable tier name. `row_count` belongs to that match only; it does not include lower tiers. - `assumptions`: Matching, cost, and execution caveats that apply to the result. - `provenance`: Public evidence availability metadata, including the version and SHA-256 of the source artifact used for the read. Market Memory lineage includes indexed-row and horizon-specific label coverage plus the verified-session boundary and freshness of any forward overlay. - `research_boundary`: Confirms that the response is research-only and has no order or brokerage authority. - `usage`: Lookup cost, cache status, remaining included lookups, and any overage amount. A missing comparison is a valid answer. The agent must not turn nulls into a forecast, substitute a nearby setup, or treat historical evidence as a guarantee. ## Market Memory tools Dedicated research-only tools include `get_current_confluence_leaders`, `search_market_memory`, `compare_historical_analogues`, `get_market_regime`, `explain_setup_failure`, `compare_against_benchmark`, `simulate_exit_policy`, `estimate_execution_conditions`, and `get_data_lineage`. They read the same verified live frame or prepared artifact and never scan raw tape during a request. Call `get_current_confluence_leaders` with `{ side: "buy", limit: 5 }` to rank current quote-fresh symbols by observed active signal agreement. This is one current-snapshot lookup, not five ticker evaluations. Follow it with `evaluate_current_setup` when historical evidence for a specific symbol is needed. The leaderboard is descriptive research, not a recommendation or order list. The optional `record_research_hypothesis` and `review_hypothesis_outcome` tools write only research notes to the authenticated account's journal. They cannot trade or change execution permissions. ## Evidence wake rules Use `create_evidence_alert` to set a rule that wakes the agent through a signed HTTPS webhook when a fresh open-session setup matches. The rule can require a minimum active-signal count, Market Memory match strength, win rate, average return, and one forward horizon. `list_evidence_alerts`, `pause_evidence_alert`, `resume_evidence_alert`, `test_evidence_alert`, and `delete_evidence_alert` manage the authenticated account's rules. The create response returns a signing secret once. Leroy signs the exact JSON body with HMAC-SHA256 and sends `X-Leroy-Event`, `X-Leroy-Delivery`, `X-Leroy-Timestamp`, and `X-Leroy-Signature: v1=...` headers. Verify the timestamp and signature before acting. Alert payloads are research-only evidence; no order is placed by Leroy. ## Usage Call `get_usage` with an empty JSON object when the agent needs current quota information. ```json {} ``` ```json { "period_start": "2026-08-01", "included_lookups": 100, "used_lookups": 1, "lookups_remaining": 99, "overage_lookups": 0, "overage_amount_usd": 0, "overage_rate_usd": 0.01, "billing_status": "ledgered", "research_boundary": { "broker_write_authority": "none", "paper_trading": false, "live_order": false } } ``` Free activation includes 100 MCP lookups per calendar month. A normal one-direction evaluation costs one lookup; `side: "both"` costs two. The current confluence leaderboard costs one lookup for the single scanner snapshot regardless of whether it returns one or five leaders. Identical requests for the same frame may be served from cache without another lookup. Paid plans include larger monthly allowances and bill additional lookups at $0.01 each; usage appears in the account ledger. ## Boundary Leroy is research-only. MCP has no paper-trading tool, brokerage connection, order submission, portfolio-management authority, or investment-advice output. The external agent remains responsible for its decision, risk controls, and execution.