NexusTrade Financial MCP Server

⚠ COSTS LLM CREDITS on the NexusTrade account — spins up an Aurora agent via Router V5 classification + ReAct execution loops, billed per token. **Manual approval required**: do NOT call unless the user explicitly asked to launch an Aurora agent. For strategy creation/backtesting/analysis prefer no-LLM tools: structured create_portfolio (pass full IPortfolio JSON), backtest_portfolio, query_backtest_history, query_*, fetch_portfolios. Create a new autonomous Aurora agent using the same body shape as POST /api/agent. When maxIterations or automationMode are omitted, applies the user's saved ChatSettings. Agent models are product-locked (openai/gpt-5.6-luna planner, meta/muse-spark-1.3-contributor:thinking-high executor, and the platform tool-role defaults) and cannot be overridden. Pass attachment_ids from upload_chat_attachment (READY) to bind files onto the last user message — same as the web FILES tab. Use this for a method-brief PDF plus a short analyze/report request.

Aurora agent surface (no LLM cost on this call — pure DB read). Only relevant when the user is actively working with an Aurora agent. Returns status, plan, messages, config. Address by agentId OR by exact title (case-insensitive); provide exactly one. Duplicate titles fail closed with candidate ids. Polling/liveness: use agent.lastProgressAt (advances during sandbox steps, tool cards, LLM rounds, and — while waiting_for_subagents — when children progress) — NOT agent.updatedAt (state transitions only; stays frozen by design while parked on subagents so the waiting-no-wake detector can prefilter). For waiting_for_subagents, a frozen lastProgressAt means children stopped progressing; confirm via child agent statuses. Sandbox step detail: agent.messages[*].data.steps. Poll until status is terminal (complete/stopped/error).

Aurora agent surface (no LLM cost on this call — pure DB read). Only relevant when inspecting an Aurora agent run. Raw trace / trajectory events for an agent (for inspection or building evaluator input). Address by agentId OR exact title (XOR).

Submit an asynchronous historical backtest for a portfolio over a date range. Minute interval: first-look default is the last 90 inclusive calendar days; hard max is 365 days — do not emit 2010 or a multi-year Minute window, and do not split a longer span into yearly Minute jobs. Daily equity may use a long window. Set baseline_symbol to match the book — underlying ticker for single-name options (AAPL→AAPL), per-underlying baselines or equal-weight universe B&H for multi-name options; SPY only for broad equity. Returns a backtest ID immediately; poll query_backtest_status, then query_backtest_history (zero-LLM). Aurora may also use Read Backtest for an LLM narrative once complete.

Return a time series of {time, value, cash, positionValue, comparisonValue, reservedCollateral} per tick for a completed backtest. Reads from the backtesthistories collection (full minute-resolution; 30-day TTL). Use this to find suspicious single-tick portfolio value jumps without needing the codebase — feed the result through your own jump-detection logic. Cash is derived as value minus Σ(position.quantity × lastPrice). `reservedCollateral` is the collateral locked by open positions at that tick, as the engine computed it; it reads `null` for a run made before collateral reporting existed, which is NOT zero. Never re-derive it from cash − buyingPower. Zero research token cost.

Return the parent backtest document's status, error, interval, timestamps, elapsed time, and completed statistics without reading history/events. Use immediately after backtest_portfolio or before query_backtest_history so ERROR/PENDING/RUNNING states are explicit. Statistics include peakReservedCollateral and medianReservedCollateral — how much capital the book actually had on the line, which a percentage return does not say. Both read "not recorded" for a run made before collateral reporting existed; that is not zero, so do not report it as such. Zero research token cost.

Deep-copy a source portfolio (chat OR deployed) into a NEW chat portfolio with fresh strategy IDs and no YAML/NL re-authoring. Use this — NOT create_portfolio — whenever an existing portfolio must remain the exact semantic baseline. Omit patches (or pass []) for a clone-only control; supply RFC-6902 JSON-Pointer patches (op/path/value) only for deliberate surgical changes. Patch paths target the IPortfolio shape and are action-type-specific: DynamicRebalance cash/deploy → `/strategies/0/action/deploymentPercent` (number 0–100); RebalanceOption book budget → `/strategies/0/action/totalBudget/amount`. Never put totalBudget on DynamicRebalance or deploymentPercent on RebalanceOption — validation rejects the wrong field. Requires source_portfolio_id and name. Pass dry_run:true to validate without persisting. Result is an independent chat portfolio; backtest it to evaluate.

Fetch one portfolio with full strategy objects (condition, action, indicators), positions, and spread-grouped holdings. Zero LLM cost — same data path as GET /api/portfolio/:portfolioId. Resolves deployed paper/live portfolios first, then chat portfolios. Use fetch_portfolios to discover IDs. Response includes conditionFieldAudit (comparison, value, window.length per base condition) — use that for Gate-7/Gate-8 deploy verification, NOT strategy.name or condition.name (those may be stale after GA mutation).

Deploy, undeploy, rename, delete, add/remove/replace strategies, or set deployment frequency on portfolios. **rename** requires a non-empty `name` on the operation. **delete** permanently removes a chat, paper, or live portfolio (archives deployed paper/live books; deleting a chat portfolio also archives linked deployments). Pass confirmLive:true only after explicit user confirmation when deleting an active live portfolio. **Structured path (zero LLM cost):** pass an `operations` array — see inputSchema. Use `replaceStrategy` / `replaceStrategies` with full `{name, condition, action}` strategyObjects (same shape as create_portfolio). RebalanceOption: set `action.positionScope` to `portfolio` (single-book — closes/orphans all option spreads in the portfolio) or `strategy` (multi-strategy book).

⚠ COSTS LLM CREDITS — re-runs the Aurora planner LLM after appending the user's follow-up. Manual approval required; do NOT call unless the user explicitly asked to push a message into an active Aurora agent. Address by agentId OR exact title (XOR). Send a follow-up user message to an agent and re-run the planner, matching POST /api/agent/:agentId/message. This can charge planning tokens, rejects actively running/approved states, may recover terminal states, may transition the agent, and publishes websocket updates. It is not an append-only operation.

⚠ COSTS LLM CREDITS — same path as POST /api/chat. Router V5 classifies the message: Ask Clarity (persisted), Create Agent (spawns Aurora research), or single-tool fulfill (queued prompt job). Use this for chat turns; use create_agent only when you explicitly want agent spawn without single-tool fulfill. Aurora chooses the complete route adaptively.

Aurora agent surface (no LLM cost on this call itself — pure DB read). Useful only when the user is actively operating an Aurora agent. For strategy creation/backtesting prefer the structured no-LLM tools (create_portfolio with full JSON payload, backtest_portfolio, query_*, fetch_portfolios). List your Aurora agents with pagination using the same query shape as the agent controller.

⚠ INDIRECTLY COSTS LLM CREDITS — approving the plan unfreezes the agent which then runs more planning + execution LLM calls. Manual approval required; do NOT call unless the user explicitly told you to advance their Aurora agent. Approve a semi-automated agent that is waiting in pending_plan_approval or pending_action_approval. Auto-detects which approval the agent needs and emits the matching state-machine event so the agent resumes execution. Returns 400 if the agent is not in a pending-approval state.

Aurora agent surface (no LLM cost — pure DB write). Only relevant when managing Aurora agents. Archive an agent (soft-delete). The agent remains in the database but is hidden from default listings. Address by agentId OR exact title (XOR).

Preview/builder twin of create_portfolio. Runs the SAME construction + per-strategy validation (Portfolio/Strategy/Condition/Indicator) as create_portfolio but PERSISTS NOTHING. Accepts the same IPortfolio JSON (all fields optional so partial drafts can be checked). Returns the canonicalized portfolio plus a per-component issue list (path + component + message) so you can see exactly which strategy/condition/indicator is wrong before committing. A draft that previews clean cannot fail on create_portfolio. Zero research token cost. Custom data sources: none yet. Create one with run_compute (pass name and point_kind to promote its signal output directly), or use dataset_to_indicator with a saved dataset; then reference customIndicatorId in create_portfolio.

Replace a deployed (paper/live) portfolio's entire strategy set with deep copies of a source portfolio's strategy objects (by reference, not YAML). Source is a chat or deployed portfolio; the target MUST be a real deployed portfolio (chat portfolios are immutable and cannot be a target). Use this to deploy a chat portfolio's strategies onto a live/paper portfolio without re-describing them. Do NOT automatically backtest after clone — only backtest when the user asked for research validation. The source's prior backtest does not validate the target (different objects), but deploy-only asks should stop at clone/deploy.

⚠ MUTATING — creates or modifies a portfolio. Fork strategies from a shared portfolio into the user's account. target: 'new' creates a chat portfolio; 'existing' patches a deployed portfolio. mode: 'replace' (default) removes old strategies, 'append' keeps them. For monetized portfolios, subscribe first. Returns { forkSharedPortfolioResult: { portfolioId, name, addedCount, removedCount, ... } }. Prefer fork when the user wants to edit/customize strategies.

List or search your portfolios with lightweight metadata (strategy id + name). Matches portfolio name, strategy names, and tickers — same workspace search as the dashboard / GET /api/chat-portfolio. include_chat_portfolios returns workspace DRAFTS only (excludes deployedMirror rows). Recover a past chat draft: include_paper=false, include_live=false, include_chat_portfolios=true, search="Delta 0.07" (then get_portfolio for full strategy JSON). Returns an object: { portfolios, page, limit, total, totalPages, scopes }. Deployed and draft rows page as one list (all deployed, then all drafts), so every row is reachable by walking pages. When search is set, include_positions defaults to false. Use analyze_portfolios only when you need LLM-written analysis.

Search and browse publicly shared portfolios from other NexusTrade users, sorted by performance metrics. Optional profileId filters to one creator's public/monetized books (from Search Creators / /p/:profileId).

Aurora agent surface (minimal LLM cost — state transition, no re-planning). Only relevant when actively managing an Aurora agent. Reject a semi-automated agent that is waiting in pending_plan_approval or pending_action_approval. Mirrors POST /api/agent/:agentId/reject, marks the latest assistant message as errored, transitions through the state machine, traces the rejection, and publishes a websocket update.

Aurora agent surface (no LLM cost — pure DB write). Star or unstar a top-level agent for quick sidebar access. Mirrors PATCH /api/agent/:agentId/star. Address by agentId OR exact title (XOR). Omit starred to toggle.

Aurora agent surface (no LLM cost — pure state transition). Only relevant when actively managing an Aurora agent. Stop a running agent. Sends a cancellation request and cascades to all descendant subagents. The agent must be in an active state (running, initializing, pending approval, etc.).

Aurora agent surface (no LLM cost — pure DB write). Only relevant when managing Aurora agents. Restore an archived agent so it appears in default agent listings again. Address by agentId OR exact title (XOR).