Tools reference · user-scoped v1

TradeJournal MCP Tools Reference

Every MCP and on-site agent call uses the same 18 tools below. Always start with get_runtime_context, then query trades, stats, or posts.

Connect AI MCP hub Free trial

Quick summary

  1. First tool: Always get_runtime_context (portfolios, plan, privacy).
  2. Trades & stats: list_trades, get_trade_stats, get_portfolio_stats.
  3. Posts: list_posts and get_post for published journal posts only.

Key takeaway

TradeJournal.co MCP tools are user-scoped: call get_runtime_context first, then list_trades, get_trade_stats, list_open_trades_by_target_priority, update_trade, and the rest documented on the tools reference page; the same definitions power the on-site AI assistant and external MCP clients.

Recommended call order

Agents should follow this sequence for reliable answers:

  1. get_runtime_context
  2. list_portfolios
  3. get_trade_stats
  4. list_trades
  5. list_open_trades_by_target_priority
  6. get_trade
  7. update_trade
  8. link_trade_unlinked_dividends
  9. get_dashboard_stats
  10. get_portfolio_stats
  11. list_posts
  12. get_post

Tool catalog (v1 read-only)

Tool Purpose Parameters
get_runtime_context Load user portfolios, active portfolio, and privacy rules. Call this first. —
list_portfolios List the user's portfolios (id and name). —
get_trade_stats Aggregate trade statistics for this user. portfolio_id: integer; status: op,cl,pl
list_trades List trades. position_size = /stats Cost (USD). asset=option|stock|etc. For 'option trades' do NOT filter status=cl only — include open and closed unless user asks for open/closed only. Use order_by=position_size_desc for largest cost. Open rows include optional price_target, stop_target, target_nudge. Target sort order_by values force status=op and sort by plan-level priority (past_target_first, nearest_target, etc.). portfolio_id: integer; symbol: string; status: op,cl,pl; asset: string; limit: integer; order_by: last_entry,position_size_desc,position_size_asc,largest_position,missing_targets_first,nearest_either,nearest_stop,nearest_target,past_target_first,smallest_position
list_open_trades_by_target_priority Open trades only, sorted by user's review priority (price target / stop nudges). Includes nudge_summary counts and nudged_trades sample. Use when user asks which open trades hit target, are near stop, or need plan levels. portfolio_id: integer; limit: integer; order_by: largest_position,missing_targets_first,nearest_either,nearest_stop,nearest_target,past_target_first,smallest_position
get_trade Get one trade by id with entry legs, entry/exit CPU, P/L drift check, portfolio_sizing (cost vs GAV), option_context (notional leverage, underlying price from Symbol store), optional plan levels (price_target, stop_target, target_nudge, suggested_price_target), and unlinked_dividends when imported broker dividends belong on this trade. Use when the user questions P/L, option leverage, import accuracy, targets, unlinked dividends, or links /trade/123/. For short trades, entry_type exit=sell-to-open and entry= cover buy. trade_id*: integer
update_trade Set or clear optional plan levels on a trade: price_target and stop_target. apply_suggested_price_target uses the user's default reward:risk from account settings when stop_target is set. Validates price target vs entry and stop vs price target. trade_id*: integer; price_target: number; stop_target: number; clear_price_target: boolean; clear_stop_target: boolean; apply_suggested_price_target: boolean
link_trade_unlinked_dividends Link imported broker dividend entries to a specific trade when get_trade shows unlinked_dividends or the user asks to fix 'dividend not linked' on a trade. Refreshes trade stats after linking. For portfolio-wide fixes use repair_portfolio_import_health action link_unambiguous_dividends. trade_id*: integer
get_dashboard_stats High-level public/private trade and post counts and profit. —
get_portfolio_stats Stats for one portfolio owned by this user. portfolio_id*: integer
list_posts List the user's published posts. limit: integer
get_post Get one published post by id. post_id*: integer
audit_portfolio_import_health Read-only audit for import/portfolio health: ghost trades, orphan entries, duplicate trades, stale wizard, overlapping imports, symbol net drift vs file, cached_profit drift, unlinked dividends (with linkable trade suggestions). Call before any repair. portfolio_id*: integer; import_id: string
update_media_asset Update media attribution fields (source, alt text, notes). media_id*: integer; alt_text: string; source_type: website,pdf,video,screenshot,social,other; source_url: string; source_title: string; source_notes: string
repair_portfolio_import_health Apply allowlisted import repairs (dry_run defaults true). Actions: remove_ghost_trades, clear_wizard_sessions, rerun_auto_process, refresh_portfolio_cached_profit, refresh_stale_trade_stats, link_unambiguous_dividends, purge_import_entries, reimport_statement. Requires confirm=true and dry_run=false to apply changes. portfolio_id*: integer; actions*: array; dry_run: boolean; confirm: boolean; import_id: string; purge_import_ids: array
get_media_asset Get one media library asset by id (must belong to this user). media_id*: integer
delete_media_asset Delete a media asset when it is not referenced on the site. media_id*: integer
list_media_assets List the user's media library images with attribution and site references. limit: integer; upload_context: quill,trade_image,profile,wizard,library

Source of truth: mcp_services.tools (same as on-site agent). Security guarantees · MCP hub · MCP spec.

Frequently asked questions

18 user-scoped tools including get_runtime_context, list_trades, list_open_trades_by_target_priority, get_trade, update_trade, get_trade_stats, import health audits, media tools, and more — see the full table on this page.

No. Authorization is always the token or session user; user_id is not accepted from tool arguments.

Yes. The web agent and MCP gateway call the same mcp_services implementations.

Start free trial — claim onboarding

Import trades, then ask real questions about your data.

Connect AI Start free trial Consulting