Alpaca MCP V1 vs V2: what changed and how to upgrade

✓ Written from Alpaca's official README and docs · checked 2026-10-16

Short answer: V2 is a complete rewrite of Alpaca's official MCP server, built with FastMCP and Alpaca's OpenAPI specs. None of the V1 tools exist in V2, configuration moved from a .env file plus init command to env vars in your MCP client config, and V2 adds ALPACA_TOOLSETS to limit which tools the AI sees. Treat it as a new server, not an update.

What changed

Aspect	V1	V2
Tool names	Hand-crafted (e.g. `get_account_info`)	Derived from the API spec with overrides; names may overlap with V1 but schemas differ
Parameters	Custom schemas	Aligned with Alpaca API specs
Configuration	`.env` + `init` command	Env vars in the MCP client config only; no files written to disk
Tool filtering / whitelisting	Not supported	`ALPACA_TOOLSETS` env var

Upgrade checklist

Don't reuse V1 config. Update the command/args in your MCP client and remove any .env or init-based setup.
Restart your MCP client (Claude Desktop, Cursor, VS Code…) so it fetches the new tool list.
Start a fresh chat, since old sessions may reference V1 tool names.
Update custom instructions and rules (Cursor rules, Claude instructions) that name V1 tools.
Rebuild scripts or prompts that call V1 tools by name: Alpaca says to treat them as obsolete.
Restrict tools with ALPACA_TOOLSETS if you previously limited what the assistant could do.

V2 config (Claude Desktop)

{
  "mcpServers": {
    "alpaca": {
      "command": "uvx",
      "args": ["alpaca-mcp-server"],
      "env": {
        "ALPACA_API_KEY": "your_alpaca_api_key",
        "ALPACA_SECRET_KEY": "your_alpaca_secret_key",
        "ALPACA_TOOLSETS": "account,stock-data,crypto-data,options-data,news"
      }
    }
  }
}

That toolset list is read-only: it leaves out trading. ALPACA_PAPER_TRADE defaults to true; set it to false only with live keys. Full walkthrough: connect Claude to Alpaca MCP.

V2 toolsets

Toolset	Covers
`account`	Account info, config, portfolio history, activities
`trading`	Orders, positions, exercise options
`watchlists`	Watchlist CRUD operations
`assets`	Asset lookup, option contracts, calendar, clock
`stock-data`	Stock bars, quotes, trades, snapshots, screeners
`crypto-data`	Crypto bars, quotes, trades, snapshots, orderbooks
`options-data`	Option bars, quotes, trades, snapshots, chain, exchange codes
`corporate-actions`	Corporate action announcements
`news`	News articles for stocks and crypto
`fixed-income-data`	Fixed income (bond/treasury) quotes
`locates`	Short-sale locate requests and quotes

Staying on V1

Pin the last V1 release in your MCP client config, e.g. uvx alpaca-mcp-server==1.x.x serve (Alpaca's placeholder; pick the exact 1.x version you use). V1 remains on PyPI for existing setups.

FAQ

Is Alpaca MCP V2 a drop-in replacement for V1?

No. Alpaca says V2 is a complete rewrite built with FastMCP and OpenAPI, none of the V1 tools exist in V2, and you should assume no backward compatibility.

How do I limit which tools V2 exposes?

Set ALPACA_TOOLSETS to a comma-separated list of toolsets, for example stock-data,crypto-data. V1 had no tool filtering.

Can I stay on V1?

Yes. Pin the last V1 release in your MCP client config (Alpaca's example: uvx alpaca-mcp-server==1.x.x serve). V1 remains on PyPI.

Does V2 still default to paper trading?

Yes. ALPACA_PAPER_TRADE defaults to true; set it to false with live keys to trade live.

Sources: alpacahq/alpaca-mcp-server README, "Upgrading from V1" · Alpaca MCP docs. Not financial advice.