ib-gateway-mcp

Stream 5-second bars

subscribe_realtime_bars

Read-only

Stream 5-second OHLCV bars for a contract into a ring buffer for retrieval and real-time analysis.

Instructions

Start streaming 5-second OHLCV bars for one contract into a ring buffer.

A new bar arrives every 5 seconds; get_subscription_data returns them oldest first
with open, high, low, close, volume, VWAP and trade count. Only 5-second bars exist;
for other sizes use subscribe_bars. One stream per contract, what_to_show and
use_rth: subscribing again returns the same handle. Uses a market data line and
counts against IBKR's historical data pacing. Needs market data permissions; TRADES
is not available for forex (use MIDPOINT). Errors 420 and 162 mean IBKR refused the
request (invalid for the contract, or pacing). Stop it with unsubscribe.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`use_rth`	No	True: regular trading hours only. False: include pre-market, after-hours and overnight data.
`contract`	Yes	The instrument. A con_id alone is unambiguous; otherwise give symbol and sec_type, plus expiry, strike and right for options.
`buffer_size`	No	How many of the newest bars the server keeps (720 = one hour).
`what_to_show`	No	Build bars from TRADES, MIDPOINT, BID or ASK prices.	TRADES

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

Behavior4/5

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

The annotations declare readOnlyHint=true and openWorldHint=true, so the safety profile is already known. The description adds valuable behavioral context beyond the annotations: the ring buffer semantics, the 5-second cadence, the oldest-first return order, the one-stream-per-contract deduplication (subscribing again returns the same handle), the market data line consumption, and the pacing implications. It also discloses that TRADES is not available for forex. This is rich behavioral disclosure that goes well beyond what annotations provide, though it doesn't detail the exact output schema structure (which is covered by the output schema).

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 compact and information-dense, with every sentence earning its place. It front-loads the core action ('Start streaming 5-second OHLCV bars') before diving into details. The structure flows logically: what it does, what you get, how it differs from alternatives, deduplication behavior, resource implications, permissions, and error handling. No filler or redundancy.

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?

For a subscription tool with an output schema, annotations, and 100% schema coverage, the description is complete. It covers the subscription lifecycle (start, retrieve via get_subscription_data, stop via unsubscribe), the data cadence, the ring buffer semantics, the deduplication behavior, resource consumption, permissions, forex caveat, and error codes. An agent has everything it needs to decide whether to call this tool and how to interpret the result. The output schema covers the return structure, so the description doesn't need to.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all four parameters (contract, use_rth, buffer_size, what_to_show) with descriptions. The tool description adds some context beyond the schema: it explains that buffer_size relates to the ring buffer, that what_to_show=TRADES is not available for forex (use MIDPOINT), and that use_rth affects whether pre-market/after-hours data is included. However, most of the parameter semantics are already in the schema, so the description's incremental contribution is moderate. Baseline 3 is appropriate.

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 states a specific verb ('Start streaming'), a precise resource ('5-second OHLCV bars for one contract'), and the delivery mechanism ('into a ring buffer'). It also distinguishes itself from the sibling subscribe_bars by explicitly noting that only 5-second bars exist and other sizes should use subscribe_bars. This is a clear, specific, and well-differentiated purpose statement.

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

Usage Guidelines5/5

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

The description provides explicit usage guidance: it names the alternative (subscribe_bars) for other bar sizes, states the one-stream-per-contract behavior, and gives concrete conditions for when to use MIDPOINT instead of TRADES for forex. It also mentions error codes 420 and 162 as indicators of IBKR refusal, which helps an agent decide whether to retry or switch approaches. This is comprehensive usage guidance.

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

Deploy Server