alpaca-trading-paper-trading-mcp

name	alpaca-trading-paper-trading-mcp
description	Preview, submit, inspect, and manage Alpaca paper-trading orders using the Alpaca Trading API MCP Server. Supports US equities, options, and crypto. Use this skill when you want your AI agent to execute paper trades through MCP tool calls — no CLI installation or direct API coding required.

Alpaca Paper Trading — MCP Server Version

Use this skill when you want your AI agent to preview, submit, inspect, and manage paper-trading orders using the Alpaca Trading API MCP Server.

This skill is written for you, a Trading API user working with your own Alpaca paper-trading account. Your agent calls MCP tools directly — no CLI installation or raw HTTP requests needed. The MCP server handles authentication and API communication.

This is the MCP-server-specific version. A generic (implementation-agnostic) version and a CLI version are also available as companion skills.

---

0 — How your AI agent should use this skill

1. Start with the signal source. Whether it originates from a backtest result, a manual trading idea, a scheduled trigger, or a conversational request — identify what is driving the trade.
2. Reiterate strategy logic and confirm with you. Your agent must restate the trading idea in its own words and wait for your confirmation before proceeding.
3. Gather and confirm ALL configurations. Timing, asset class, symbol, side, quantity or notional amount, order type, time-in-force, limit/stop prices, extended-hours flag, risk controls (position limits, max order size, loss thresholds), and margin intent.
4. Discover available MCP tools. Your agent must call GetDynamicTools to find the Alpaca MCP namespace and inspect available tool schemas before calling any tool. Tool names and parameters vary by MCP server implementation — never assume.
5. Verify paper environment. Read env.ALPACA_PAPER_TRADE from the host's MCP config file — no tool exposes it — and require it to be absent, true, 1, or yes. Then confirm the account is active and unblocked. If paper mode cannot be proven, STOP immediately and tell you.
6. Show a complete order preview table. Every parameter that will be sent to the order-placement tool must be visible to you before submission.
7. Ask whether you want explicit confirmation before each order (default: ON). Respect your preference for the rest of the session.
8. Submit via the order-placement tool for the asset class. Placement is split across stock, crypto, and option tools — select by asset class, then pass the confirmed parameters exactly as previewed.
9. Monitor with the order lookup and order list tools. Report fills, rejections, partial fills, and portfolio impact.
10. Never place live trades. Verify paper environment before every submission.

---

1 — Prerequisites

Required

• Alpaca Trading API MCP Server installed and configured in your agent host (Cursor, etc.)
• Paper trading API key and secret configured as environment variables in the MCP server configuration — never pasted into chat or passed as tool arguments
• MCP server namespace discoverable via GetDynamicTools
• Paper trading account active at Alpaca

Conditional

• Options trading: must be enabled on your Alpaca paper account
• Crypto trading: must be enabled on your Alpaca paper account

MCP Server Setup (Cursor)

The server is Alpaca's official MCP server, maintained at alpacahq/alpaca-mcp-server. That repository's README is the source of truth for the package name, command, and environment variables. The configuration below reflects v2.

Add it to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "alpaca-paper-trading": {
      "command": "uvx",
      "args": ["alpaca-mcp-server"],
      "env": {
        "ALPACA_API_KEY": "your-paper-key",
        "ALPACA_SECRET_KEY": "your-paper-secret",
        "ALPACA_PAPER_TRADE": "true"
      }
    }
  }
}

Variable	Required	Default	Purpose
ALPACA_API_KEY	Yes	—	Paper API key
ALPACA_SECRET_KEY	Yes	—	Paper secret key
ALPACA_PAPER_TRADE	No	true	Paper/live switch; false selects live. This skill requires true.
ALPACA_TOOLSETS	No	all	Comma-separated toolsets to expose. Leaving it unset means you have all capabilities. Set it (for example account,trading,assets) only to narrow what the agent can reach.

Paper versus live is determined solely by ALPACA_PAPER_TRADE. The server derives the API host from that flag, so there is no base-URL variable to set and none to verify.

Verifying the MCP server is available

Your agent should run:

GetDynamicTools with pattern "alpaca"

If the namespace is not found, appears in "error" or "loading" state, or has namespaceStatus: "needsAuth":

1. If "needsAuth" — authenticate via mcp_auth for that namespace, then retry.
2. If "error" or not found — tell you to check the MCP server configuration in Cursor settings.
3. Do not fall back to direct HTTP calls or CLI commands. This is the MCP version.

---

2 — Gather inputs

Input table

Parameter	Required	Default	Notes
symbol	Yes	—	Ticker symbol (e.g., AAPL, BTC/USD, AAPL251219C00250000)
side	Yes	—	buy or sell
qty	One of qty/notional	—	Number of shares/units. Whole or fractional. Mutually exclusive with notional
notional	One of qty/notional	—	Dollar amount. Stocks: market orders with day TIF only. Crypto: market orders only. Not available on place_option_order
type	No	market	Stocks: market, limit, stop, stop_limit, trailing_stop. Crypto: market, limit, stop_limit. Options: market, limit. The parameter is type, not order_type
time_in_force	No	day (stocks), gtc (crypto), day (options)	Stocks: day, gtc, opg, cls, ioc, fok. Crypto: gtc or ioc only — day and fok are rejected. Options: day only
limit_price	If limit/stop_limit	—	Limit price
stop_price	If stop/stop_limit	—	Stop trigger price
trail_percent

The bracket legs are flat scalar parameters, not nested objects. POST /v2/orders takes nested take_profit: { limit_price } and stop_loss: { stop_price, limit_price }, but the place_* tools flatten them, and their schemas set additionalProperties: false — so passing the nested REST shape is a hard rejection, not a silently ignored field. This is the general hazard: the tools deliberately reshape the REST body, so never build parameters from the REST schema.

Additional context gathered

Input	Required	Default	Notes
asset_class	Inferred	us_equity	us_equity, crypto, us_option
strategy_description	Recommended	—	Natural-language description of the trade rationale
risk_controls	Recommended	—	Max position size, max loss threshold, portfolio concentration limit
mcp_namespace	Discovered	—	The MCP namespace where Alpaca tools are available (via GetDynamicTools)

Strategy confirmation checklist

Before proceeding to order preview, your agent must confirm:

• Strategy intent restated in plain language
• Symbol, side, and quantity/notional confirmed
• Order type and all price levels confirmed
• Time-in-force confirmed
• Extended-hours intent confirmed (equities)
• Risk controls confirmed (or explicitly waived)
• Asset-class-specific requirements confirmed (options approval, crypto eligibility)
• Paper environment verified

---

3 — Source-of-truth references

Source	URL	Used for
Alpaca MCP Server	https://github.com/alpacahq/alpaca-mcp-server	Server setup, environment variables, toolsets, current tool list
Alpaca Trading API docs	https://docs.alpaca.markets/us/docs/trading-api	Order parameters, account fields, asset details
Create Order reference	https://docs.alpaca.markets/us/reference/postorder	Underlying REST semantics only — not the tool parameter shape. The place_* tools flatten and constrain this schema, so always build parameters from the discovered tool schema
Order types guide	https://docs.alpaca.markets/us/docs/orders-at-alpaca	Order type behavior, TIF rules, extended hours
Options trading	https://docs.alpaca.markets/us/docs/options-trading	Options order requirements, exercise/assignment
Crypto trading	https://docs.alpaca.markets/us/docs/crypto-trading	Crypto pairs, 24/7 trading, fractional units
Account API	https://docs.alpaca.markets/us/reference/getaccount-1	Account status fields, buying power, PDT
Alpaca disclosures	https://alpaca.markets/disclosures	Disclosure language

Discovery rule

Your agent must call GetDynamicTools to discover the actual MCP namespace, tool names, and parameter schemas before calling any tool. The names this skill cites are those of the official server at v2; confirm them, and never assume a parameter format.

---

4 — Workflow

Phase 1: Strategy Confirmation

Step 1 — Identify the signal source.

Determine where the trade idea originates:

• Backtest result (reference the run folder and signal)
• Manual idea from you ("I want to buy 100 shares of AAPL")
• Scheduled or conditional trigger ("Buy when AAPL drops below $180")
• Portfolio rebalance ("Close my TSLA position and rotate into NVDA")

Step 2 — Reiterate the strategy.

Your agent restates the trade in its own words:

"You want to buy 10 shares of AAPL as a market order, good for the day, in your paper account. This is a manual directional trade — no stop loss or take profit attached. Is that correct?"

Step 3 — Wait for your confirmation.

Do not proceed until you confirm. If you correct any detail, your agent re-confirms the updated version.

Phase 2: Configuration Agreement

Step 4 — Gather all order parameters from the input table above.

Step 5 — For limit, stop, or bracket orders, confirm all price levels.

Step 6 — Confirm time-in-force and extended-hours settings.

Step 7 — Confirm risk controls:

• Maximum position size in this symbol
• Maximum single-order notional value
• Portfolio concentration limits
• Stop-loss or take-profit levels (if bracket)

Step 8 — For options: confirm the contract symbol, position intent (buy_to_open, etc.), and that options trading is enabled.

Step 9 — For crypto: confirm the trading pair (e.g., BTC/USD), quantity precision, and 24/7 availability.

Phase 3: MCP Discovery and Paper Account Verification

Step 10 — Discover the Alpaca MCP namespace.

Call GetDynamicTools with pattern "alpaca" to find the namespace.
Then call GetDynamicTools with the found namespace to list all available tools.

Your agent inspects the available tools and their parameter schemas. This step must happen every session — tool names and schemas may change between MCP server versions.

Step 11 — Fetch account status via MCP.

Call the account-info tool — get_account_info as of v2; confirm the name against discovery.

From the response, verify:

• status = ACTIVE
• trading_blocked = false
• account_blocked = false

Paper mode itself is established by the server's ALPACA_PAPER_TRADE setting, not by these fields.

Step 12 — STOP gate: prove paper mode from the MCP client config, then stop if you cannot.

The MCP server does not expose ALPACA_PAPER_TRADE to your agent. There is no tool, resource, or server-instruction field that reports it, so the agent cannot ask the server which mode it is in. The only place that value is readable is the client's own MCP configuration file.

That file also holds ALPACA_API_KEY and ALPACA_SECRET_KEY in the same env block, so your agent must not read the file as a whole — no cat, no file-read tool, no printing the server entry. Reading it wholesale would pull the credentials into model context and violate the data-handling guarantee in §8. The gate needs exactly one value, so it extracts exactly that one value:

# 1. List server names (names are not secrets)
jq -r '.mcpServers | keys[]' ~/.cursor/mcp.json

# 2. Confirm the chosen entry exists, then read only the flag
jq -r '.mcpServers | has("<server-name>")' ~/.cursor/mcp.json
jq -r '.mcpServers["<server-name>"].env.ALPACA_PAPER_TRADE // "unset"' ~/.cursor/mcp.json

On a host without jq, the equivalent single-value read:

python3 -c 'import json,sys;d=json.load(open(sys.argv[1]));e=d["mcpServers"][sys.argv[2]].get("env") or {};print(e.get("ALPACA_PAPER_TRADE","unset"))' ~/.cursor/mcp.json '<server-name>'

Substitute the host's own config path when it is not Cursor. Your agent then:

1. Identifies the server entry backing the namespace it discovered its Alpaca tools from, and confirms that entry exists — step 2 above.
2. Requires the flag to be unset, or set to true, 1, or yes (case-insensitive). The server lowercases the value and tests membership in exactly that set, so any other value selects live — including paper, TRUE with a trailing space, and yes!.

Distinguish the two ways a read comes back empty, because they are not equivalent. A confirmed entry whose flag is unset passes — the server defaults to paper when the variable is absent. An entry that cannot be found, or a config that cannot be parsed, is an inconclusive read, not a passing one, and the value printed for it is indistinguishable from a genuinely absent flag. Never let the second case be read as the first.

If the config cannot be read or parsed, the server entry cannot be identified, or the value is anything outside that set, the gate fails closed. Your agent stops and tells you:

"⚠️ I cannot confirm this MCP server is in paper mode. This skill only supports paper trading. Check that ALPACA_PAPER_TRADE is true in the server's env block and that the configured keys are paper keys, then restart the client."

Your agent must never treat the account response as proof. Live and paper accounts return the same shape, so an account payload can never by itself establish the environment — treat unproven as live. Two weaker signals may corroborate a passing config check but must never substitute for it: paper accounts commonly return an account_number beginning PA, and status may be PAPER_ONLY. Neither is a documented guarantee.

Do not proceed under any circumstances if paper mode is unproven.

Step 13 — From the account response, check:

• buying_power — sufficient for the planned order
• options_trading_level — if trading options. This is the effective level (the minimum of options_approved_level and the configured max_options_trading_level), so gate on it rather than on options_approved_level
• options_buying_power — if trading options
• crypto_status — if trading crypto
• multiplier — margin classification, and the only PDT signal the account object carries: 4 means a PDT account

The account object has no pattern_day_trader, daytrade_count, or daytrading_buying_power field. Your agent must not read them.

Step 14 — Show account summary:

┌─────────────────────────────────────────┐
│         Paper Account Summary           │
├─────────────────────┬───────────────────┤
│ Account ID          │ xxxxxxxx          │
│ Status              │ ACTIVE            │
│ Environment         │ PAPER             │
│ Equity              │ $100,000.00       │
│ Buying Power        │ $200,000.00       │
│ Cash                │ $100,000.00       │
│ Options Approved    │ Level 2           │
│ Crypto Status       │ ACTIVE            │
│ PDT                 │ No                │
└─────────────────────┴───────────────────┘

Phase 4: Order Preview

Step 15 — Build the order parameters object. Do NOT call the submit tool yet.

Construct the exact parameter set that will be sent to the order-placement tool selected in Step 19:

{
  "symbol": "AAPL",
  "side": "buy",
  "qty": "10",
  "type": "limit",
  "limit_price": "185.50",
  "time_in_force": "day",
  "client_order_id": "pt-20260726-001-aapl-buy"
}

Step 16 — Display the order preview:

┌─────────────────────────────────────────┐
│           ORDER PREVIEW                 │
├─────────────────────┬───────────────────┤
│ Symbol              │ AAPL              │
│ Side                │ BUY               │
│ Quantity            │ 10 shares         │
│ Order Type          │ LIMIT             │
│ Limit Price         │ $185.50           │
│ Time in Force       │ DAY               │
│ Extended Hours      │ No                │
│ Order Class         │ Simple            │
│ Est. Notional       │ $1,855.00         │
│ Client Order ID     │ pt-20260726-...   │
│ Environment         │ PAPER (verified)  │
├─────────────────────┴───────────────────┤
│ ⚠ Paper trading only. Not financial    │
│   advice. Past performance ≠ future.   │
└─────────────────────────────────────────┘

Step 17 — If confirmation is ON (default): wait for your explicit "yes" or "go ahead" before submitting.

Step 18 — If you previously set confirmation to OFF: show the preview, pause briefly to let you read it, then proceed.

Phase 5: Order Submission via MCP

Step 19 — Select the order-placement tool for the asset class, then call it.

There is no single create-order tool. Placement is split by asset class, so the tool is chosen from the asset class confirmed in Step 7:

Asset class	Tool (as of v2)	Supports
US equity / ETF	place_stock_order	market, limit, stop, stop-limit, trailing-stop, brackets
Crypto	place_crypto_order	market, limit, stop-limit
US option	place_option_order	single-leg and multi-leg

Each takes its own schema — the order types available for stocks are not all available for crypto, so read the schema of the specific tool you selected rather than reusing parameters from another. Confirm the name and parameters against discovery before calling; the names above are current for v2 and are not guaranteed across versions.

Call place_stock_order with:
  symbol: "AAPL"
  side: "buy"
  qty: "10"
  type: "limit"
  limit_price: "185.50"
  time_in_force: "day"
  client_order_id: "pt-20260726-001-aapl-buy"

Step 20 — Parse the response.

Extract from the MCP response:

• id — the Alpaca order ID
• client_order_id — your idempotency key
• status — initial order status (new, accepted, pending_new)
• created_at — submission timestamp
• filled_qty, filled_avg_price — if immediately filled (market orders)

Step 21 — On failure:

If the MCP tool call returns an error:

Error type	Action
Insufficient buying power	Show current buying power, suggest reducing quantity or using a limit order
Invalid symbol	Verify the symbol with the asset lookup tool (get_asset as of v2), suggest corrections
Invalid parameters	Show the parameter that failed validation, reference the correct schema
Market closed (for day TIF)	Show market hours via the clock tool, suggest gtc or waiting for open
Options not enabled	Tell you to enable options trading in Alpaca dashboard
Account restricted	Show the restriction reason, suggest contacting Alpaca support
MCP tool error	Show the raw error, suggest checking MCP server logs

Log the failed attempt in order_log.csv with status FAILED and the error message.

Phase 6: Post-Submission Monitoring via MCP

Step 22 — Check order status.

Call the single-order lookup tool — get_order_by_id as of v2 — with the order ID from Step 20. If the submission outcome was ambiguous and you have no order ID, look the order up by your idempotency key instead, using get_order_by_client_id.

Report the current status and any fill information.

Step 23 — List all open orders (if requested or useful context).

Call the order-list tool — get_orders as of v2 — filtered to open orders.

Show a summary table of all open orders.

Step 24 — Return order summary:

┌─────────────────────────────────────────┐
│           ORDER SUBMITTED               │
├─────────────────────┬───────────────────┤
│ Order ID            │ abc-123-def       │
│ Symbol              │ AAPL              │
│ Side                │ BUY               │
│ Qty                 │ 10                │
│ Type                │ LIMIT @ $185.50   │
│ Status              │ NEW               │
│ Submitted           │ 2026-07-26 15:30  │
│ Environment         │ PAPER (verified)  │
├─────────────────────┴───────────────────┤
│ Next: Check status, modify, or cancel.  │
└─────────────────────────────────────────┘

Step 25 — Order lifecycle reporting.

As the order progresses, your agent reports state transitions:

Status	Report to you
new / accepted	Order is live, waiting for fill
partially_filled	Show filled qty, remaining qty, avg fill price
filled	Show total filled qty, avg fill price, estimated cost
canceled	Confirm cancellation, show any filled portion
expired	Note expiration (TIF elapsed), suggest resubmission if appropriate
rejected	Show rejection reason, suggest remediation
replaced	Show old → new order details

For filled or partially filled orders, calculate portfolio impact:

• New position size (or change to existing position)
• Estimated cost basis
• Remaining buying power
• Portfolio weight of this position

Phase 7: Portfolio Impact via MCP

Step 26 — Fetch all positions.

Call the all-positions tool — get_all_positions as of v2.

Show a positions summary table.

Step 27 — Fetch a specific position (if checking a single symbol).

Call the single-position tool — get_open_position as of v2 — for the symbol in question.

Show position details: qty, avg entry, current price, unrealized P&L, market value.

Step 28 — Fetch updated account.

Call the account-info tool again — get_account_info as of v2.

Show updated equity, buying power, and cash after the trade.

Step 29 — Portfolio risk summary:

┌─────────────────────────────────────────────┐
│         Portfolio Risk Summary              │
├──────────────────┬──────────────────────────┤
│ Total Equity     │ $99,850.00              │
│ Cash             │ $98,000.00              │
│ Market Value     │ $1,855.00               │
│ Buying Power     │ $196,000.00             │
│ Positions        │ 1                       │
│ Largest Position │ AAPL (100% of invested) │
│ Unrealized P&L   │ +$5.00 (+0.27%)         │
│ Day P&L          │ +$5.00                  │
└──────────────────┴──────────────────────────┘

Phase 8: Order Management via MCP

Step 30 — Cancel a specific order.

Call the single-order cancel tool — cancel_order_by_id as of v2 — with the order ID.

Confirm cancellation. Note: filled orders cannot be canceled.

Step 31 — Cancel all open orders.

Call the bulk cancel tool — cancel_all_orders as of v2. This acts on every open order in the account at once, so show the list it will affect and get confirmation before calling it, even when confirmation mode is OFF.

Confirm how many orders were canceled. Show any that could not be canceled (already filled/filling).

Step 32 — Replace (modify) an existing order.

Call the replace tool — replace_order_by_id as of v2 — with the order ID and only the fields being changed.

Show the old → new comparison table. Only unfilled or partially-filled orders can be replaced.

Step 33 — Close a single position.

Call the single-position close tool — close_position as of v2. It takes symbol_or_asset_id (required) and optionally either qty or percentage, which are mutually exclusive. Omitting both closes the entire position.

This is not a cancellation — it submits a market sell order for the position, so it moves real (paper) money and is subject to market hours. If the market is closed the order queues and executes at the next open, which means the fill price is unknown at the time you approve it. Your agent states this explicitly when the market is closed rather than implying the position is already flat.

Your agent shows the position it is about to close — symbol, quantity, market value, and unrealized P&L — and requires explicit confirmation. Confirmation mode governs order entry, and this is order entry, so an OFF setting does not skip the confirmation for a liquidation. After the call it reports the resulting order ID and monitors it to a terminal state exactly as it would any other order.

Step 34 — Close all positions.

Call the bulk close tool — close_all_positions as of v2. Its one parameter, cancel_orders, cancels every open order before liquidating when set to true.

This is the most destructive operation in the skill: it liquidates the entire portfolio, including positions this session never opened, and with cancel_orders: true it destroys resting orders too. Your agent first shows the full inventory it will affect:

• Every open position, from the positions list tool, with symbol, quantity, market value, and unrealized P&L
• The total market value being liquidated
• Every open order that cancel_orders: true would cancel, if that flag is being set

It then states the count, and requires an explicit "yes" — always, regardless of confirmation_mode. Only then does it call the tool. Afterward it reports how many positions were closed and surfaces any that failed, since a partial failure leaves the portfolio in a half-liquidated state that you need to know about.

Step 35 — Options exercise.

Exercising is irreversible and settles into the underlying, so exercise_options_position and do_not_exercise_options_position (as of v2) both carry the same explicit-confirmation requirement as Step 34. Your agent shows the contract, the resulting underlying obligation, and the cash impact before calling either one, and never issues an exercise instruction on its own initiative.

Phase 9: Deployment Guidance (on request)

If you ask about automating these trades beyond interactive sessions:

MCP-based automation

• MCP servers are session-based and typically run within an agent host like Cursor
• For recurring MCP-based trades, explore Cursor automations or scheduled agent triggers
• The MCP server must be running and authenticated for each session

Standalone automation

• For production-grade automation, use the Alpaca SDK directly:
  • Python: alpaca-py (pip install alpaca-py)
  • TypeScript/JavaScript: @alpacahq/alpaca-trade-api or @alpacahq/typescript-sdk
• Cron + SDK script for scheduled strategies
• Cloud functions (AWS Lambda, GCP Cloud Functions) for event-driven trading
• Webhook-based triggers from TradingView or custom signal providers

Standalone automation leaves this skill's guarantees behind. The Step 12 paper gate covers MCP tool calls in an interactive session; an SDK script running under cron, a cloud function, or a webhook has no MCP server and no gate. The script must assert paper itself, at startup, and exit if it cannot — construct the client with paper=True as a literal rather than reading the endpoint from configuration, and abort if a live endpoint or live-trading flag is present in the environment. A live account returns the same response shape as a paper one, so nothing later in the run will surface the error.

Always:

• Validate any new automation against paper for a meaningful period before considering live at all
• Implement circuit breakers (max daily loss, max orders per day, max position size)
• Log all orders and monitor for unexpected behavior
• Your agent does not recommend specific cloud providers or infrastructure choices

---

5 — Execution rules

Universal rules

1. Paper only. This skill is exclusively for paper trading. Your agent must verify the paper environment before every order submission.
2. No financial advice. Your agent executes trades at your direction. It does not recommend trades, predict prices, or suggest strategies.
3. Confirmation by default. Your agent asks for explicit confirmation before each order unless you opt out.
4. Idempotency. Every order gets a unique client_order_id to prevent duplicate submissions on retry.
5. Complete transparency. Every parameter sent to the MCP tool must be shown to you in the preview.
6. Fail safe. If any verification step fails (account check, paper verification, buying power), your agent stops and explains.
7. No interpolation. Your agent uses exactly the parameters you confirmed — never infers "you probably meant" and silently changes values.
8. Disclose limitations. If the MCP server does not support a requested feature (e.g., a specific order type), your agent tells you rather than attempting a workaround.
9. Gate unscoped destructive tools. cancel_all_orders, close_all_positions, close_position, exercise_options_position, and do_not_exercise_options_position act on holdings this session may never have created, and the last three are irreversible. Your agent lists exactly what each call will affect and requires explicit confirmation regardless of confirmation_mode, which governs order entry only.
10. Closing a position is order entry. The close tools submit market sell orders rather than deleting a position. They obey market hours, queue to the next open when the market is closed, and fill at an unknown price. Your agent monitors the resulting order to a terminal state instead of reporting the position as flat on the call returning.

MCP-specific rules

11. Always discover tools first. Call GetDynamicTools to find the Alpaca namespace and inspect tool schemas before calling any tool. Tool names cited in this skill are current for v2 and are documentation, not a contract — v2 was a rewrite in which none of the v1 tools survived, and a name can persist across versions while its schema changes. Confirm against discovery and never hard-code a parameter schema.
12. Handle namespace states. If the MCP namespace is "needsAuth", authenticate via mcp_auth. If "error" or not found, tell you to check the MCP server configuration.
13. No raw HTTP fallback. This is the MCP version — do not fall back to direct HTTP API calls or CLI commands if the MCP server is available and functioning. This governs how your agent reaches Alpaca. It does not forbid reading the local MCP config for the Step 12 paper gate, which touches no Alpaca endpoint.
14. Auth errors are not retryable with different credentials. If an MCP tool call fails with an authentication error, tell you to check the MCP server configuration. Do not retry with different credentials or attempt to pass API keys as tool arguments.
15. MCP tool calls do not need required_permissions: ["all"]. They run through the MCP protocol, not the shell.
16. Respect MCP server boundaries. If the discovered schema does not include a parameter you expect (e.g., position_intent for options), do not invent it — tell you and reference the API docs for workarounds.
17. Re-discover on error. If an MCP tool call fails with an unexpected schema error, re-discover tools with GetDynamicTools in case the server was updated.

Asset-class-specific rules

18. Equities — Verify the symbol exists and is tradable via the asset lookup tool before ordering. Check for stock splits, halts, or delistings.
19. Options — Verify options approval level. Resolve the contract through the option contracts tool rather than trusting a hand-built OCC symbol (e.g., AAPL251219C00250000). Confirm position_intent.
20. Crypto — Use the slash-pair format (e.g., BTC/USD). Note 24/7 trading availability. Fractional quantities are common — confirm precision.

---

6 — Output contract

Run folder structure

runs/<YYYYMMDD-HHMMSS>-paper-trading-mcp/
  notes.md              # Strategy description, assumptions, risk controls
  orders.json           # All MCP order responses (create, get, list)
  order_log.csv         # Chronological log of all order actions
  positions_snapshot.json  # Position state after trades
  portfolio_summary.md  # Account and portfolio state
  review.md             # Session review and lessons learned

notes.md

Contains:

• Strategy description and rationale
• All confirmed parameters
• Risk controls in effect
• Paper environment verification details
• Any assumptions made
• Timestamps

orders.json

Array of all order-related MCP responses captured during the session:

[
  {
    "action": "create",
    "timestamp": "2026-07-26T19:30:00Z",
    "request": {
      "symbol": "AAPL",
      "side": "buy",
      "qty": "10",
      "type": "limit",
      "limit_price": "185.50",
      "time_in_force": "day"
    },
    "response": {
      "id": "abc-123-def",
      "status": "new",
      "filled_qty": "0",
      "created_at": "2026-07-26T19:30:01Z"
    }
  }
]

order_log.csv

timestamp,action,order_id,client_order_id,symbol,side,qty,type,limit_price,stop_price,tif,status,filled_qty,filled_avg_price,error
2026-07-26T19:30:00Z,CREATE,abc-123-def,pt-20260726-001,AAPL,buy,10,limit,185.50,,day,new,0,,
2026-07-26T19:31:00Z,STATUS,abc-123-def,pt-20260726-001,AAPL,buy,10,limit,185.50,,day,filled,10,185.48,

positions_snapshot.json

Captured from the list-positions MCP response after all trades are complete.

portfolio_summary.md

Human-readable summary of account state, positions, and risk metrics after the session.

review.md

Post-session review: what was traded, outcomes, lessons, what to do next.

Note: Unlike CLI output, MCP responses are not automatically saved as raw files. Your agent must capture relevant response data and write it to orders.json and order_log.csv explicitly.

---

7 — Validation and tests

Pre-submission checks

Your agent validates before every order submission:

Check	How	Fail action
Paper environment	env.ALPACA_PAPER_TRADE in the host's MCP config is absent, true, 1, or yes. Not readable from any tool — read the config file. Fail closed if unreadable	STOP — tell you to reconfigure
Account active	status == "ACTIVE"	STOP — account issue
Trading not blocked	trading_blocked == false	STOP — account restricted
Sufficient buying power	buying_power >= est_notional	STOP — show buying power, suggest smaller order
Symbol tradable	Get-asset tool	STOP — symbol not found or not tradable
Options approved	Account options level	STOP — tell you to enable options
Crypto enabled	Account crypto status	STOP — tell you to enable crypto
Valid order type	Schema validation	STOP — show valid order types
Valid TIF	Schema validation	STOP — show valid TIF options
Price levels present	Limit/stop price for limit/stop orders	STOP — ask for missing price
Client order ID	UUID generated	Generate if missing

Post-submission checks

Check	How	Fail action
Order accepted	Response status	Report rejection reason
No duplicate	client_order_id uniqueness	Warn if duplicate detected
Fill within expectations	filled_avg_price vs limit_price	Alert if unexpected

MCP-specific validation tests

Validate these MCP-specific failure modes:

• MCP namespace not found
• MCP namespace needs authentication
• MCP tool schema changes
• MCP server configured for live environment
• MCP tool call network errors

---

8 — Disclosures, safety, and data handling

Disclosures

Your agent must include these disclosures:

• Before every order preview:

  "Paper trading only. Not financial advice. Past performance does not guarantee future results."

• If discussing strategy performance:

  "Paper trading results are simulated and may not reflect real-world execution, slippage, or market impact."

• If discussing options:

  "Options involve significant risk and are not suitable for all investors. Paper trading options does not carry financial risk, but the strategies tested may involve substantial risk if applied to live trading."

• Full disclosures. Review Alpaca's disclosures and agreements at alpaca.markets/disclosures.

Important disclosure: This material is for informational, educational, and research purposes only. It is not investment advice, a recommendation, an offer, or a solicitation to buy or sell securities, options, cryptocurrencies, or any other financial product. All investing and trading involve risk, including possible loss of principal. Paper trading is simulated and may differ from live trading in fills, market impact, liquidity, fees, latency, and other factors. Review Alpaca's disclosures at https://alpaca.markets/disclosures.

Safety

• Never place live trades. This skill checks for paper environment, but the MCP server configuration is ultimately your responsibility.
• Never expose API keys. Keys are configured in the MCP server environment, not passed through the agent.
• Never provide financial advice. Your agent executes orders at your direction and reports facts. It does not recommend trades.
• Circuit breaker awareness. If you submit many rapid orders, your agent should note the pace and ask if it is intentional.
• Destructive tools are gated independently of confirmation mode. Turning per-order confirmation OFF speeds up order entry. It never waives the explicit "yes" required for close_all_positions, cancel_all_orders, close_position, or an options exercise instruction.
• The default toolset is the full toolset. ALPACA_TOOLSETS defaults to all capabilities, so liquidation and exercise tools are reachable in any default install. Scope the variable if you want them out of the agent's reach entirely rather than relying on the gate alone.

Data handling

• MCP tool calls go through the MCP protocol to the Alpaca API. Credentials live in the server's configuration and are never passed as tool arguments, so tool calls never place them in your agent's context.
• The one point where your agent touches the file holding those credentials is the Step 12 paper gate. It reads a single field from that file and must never read, print, or echo the file or the server entry as a whole. If your agent cannot extract just that field, it fails the gate rather than falling back to a wholesale read.
• Order data is saved locally in the run folder structure (see §6).
• No trading data is sent to third-party services beyond Alpaca.
• Your agent's conversation context may include order details — treat chat history accordingly.

---

9 — Anti-patterns

• NEVER call a tool named in this skill without confirming it against discovery — the names are documented for v2, not guaranteed.
• NEVER call MCP tools without first inspecting their schema via GetDynamicTools.
• NEVER assume the MCP server is configured for paper, and never treat an account response as proof of it — paper mode comes from ALPACA_PAPER_TRADE.
• NEVER read the MCP config file wholesale to check that flag — the same env block holds the API keys. Extract the single field.
• NEVER treat an unidentifiable server entry as an absent flag — absent passes, inconclusive fails closed.
• NEVER fall back to direct HTTP calls if the MCP server is available. This is the MCP version.
• NEVER pass API keys as MCP tool arguments — the server handles auth internally.
• NEVER place live trades or continue if the account appears to be live.
• NEVER submit an order without showing you a preview first.
• NEVER skip the paper-environment verification step.
• NEVER provide financial advice, price predictions, or trade recommendations.
• NEVER retry auth errors with different credentials — tell you to fix the MCP server config.
• NEVER silently change order parameters after your confirmation.
• NEVER assume a specific MCP server package name or version — discover at runtime.
• NEVER use required_permissions: ["all"] for MCP tool calls — they do not need it.
• NEVER invent MCP tool parameters not present in the discovered schema.
• NEVER treat partial fills as complete — always report remaining quantity.
• NEVER call close_all_positions or cancel_all_orders unprompted — both are unscoped and hit holdings this session never created. List what will be affected and require an explicit "yes".
• NEVER exercise an option without explicit confirmation — exercise and do-not-exercise instructions are irreversible.
• NEVER report a closed position as flat the moment the close tool returns — it submits a sell order that may still be queued or partially filled.

---

10 — Related files

• reference.md — MCP tool discovery patterns, order type reference, error handling, asset class specifics

Companion skills

• alpaca-trading-paper-trading — Generic implementation-agnostic paper-trading skill
• alpaca-trading-paper-trading-cli — CLI-specific paper-trading skill