Canary
MCP tools reference
Generated by scripts/docgen/mcp-tools. Do not edit by hand — run make docs-regen after changing internal/mcp/tools.go.
These are the tools canary mcp exposes to MCP clients (Claude Code, Claude Desktop, or any other MCP host). Every public tool uses the canonical canary_* namespace. Each entry lists the tool name an LLM picks against, the description the LLM reads to decide whether to invoke, and the parameter schema the LLM binds against.
20 tools total. Listed in registration order, aligned with the agent-appropriate CLI commands. Local lifecycle commands such as setup, update, restart, mcp, daemon, and version are intentionally excluded from MCP tools.
canary_status
Read daemon, gateway, storage, and source health. Use for connectivity or degraded-input diagnosis; use canary_brief for the desk decision surface.
No parameters.
canary_trading_status
Read local broker-write readiness, pinned context, freeze state, and blockers. It only reports readiness and does not place, modify, or cancel orders.
No parameters.
canary_settings
Read platform settings and observed data quality. This tool cannot change settings or authorize a broker action.
No parameters.
canary_orders_open
Read-only current-context local order lifecycle view. It does not place, modify, cancel, or transmit orders and is not a broker statement.
No parameters.
canary_orders_history
Read-only bounded local order-journal history for the current account and mode. It does not place orders and is not an IBKR Activity Statement.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
event_limit |
integer | no | maximum lifecycle events returned per grouped order row; default 20, max 200. When truncated, rows carry events_truncated and total_events_count. |
limit |
integer | no | maximum grouped order rows to return; default 50, max 500 |
since |
string | no | optional inclusive lower boundary as YYYY-MM-DD UTC date or RFC3339 timestamp; default is 7 days before until |
until |
string | no | optional upper boundary as RFC3339 timestamp, or YYYY-MM-DD UTC date to include that whole UTC day; default is now |
canary_order_status
Read-only lifecycle and typed callback evidence for one locally journaled order. Broker free text is withheld; this tool cannot preview or change the order.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | yes | order identifier to inspect: local order_ref such as canary-20260528-093000, IBKR order ID, or permanent ID. Orders journaled before the product was renamed carry an ibkr- prefix instead; pass those through unchanged |
canary_account
Read account financials. The authority block identifies one concrete account and mode with availability, freshness, typed reason, and field presence; missing is never zero.
No parameters.
canary_positions
Read held positions and exposure. The authority block identifies one concrete account and mode with availability, freshness, and typed reason; stale or unavailable empty rows do not prove an empty book.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
symbol |
string | no | filter to a single underlying symbol (case-insensitive) |
type |
string | no | filter to stock or option positions |
view |
string | no | response shape: full returns existing stocks/options/by_underlying detail plus protection_coverage; risk returns compact portfolio aggregates, top exposures, option-health counts, protection coverage, and flagged option legs |
canary_strategies
Read how Canary groups currently held option legs into proportional strategies and which legs still need review. Use canary_positions for the full book. This tool cannot preview, submit, place, modify, cancel, or transmit an order.
No parameters.
canary_technical
Analyze explicitly named stock or ETF symbols using daily trend, relative strength, ATR, and liquidity evidence. This is analysis, not order entry.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
benchmark |
string | no | relative-strength benchmark, default SPY |
currency |
string | no | optional ISO currency override for symbols, e.g. USD or EUR |
exchange |
string | no | optional IBKR exchange override for symbols, e.g. SMART or IBIS |
lookback_days |
integer | no | calendar-day history lookback; default 420, enough for 200-DMA and 126 trading-bar returns |
market |
string | no | optional route for symbols, not the benchmark; omit/use us for SMART/USD, use de for Xetra/IBIS EUR equities |
primary_exchange |
string | no | optional primary-exchange hint for symbols, e.g. ARCA for ETFs or IBIS for Xetra |
symbols |
array | yes | ticker symbols, e.g. ["AAPL","MSFT","NVDA"] |
canary_calendar
Read official exchange sessions to plan work around market opens, closes, holidays, and early closes. Supports US cash equities, US listed options, and Xetra. Preserve timezone, source, coverage bounds, and session.state: unknown is not closed and cannot supply a trading schedule. This is an exchange-session calendar, not an economic-release or earnings calendar; use canary_brief for current held-name event context. Read-only; no scheduling, refresh, or broker actions.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
at |
string | no | optional RFC3339 instant including a timezone offset; evaluates the market at that instant and takes precedence over date |
date |
string | no | optional YYYY-MM-DD in the market timezone; evaluates that date at local noon. Omit for now; at takes precedence when both are supplied |
days |
integer | no | number of forward calendar dates including the selected date, not trading sessions; default 14, maximum 400 |
market |
string | no | exchange-session market; default us. US listed options models the regular 16:15 session; per-class exceptions and global/curb hours are not modeled |
canary_macro
Read cached economic releases, central-bank meetings and recent official publications for the trading day. Includes BLS, BEA, Federal Reserve and ECB sources with per-feed availability, original times and a bounded window. Missing or stale feeds do not mean nothing is scheduled. Preserve source_label/date-only precision and truncation. This is official-source coverage, not a licensed general-news or consensus feed. Use canary_calendar for exchange hours and canary_brief for the current book and risk. Read-only; does not fetch, acknowledge, schedule or trade.
No parameters.
canary_regime
Read the detailed broad-market regime: all eight indicators, independent clusters, confirmation eligibility, gamma horizons and skew, source health, and stale or unavailable evidence. Choose view=monitor for a compact dashboard projection or view=full (default) for detailed evidence. Use after canary_brief or for an explicit market-regime question; use canary_stress for how that market state affects the held portfolio. Gamma is a conditional amplification/damping model; open interest does not identify dealer inventory or market direction. Read-only; no history or refresh controls.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
include_profiles |
boolean | no | Include large gamma profile arrays; false by default. Scalar measurements, thresholds, warnings and freshness are always retained. |
view |
string | no | full (default) retains detailed evidence; monitor uses the shared compact dashboard projection. monitor cannot include gamma profile arrays. |
canary_stress
Read the full current portfolio-stress assessment: margin, P&L and tape shocks, exposure, concentration, protection coverage, held-name and options risk, market indicators, and source health. Use after canary_brief or for an explicit portfolio-risk question; use canary_regime for the detailed broad-market dashboard. Preserves the same shared assessment used by the app. Missing inputs cannot become healthy zero values. Advisory and read-only; cannot preview or submit orders or change limits.
No parameters.
canary_brief
Start here for the daemon's current desk summary: regime stage and verdict, portfolio-stress summary, breadth coverage, modeled gamma response and expiry horizons, and observed 25-delta option skew. Preserve freshness, rankability, source warnings and unavailable values. Gamma models potential amplification or damping; open interest does not prove bullish/bearish intent or dealer inventory, and put-call skew is relative option pricing, not a forecast. Use canary_regime for all market indicators and confirmation details, canary_stress for full portfolio-risk evidence, canary_status to diagnose degraded sources and canary_edge for retrospective decision outcomes; drill into canary_positions or canary_account only when the brief points there. Read-only; never acknowledges the brief or writes to the journal.
No parameters.
canary_reporting
Read shared IBKR statement-reporting setup, broker reachability, backfill state, absent sections, present-empty sections, and proven missing fields for Recon and Edge. Read-only; returns no Query ID or token and cannot validate candidates, refresh reports, or change setup.
No parameters.
canary_edge
Call with no arguments after canary_brief for an automatic one-year review of historical decision price outcomes: action/direction coverage, comparisons of the same decisions at different horizons, monthly consistency, concentration, and exact local protection provenance when available. SPY, QQQ, DIA, and VIX supply informational context. Options separately report option lifecycle coverage, proven flat-to-flat exact-contract positions, broker-reported realized option episodes, and the latest dated open option snapshot; these scopes overlap and must not be added. Use a returned change_id or returned option_id for broker-fact details; completed position cycles are already expanded in options.cycles. Do not use for current risk, order decisions, forecasting, or causal claims. Do not infer skill, strategy win rates, trade intent, or risk effectiveness. Use canary_brief for current portfolio risk and canary_positions for current holdings. Read-only; parameters select retained evidence and cannot refresh data.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
change_id |
string | no | optional opaque change ID returned by a prior canary_edge call |
horizon_sessions |
integer | no | optional explicit decision-price-impact horizon; omitted selects the longest adequately covered horizon automatically |
limit |
integer | no | maximum findings; default 3 |
option_id |
string | no | optional opaque option ID returned by a prior canary_edge call |
window |
string | no | optional review override; default 365d |
canary_rules
Read the daemon-evaluated desk rulebook, ranked findings, policy identity, and explicit unknown inputs. Advisory evidence never authorizes an order.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
symbol |
string | no | optional underlying symbol (case-insensitive) to narrow per-rule offender lists; portfolio verdicts are unaffected |
canary_proposals
Read-only protection candidates for existing positions. It can refresh discovery but cannot preview, submit, place, modify, cancel, or transmit an order.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
refresh |
boolean | no | when true, ask the daemon to recompute proposals before returning; otherwise returns the latest daemon snapshot |
show |
boolean | no | when true, records a shown audit event for returned proposal rows |
canary_opportunities
Read-only option-exercise candidates for existing positions. It can refresh discovery but cannot preview, exercise, submit, or expose an execution token.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
refresh |
boolean | no | when true, ask the daemon to recompute opportunities before returning; otherwise returns the latest daemon snapshot |
show |
boolean | no | when true, records a shown audit event for returned opportunity rows |