Gateway health
get_healthRead-only
Check the Interactive Brokers gateway connection status and diagnose why it might be unusable. Call this first when other tools fail with not_connected or timeouts.
Instructions
Report whether the Interactive Brokers gateway connection is usable, and what is known about 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; this alone doesn't say
why. 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. `last_disconnect_at` is when the connection last went down,
kept after it comes back (this server's start time if it started during the outage).
`login_state` (if configured) is the gateway's login phase: restarting or logging_in
(in progress), awaiting_2fa (the account holder must approve a challenge), throttled
(paused until retry_at; it logs in again then only if its login automation is set to
retry), login_rejected (it won't retry), login_idle (nothing is retrying), unknown
(detail says why), or logged_in, which only means the last login in the gateway's log
succeeded; later events aren't logged there, and an old log_updated_at is normal then.
Without login_state, relay hint and report last_disconnect_at; don't guess a cause the
hint doesn't name.
`trading_enabled` says whether the trading gate is open (order tools also need
`circuit_open` false: after repeated IBKR rejections the breaker halts 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
requested data type (set_market_data_type), and `subscriptions_used`/`subscriptions_max`
count open streams. 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 | Default |
|---|---|---|---|
| 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 | ||
| login_state | No | The gateway's login phase, read from its launcher.log; null unless IB_GATEWAY_SETTINGS_DIR is set. | |
| 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. | |
| last_disconnect_at | No | When the connection last went down (UTC), kept after it comes back, so with connected_since it gives the last outage window. If the gateway was already down when this server started, the server's start time (the outage may be older). Null while no outage has been seen. | |
| subscriptions_used | No | Open streaming subscriptions. |