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	If trailing_stop	—	Trailing stop percentage. place_stock_order only
trail_price	If trailing_stop	—	Trailing stop dollar offset. place_stock_order only
extended_hours	No	false	Allow extended-hours fills. place_stock_order only; limit type with day or gtc TIF
client_order_id	No	Alpaca generates one if omitted	Idempotency key — your agent generates one per order
order_class	No	null	simple, bracket, oco, oto. place_stock_order only. Automatically set to bracket when either bracket-leg parameter below is supplied
take_profit_limit_price	If bracket	—	Limit price for the take-profit leg. place_stock_order only
stop_loss_stop_price	If bracket	—	Stop price for the stop-loss leg. place_stock_order only
stop_loss_limit_price	No	—	Limit price for the stop-loss leg. Requires stop_loss_stop_price
position_intent	No	—	buy_to_open, buy_to_close, sell_to_open, sell_to_close (options)

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.