MCP
The package exposes provider-neutral MCP tooling for local stdio clients and remote HTTP clients.
Broker authentication remains separate from MCP authorization. MCP bearer tokens must never be forwarded to IBKR.
Local Stdio
ibkr-agent mcp serve --transport stdio --describe --json
ibkr-agent mcp serve --transport stdio --json
Use --describe for a smoke check that exits immediately. Omit it when wiring
an MCP client; the command then runs a line-oriented JSON-RPC stdio loop.
The local server lists only tools whose scopes are enabled by the current CLI
config. Every tools/call enforces the tool scope before backend access and
writes an audit event for completion, denial, refusal, or failure.
Example client configs live under examples/mcp-clients/.
Remote HTTP
Remote MCP is disabled by default and requires explicit configuration plus the independent safety flag. See remote-mcp-oauth.md.
Use --describe for a config smoke check, or omit it to bind the HTTP listener
and serve JSON-RPC requests on POST /mcp:
ibkr-agent mcp serve --transport http --describe --enable-remote-mcp --json
ibkr-agent --config config/remote.example.yaml mcp serve --transport http --enable-remote-mcp --bind 127.0.0.1:8080
The HTTP transport validates OAuth/OIDC bearer tokens, serves protected-resource
metadata, filters tool discovery by granted scopes, and routes authorized
tools/call requests through the same handlers as stdio.
Tool Registry
Read tools:
| Tool | Scope |
|---|---|
ibkr_health | ibkr:health:read |
ibkr_backend_status | ibkr:health:read |
ibkr_session_requirements | ibkr:health:read |
ibkr_session_renew | ibkr:health:read |
ibkr_kill_switch_status | ibkr:health:read |
ibkr_accounts_list | ibkr:accounts:read |
ibkr_account_metadata | ibkr:accounts:read |
ibkr_account_summary | ibkr:portfolio:read |
ibkr_pnl_daily | ibkr:portfolio:read |
ibkr_pnl_realtime | ibkr:portfolio:read |
ibkr_positions_list | ibkr:positions:read |
ibkr_portfolio_snapshot | ibkr:portfolio:read |
ibkr_contracts_search | ibkr:marketdata:read |
ibkr_contract_resolve | ibkr:marketdata:read |
ibkr_market_snapshot | ibkr:marketdata:read |
ibkr_historical_bars | ibkr:marketdata:read |
ibkr_options_chain | ibkr:options:read |
ibkr_option_greeks | ibkr:options:read |
ibkr_market_depth | ibkr:marketdata:depth:read |
ibkr_scanner_run | ibkr:scanner:read |
ibkr_news_list | ibkr:news:read |
ibkr_news_article | ibkr:news:read |
ibkr_fundamentals_get | ibkr:fundamentals:read |
ibkr_market_session | ibkr:calendar:read |
ibkr_market_holidays | ibkr:calendar:read |
ibkr_currency_rate | ibkr:currency:read |
ibkr_transfer_history | ibkr:transfers:read |
ibkr_orders_list | ibkr:orders:read |
ibkr_orders_history | ibkr:orders:read |
ibkr_order_status | ibkr:orders:read |
ibkr_executions_list | ibkr:orders:read |
ibkr_limits_status | ibkr:risk:read |
ibkr_audit_tail | ibkr:audit:read |
ibkr_audit_export | ibkr:audit:export |
Preview and paper tools are discoverable when their scopes are enabled:
| Tool | Scope |
|---|---|
ibkr_order_preview | ibkr:orders:preview |
ibkr_bracket_order_preview | ibkr:orders:preview |
ibkr_paper_order_submit | ibkr:orders:paper:submit |
ibkr_paper_order_cancel | ibkr:orders:paper:cancel |
ibkr_paper_order_modify | ibkr:orders:paper:modify |
ibkr_paper_bracket_order_submit | ibkr:orders:paper:submit |
ibkr_approvals_create | ibkr:approvals:create |
Live tools are discoverable when live scopes are enabled:
| Tool | Scope |
|---|---|
ibkr_live_order_submit | ibkr:orders:live:submit |
ibkr_live_order_cancel | ibkr:orders:live:cancel |
ibkr_live_order_modify | ibkr:orders:live:modify |
ibkr_live_bracket_order_submit | ibkr:orders:live:submit |
Live submit arguments are account_id, approval_id, preview_id, and
idempotency_key. Live modify arguments are account_id, broker_order_id,
approval_id, preview_id, idempotency_key, and at least one bounded
change. The handlers load approval, preview, live policy, writer, market
snapshot, and audit state from the server runtime; these values are not trusted
from the MCP payload. Successful submits are added to the live reconciliation
backlog. Cancel and modify results preserve the broker status, and only
terminal states are removed from pending reconciliation.
Bracket submit tools require three approvals that belong to the same server-persisted bracket preview. Mixed approvals from different preview groups are refused before any paper or live writer boundary. Paper bracket submit also persists durable idempotency state and consumes the three approvals after a successful grouped submit.
The first specs/009-mcp-tool-maturity/ additions are consultative and safety
read tools: PnL, order history, account metadata, kill switch status, live
limits status, MCP audit export, and explicit session renewal. Write-capable
modify additions are explicit (ibkr_paper_order_modify and
ibkr_live_order_modify), while the generic ibkr_order_modify name remains
forbidden.
The same maturity spec adds contextual reads for news, fundamentals, market
session/holiday data, FX rates, and transfer history. ibkr_approvals_create
is a gateway workflow write, not a broker write: it requires
ibkr:approvals:create and an existing unexpired preview persisted by the
server.
Forbidden Generic Write Tools
These generic write-like names remain forbidden:
ibkr_order_intent_validateibkr_order_preview_explainibkr_order_submitibkr_order_cancelibkr_order_modifyibkr_order_approve
Use the explicit preview, paper, or live-gated tools instead. Direct calls to
forbidden names return READONLY_WRITE_FORBIDDEN and are auditable.
Safety Boundary
Tool outputs must not include broker cookies, tokens, credentials, sensitive
headers, local secret paths, or raw Client Portal Gateway session material.
Scope checks happen before broker access. Missing scope returns
AUTH_MISSING_SCOPE and does not call the backend.