Alpaca Trading Paper Trading MCP

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"
      }
    }
  }
}

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

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

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

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:

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:

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:

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.