Alpaca + RiskModels

A linked Alpaca account reaches the RiskModels engine through one MCP server. Alpaca Connect stores the open equity positions. The RiskModels connector reads that book, decomposes it, and sizes the ETF hedge legs. RiskModels does not place orders.

RiskModels is listed on the Alpaca Connect marketplace as a read-only app. The Connect path and the RiskModels MCP path do not receive Alpaca API keys. Keys used by the optional Alpaca MCP stay on that local process.

Connect Trade and Plaid write into the same default portfolio. riskmodels_get_my_positions reads whichever of the three sources last synced.

Path 1: Alpaca Connect (web app)

1. Sign in at riskmodels.net and open Settings.
2. In the Alpaca card, choose Live account or Paper account and click Connect Alpaca.
3. Approve the request on Alpaca's consent screen. The requested scope is data. No trading permission is requested.
4. You return to Settings with the account listed as Connected. Click Sync positions to pull the current book.

The card reports each sync as a count of equity positions synced, covered and excluded. Crypto and options positions are excluded from the sync because the ERM3 model covers US equities. Syncs run when you click Sync positions. The same call also refreshes the Plaid and ConnectTrade sources. There is no background schedule, so re-sync after trading to bring the portfolio current.

A paper-only Alpaca login is stored as a paper connection whichever option was selected, because Alpaca reports the account status as paper-only during the link. Live and paper accounts can be linked side by side.

To disconnect, click the trash icon on the connection row. That removes the stored token from RiskModels. To revoke the app at Alpaca as well, use Connected Apps in the Alpaca dashboard.

Path 2: One RiskModels MCP server

Add the RiskModels connector. In Claude Desktop, Settings → Connectors → Add custom connector with the URL https://riskmodels.app/api/mcp/sse, then Connect and sign in once. Details are in Agent integration.

For Claude Code, install the plugin, which wraps the hosted MCP:

claude plugin marketplace add BlueWaterCorp/riskmodels-plugin
claude plugin install riskmodels@riskmodels

Keep one RiskModels MCP connection per client. Registering both the plugin and a separate connector produces duplicate tools.

A hedge session

The book has to be synced first (Path 1). Each step names the tool on the RiskModels server.

1. Read the book. "Read my linked positions." The server calls riskmodels_get_my_positions. The payload includes for_analysis (ticker and weight), for_hedge (ticker and dollars), and for_exposure (ticker and signed dollars, short < 0). When the book has a short position (has_shorts) or more than 100 names, the agent passes for_exposure to riskmodels_portfolio_exposure instead of steps 2 and 3.
2. Decompose it. "Analyze this book: explained risk by market, sector, subsector and stock-specific layer." The server passes for_analysis to riskmodels_analyze_portfolio.
3. Size the legs. "Give me the ETF hedge legs for the current book." The server passes for_hedge (dollar positions) to riskmodels_analyze_portfolio, which returns the ETF tickers, hedge ratios and dollar legs.

An empty book means Settings has no synced positions yet. Connect a brokerage and click Sync positions, then call the tool again.

The RiskModels calls are metered per underlying REST route and carry _metadata.model_version, data_as_of and _agent.request_id.

Optional: Alpaca MCP for order entry

Alpaca publishes an official MCP server (alpacahq/alpaca-mcp-server) with account, position, order and market-data tools. Add it only when the same chat should place orders. Reading and analyzing the book does not require it.

Claude Desktop

Add the Alpaca server to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "alpaca": {
      "command": "uvx",
      "args": ["alpaca-mcp-server"],
      "env": {
        "ALPACA_API_KEY": "your_alpaca_api_key",
        "ALPACA_SECRET_KEY": "your_alpaca_secret_key",
        "ALPACA_PAPER_TRADE": "true"
      }
    }
  }
}

Restart Claude Desktop.

Claude Code

claude mcp add alpaca --scope user --transport stdio uvx alpaca-mcp-server \
  --env ALPACA_API_KEY=your_alpaca_api_key \
  --env ALPACA_SECRET_KEY=your_alpaca_secret_key \
  --env ALPACA_PAPER_TRADE=true

Environment variables on the Alpaca side

Alpaca's server runs locally over stdio. Alpaca's documentation states it should not be exposed to the public internet with API keys attached. For Claude on mobile or web, Alpaca publishes a self-hosting guide.

To place a paper order after the hedge legs are sized: "Place the SPY leg as a day limit order in paper." Claude calls place_stock_order on the Alpaca server and asks for confirmation before each order. ALPACA_PAPER_TRADE=true keeps the order in the paper account.

Choosing a path

Use Alpaca Connect plus the RiskModels MCP when the session should read the book and size hedge legs. Add Alpaca's MCP when that same session should also place orders.

Related

• Agent integration: connector setup for Claude, ChatGPT, Grok, Gemini and Cursor.
• Plaid holdings: the browser-based brokerage link used for accounts outside Alpaca.
• Methodology: how the hedge ratios are computed.