Getting Started -- From Zero to First Trade

This guide walks through the complete flow from initial authentication to placing your first Iron Condor trade via the Assistatron MCP server.

Prerequisites

  • An MCP-compatible client (Claude Desktop, Claude Code, or any MCP client)
  • The Assistatron MCP server configured in your client
  • An Alpaca brokerage account (paper or live)

Step 1: Authenticate

Call login to start the device authorization flow.

-> login()
<- {
     "user_code": "ABCD-1234",
     "verification_uri": "https://auth.assistatron.com/activate",
     "device_code": "dc_abc123..."
   }

Open the URL in your browser and enter the code. Once approved, call check_login:

-> check_login(device_code="dc_abc123...")
<- {
     "status": "complete",
     "access_token": "at_...",
     "refresh_token": "rt_..."
   }

Save both tokens. The access_token is used for future sessions via the Authorization: Bearer header. The refresh_token is used when the access token expires.

See: ../tools/auth.md for full auth documentation.

Step 2: Complete Onboarding

Onboarding has 4 steps that must be completed in order.

2a. Accept the End User Agreement

The agent reads the legal://eua resource and presents the full EUA text. After you confirm agreement:

-> accept_eua(confirmed=true)
<- {"ok": true, "next_step": "acknowledge_risk"}

2b. Acknowledge Risk Disclosure

The agent reads the legal://risk-disclosure resource and presents the risk disclosure. After you confirm understanding:

-> acknowledge_risk(confirmed=true)
<- {"ok": true, "next_step": "set_risk_profile"}

2c. Set Your Risk Profile

Tell the agent about your experience and risk tolerance:

-> set_risk_profile(
     options_experience="a_few_times",
     iron_condor_experience="understand_not_traded",
     risk_tolerance="moderate"
   )
<- {"ok": true, "next_step": "set_account_mode"}

2d. Connect Your Broker

Set trading mode and provide Alpaca API keys:

-> set_account_mode(mode="paper")
<- {"ok": true, "next_step": "set_broker_keys"}

-> set_broker_keys(
     broker="alpaca",
     mode="paper",
     api_key="PK...",
     api_secret="..."
   )
<- {"ok": true, "next_step": null}

When next_step is null, onboarding is complete. The 4 root tools (account, strategy, trade, positions) are now visible.

See: ../tools/onboarding.md for full onboarding documentation.

Step 3: Open the Strategy Hub

-> strategy()
<- {
     "hub": "strategy",
     "tools_revealed": [
       {"name": "create_strategy", ...},
       {"name": "get_strategy_status", ...},
       {"name": "save_strategy", ...},
       {"name": "find_iron_condors", ...},
       ...
     ]
   }

Step 4: Create a Strategy

Run the optimizer for your chosen ticker and capital budget:

-> create_strategy(ticker="SPY", max_capital=50000)
<- {
     "status": "pending",
     "job_id": "a1b2c3d4-...",
     "message": "Call get_strategy_status('a1b2c3d4-...') to check progress."
   }

The optimizer runs in the background (1-3 minutes). Wait, then check status:

-> get_strategy_status(job_id="a1b2c3d4-...")
<- {
     "status": "completed",
     "result": {
       "top_strategies": [
         {"rank": 1, "cagr": 0.22, "win_rate": 0.81, "max_drawdown": 0.09, ...}
       ],
       "summary": "5 Pareto-optimal strategies found"
     }
   }

Review the results with the agent. The rank-1 strategy has the best risk-adjusted performance. See understanding-results.md for how to interpret each metric.

See: ../tools/create-strategy.md for full optimizer documentation.

Step 5: Save the Strategy

Bookmark the strategy you want to trade:

-> save_strategy(run_id="a1b2c3d4-...", strategy_rank=1, notes="First SPY strategy")
<- {"id": "e5f6g7h8-...", "run_id": "a1b2c3d4-...", "strategy_rank": 1}

The id is your saved_strategy_id for the next steps.

Step 6: Find Live Candidates

Scan the options chain for tradeable Iron Condors matching your strategy:

-> find_iron_condors(saved_strategy_id="e5f6g7h8-...")
<- {
     "ticker": "SPY",
     "total": 15,
     "candidates": [
       {
         "expiry": "2026-06-20",
         "short_put": 520.0, "long_put": 515.0,
         "short_call": 560.0, "long_call": 565.0,
         "net_credit": 1.42, "max_loss": 3.58,
         "pop": 0.74, "ror": 0.397
       }
     ]
   }

Review the candidates with the agent. Higher pop means more likely to profit. Higher ror means better return if profitable.

See: ../tools/find-iron-condors.md for full chain scan documentation.

Step 7: Propose an Entry

Select a candidate and propose the trade:

-> trade(
     action="propose_entry",
     ticker="SPY",
     candidate={...the candidate from step 6...},
     qty=2,
     saved_strategy_id="e5f6g7h8-..."
   )
<- {
     "id": "p1q2r3s4-...",
     "type": "entry",
     "status": "pending",
     "expires_at": "2026-05-12T14:31:00Z"
   }

The proposal is valid for 60 seconds.

Step 8: Confirm the Trade

Review the proposal details, then confirm:

-> trade(action="confirm", proposal_id="p1q2r3s4-...")
<- {order details from broker}

The order is now submitted to your Alpaca account.

Step 9: Monitor Your Position

-> positions(action="list")
<- [{"position_id": "...", "ticker": "SPY", "status": "open", ...}]

-> positions(action="assignment_risk", position_id="...")
<- {per-leg risk assessment}

Summary

The complete flow:

  1. login -> check_login -- authenticate
  2. accept_eua -> acknowledge_risk -> set_risk_profile -> set_broker_keys -- onboard
  3. strategy() -- open the strategy hub
  4. create_strategy -> get_strategy_status -- optimize
  5. save_strategy -- bookmark
  6. find_iron_condors(saved_strategy_id) -- find live candidates
  7. trade(propose_entry) -- propose
  8. trade(confirm) -- execute
  9. positions(list) -- monitor

What's Next