ib-gateway-mcp

Stream quotes

subscribe_quotes

Read-only

Start a live top-of-book quote stream for a single contract, returning a subscription handle to retrieve bid, ask, last price, sizes, OHLC, volume, and options greeks via get_subscription_data.

Instructions

Start streaming live top-of-book quotes for one contract (read with get_subscription_data).

Returns a subscription handle. get_subscription_data(subscription_id) then returns
the current quote (bid/ask/last, sizes, OHLC, volume, greeks for options), the
requested generic tick values under `extras`, and IBKR notices. There is one quote
stream per contract: subscribing again returns the same handle (`deduplicated`
true), adding any new generic ticks to it. Each stream uses one of the login's
market data lines (100 by default); streams nobody reads for `idle_ttl_s` seconds
are cancelled, and unsubscribe frees the line at once.

Needs market data permissions (see set_market_data_type for delayed data). If IBKR
refuses the stream right away (354, 10089, 10168, 10197), the call fails with the
reason; later problems show in the data as `active: false` and `error`.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`contract`	Yes	The instrument. A con_id alone is unambiguous; otherwise give symbol and sec_type, plus expiry, strike and right for options.
`generic_ticks`	No	Extra fields to stream: option_volume, option_open_interest, historical_volatility, avg_option_volume, implied_volatility (these five for stocks: the underlying's option statistics), index_future_premium, misc_stats (13/26/52-week high/low, average volume), mark_price, auction, rt_volume (time & sales, VWAP), shortable (short availability and shares), fundamental_ratios (needs a Refinitiv subscription), trade_count, trade_rate, volume_rate, rt_trade_volume, rt_historical_volatility, dividends, futures_open_interest, last_rth_trade, bond_factor_multiplier, short_term_volume (3/5/10-minute volume), ipo_prices, and for ETFs etf_nav_bid_ask, etf_nav_last, etf_nav_close, etf_nav_high_low, etf_nav_frozen_last (IBKR's intraday NAV of the fund).

Output Schema

TableJSON Schema

Name	Required	Description
`key`	Yes	What it streams for: the contract id plus parameters.
`kind`	Yes	What streams: quotes, depth, tick_by_tick, realtime_bars, bars, scanner, news_bulletins, news or display_group.
`contract`	No	The instrument, when there is one.
`created_at`	Yes
`idle_ttl_s`	Yes	Seconds without a read before it is cancelled.
`deduplicated`	No	True when an identical stream was already open and its handle was returned instead of opening a second one.
`subscription_id`	Yes	Handle for get_subscription_data and unsubscribe.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 23, 2026

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint and openWorldHint annotations, the description discloses one-stream-per-contract deduplication, the market data line quota, idle-timeout cancellation, immediate vs deferred error reporting with specific IBKR error codes, and the data shape available via get_subscription_data. This is rich, non-obvious behavioral context that materially helps an agent manage the subscription lifecycle.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but efficient: three short paragraphs front-load the core action and handle, then cover deduplication, resource limits, lifecycle cancellation, permissions, and failure modes. Every sentence contributes useful information, and no filler or repetition is present.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the rich output schema and annotations, the description is complete for correct invocation and management of the subscription. It covers what the stream returns, how to read it, deduplication semantics, market data line usage, idle cancellation, permissions, and both immediate and deferred error behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides 100% description coverage for both contract and generic_ticks. The tool description adds value beyond the schema by explaining that requested generic ticks appear under `extras` and that resubscribing with new generic ticks extends the same stream rather than creating a new one.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise verb and resource: 'Start streaming live top-of-book quotes for one contract.' It clearly differentiates the tool from snapshot, historical, market-depth, and tick-by-tick siblings, and immediately names the companion get_subscription_data for reading the stream.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives strong operational context: use it for live per-contract top-of-book quotes, pair it with get_subscription_data, and be aware of market data permissions and delayed-data routing. However, it never names rival subscription tools such as subscribe_realtime_bars, subscribe_tick_by_tick, or subscribe_market_depth, nor states when one would prefer this tool over them, so the usage guidance is implied rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server