/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](https://github.com/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`, `g