ib-gateway-mcp

Gateway health

get_health

Read-only

Determine if the IB Gateway connection is usable and get the reason when it is not. Includes actionable hints and an optional probe for live verification.

Instructions

Report whether the Interactive Brokers gateway connection is usable, and why not.

Call this first when another tool fails with not_connected or times out. It never
fails itself. `state` is one of:
- connected: everything works.
- connecting: a connection attempt is in progress.
- not_accepting: the gateway refused or ignored the connection (it is down, logged out,
  or waiting for the user to approve 2FA). Retries run in the background.
- connectivity_lost: the gateway is up but cut off from IBKR's servers; usually heals.
- not_connected: stopped, or the connection dropped and a retry is pending.
`hint` explains what to do. `trading_enabled` says whether the trading gate is open
(order tools also need `circuit_open` false: after repeated IBKR rejections the
circuit breaker halts order submits until a human resets it). `api_read_only` means
the gateway's own settings reject orders. `is_paper` is true when the login only has
paper accounts. `market_data_type` is the data type requested for this session
(set_market_data_type changes it), and `subscriptions_used`/`subscriptions_max` show
how many streams are open. Pass probe=true to test the connection with a real
request (the state alone can lag behind a stalled socket).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`probe`	No	Also send one request to the gateway (its clock) to prove the connection answers right now; the outcome is in `probe`. Takes up to IB_REQUEST_TIMEOUT.

Output Schema

TableJSON Schema

Name	Required	Description
`hint`	No	What is wrong and what to do, when not connected.
`host`	Yes
`port`	Yes
`probe`	No	Result of the live round trip; null unless probe=true was asked.
`state`	Yes
`accounts`	No	Accounts this server may use (the allowlist).
`is_paper`	No	True when every managed account is a paper account (None: unknown).
`client_id`	Yes
`last_error`	No
`circuit_open`	No	True when the order circuit breaker tripped after consecutive IBKR rejections: submit_order refuses new orders, modifications and exercises until a human resets it (reset_circuit_breaker, admin toolset). Cancels still work.
`api_read_only`	No	The gateway rejected a request because its API is read-only (321).
`orders_synced`	No	Whether this session loaded the open and completed orders (skipped when no order toolset is enabled). Informational only: trading_enabled decides whether order tools work.
`server_version`	No	TWS API server version (when connected).
`connected_since`	No
`trading_enabled`	Yes	Whether the trading gate is open right now: connected, accounts allowed, live trading permitted, API not read-only. Order submits are also refused while circuit_open is true.
`market_data_type`	No	Market data type requested for this session (live, frozen, delayed...).
`circuit_threshold`	No	Consecutive rejections that trip the breaker; null when disabled.
`subscriptions_max`	No	Subscription limit (IBKR_MCP_MAX_SUBSCRIPTIONS).
`circuit_rejections`	No	Consecutive IBKR order rejections since the last accepted order.
`subscriptions_used`	No	Open streaming subscriptions.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 23, 2026

TDQS

A4.7/5.0

Behavior5/5

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

The description adds substantial behavior beyond the annotations: it never fails itself, enumerates all possible state values with meanings, explains circuit breaker behavior, api_read_only, paper accounts, market data type, subscription limits, and probe semantics. This goes far beyond readOnlyHint=true and openWorldHint=true with no contradiction.

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 long but every sentence earns its place by defining state semantics, related gates, and probe behavior. The lead sentence states the purpose immediately, and the state list is structured for quick agent parsing.

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 health-check tool with a rich output schema, the description covers when to call it, what each state means, what related fields like trading_enabled and api_read_only indicate, and how to force a live check. Nothing an agent needs to invoke it correctly is missing.

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 single parameter probe is fully documented in the schema (100% coverage), so the baseline is 3. The description adds extra meaning by explaining why to use probe: the state alone can lag behind a stalled socket. This justifies the step above baseline.

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 specific verb and resource: 'Report whether the Interactive Brokers gateway connection is usable, and why not.' It clearly identifies this as a health/diagnostic tool and distinguishes it from sibling data-retrieval tools by positioning it as the first call when other tools fail.

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

Usage Guidelines4/5

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

It explicitly tells the agent when to use it: 'Call this first when another tool fails with not_connected or times out.' It also explains when probe=true is appropriate. It does not explicitly contrast with get_connection_info or state when not to use it, so it stops short of a 5.

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

Deploy Server