Alpaca + RiskModels

Two paths bring an Alpaca account's positions to the RiskModels engine. The first is a read-only OAuth link inside the web app. The second runs Alpaca's own MCP server next to the RiskModels MCP connector in a Claude session, so one conversation can read positions, decompose them, and hand the ETF hedge legs back to Alpaca for execution.

RiskModels is listed on the Alpaca Connect marketplace as a read-only app. RiskModels never receives your Alpaca API keys under either path.

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. The linked account is also included in the scheduled position sync that runs the Plaid and ConnectTrade sources.

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: Alpaca MCP + RiskModels MCP in Claude

Alpaca publishes an official MCP server (alpacahq/alpaca-mcp-server) that exposes account, position, order and market-data tools to any MCP client. Running it alongside the RiskModels connector gives Claude both halves of a hedge workflow: the book from Alpaca and the factor decomposition from RiskModels.

Prerequisites

• An Alpaca API key and secret. Paper credentials come from the paper dashboard and are free.
• uv installed, which provides the uvx runner Alpaca's server uses.
• The RiskModels connector added to the same client. 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.

Claude Desktop

Add the Alpaca server to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows). The RiskModels side is already handled by the connector, so only Alpaca goes in this file:

{
  "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. Both tool sets appear in a new conversation.

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

For RiskModels in Claude Code, install the plugin, which wraps the hosted MCP with slash commands and the riskmodels-analyst agent:

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.

Environment variables on the Alpaca side

Alpaca's server runs locally over stdio and does not implement remote authentication. 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.

A hedge session, step by step

The sequence below is one conversation. Each step names the tool Claude calls.

1. Read the book. "List my open Alpaca positions with quantity and market value." Claude calls get_all_positions on the Alpaca server.
2. Decompose it. "Analyze this portfolio with RiskModels: explained risk by market, sector, subsector and stock-specific layer, and the recommended hedge level." Claude passes the tickers and market values to riskmodels_analyze_portfolio. The response carries L1/L2/L3 explained risk, portfolio volatility and the ETF hedge ratios at each level.
3. Size the legs. "Give me the ETF hedge legs in shares at the recommended level for the current book." Claude calls riskmodels_hedge_portfolio, which returns the ETF tickers, hedge ratios and dollar legs for the aggregate position.
4. Execute, if wanted. "Place the SPY leg as a day limit order in paper." Claude calls place_stock_order on the Alpaca server. Claude asks for confirmation before each order, and ALPACA_PAPER_TRADE=true keeps the order in the paper account.

The RiskModels calls are metered per underlying REST route and carry _metadata.model_version, data_as_of and _agent.request_id, so the hedge legs sent to Alpaca can be traced to the exact model inputs that produced them. Alpaca's tools are free to call.

What each side sees

• Alpaca's server holds your API keys locally. RiskModels receives tickers and weights or notionals, and nothing about the account.
• RiskModels bills the signed-in account for data calls. Discovery tools are free.
• Orders go through Alpaca's tools only. RiskModels has no order-placement capability under either path.

Choosing a path

Use Alpaca Connect when you want the book to stay current in the web app without running anything locally. Use the MCP pairing when the analysis and the execution should happen in the same conversation, or when the account is a paper account used for testing hedge sizes before trading them live.

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.