Alpaca MCP-Powered Options Flow Analyzer & Follow-Through Agent

Project Overview

This project creates a custom MCP (Model Context Protocol) server that detects unusual options order flow using Alpaca's real-time options trade WebSocket stream. The system then uses AI agents to analyze this flow, generate trading signals, select optimal defined-risk options strategies, and execute trades via Alpaca's paper trading account.

Why This Project Wins the Alpaca AI Trading Agents Hackathon

1. Direct MCP Innovation 🏆

• Rather than just using Alpaca's existing MCP tools, we built a custom MCP server that extends Alpaca's ecosystem
• Demonstrates deep understanding of MCP by creating new tools (detect_unusual_flow) that don't exist in the vanilla Alpaca MCP
• Shows sponsors we can build valuable additions to their platform

2. Real Competitive Edge 📈

• Detects options sweeps, block trades, and volume spikes before price moves
• Provides genuine informational advantage by analyzing raw options flow data
• Combines multiple detection methods for robust signal generation

3. Multi-Agent Architecture 🤖

• Flow Detection Agent: Uses custom MCP to monitor unusual options activity
• Strategy Selector Agent: Chooses optimal defined-risk structures (spreads, condors)
• Execution Agent: Places trades via Alpaca's standard MCP tools
• Risk Manager: Enforces strict position sizing and loss limits
• Clear separation of concerns makes the system robust and extensible

4. Risk-First Approach ⚖️

• Only defined-risk strategies (no naked options selling)
• Position sizing: Max 5% of equity per trade
• Daily loss limit: 10% of starting equity
• Max 3 concurrent positions
• Sector exposure limits
• Perfect for impressing fintech judges who prioritize risk management

5. Hackathon-Friendly Implementation ⏱️

• Modular design allows incremental development
• Clear MVP: WebSocket → MCP server → signal generation → paper trading
• Uses Alpaca's paper trading account for zero-risk demonstration
• Easy to showcase with simulated or real data

System Architecture

Alpaca Options Trade WebSocket
           ↓
[Custom MCP Server] ←→ [Flow Detection Agent]
           ↓                    ↓
   detect_unusual_flow tool    Trading Signals
           ↓                    ↓
[Strategy Selector] ←→ [Execution Agent] ←→ [Alpaca Standard MCP]
           ↓                    ↓
   Defined-Risk Strategies    Paper Trading Orders
           ↓
     [Risk Manager] ← (Position Limits, Daily Loss Controls)

Key Features

🔍 Options Flow Detection

• Connects to Alpaca's options trade WebSocket: wss://stream.data.alpaca.markets/v1beta1/us/option/trades
• Calculates real-time trade premiums (price × volume × 100)
• Detects three types of unusual activity:
  • Sweeps: Multiple trades at same ask/bid within short time window
  • Block Trades: Single trade > min_volume contracts or > min_premium $
  • Volume Spikes: Current minute volume > 3× historical average

🧠 AI Agent Workflow

1. Flow Detection Agent receives unusual flow events from custom MCP
2. Generates trading signals based on flow type and option characteristics
3. Strategy Selector chooses optimal defined-risk structure:
   • Bullish flow → Bull Call Spread or Cash-Secured Put
   • Bearish flow → Bear Put Spread or Covered Call
   • High volume → Iron Condor or Strangle
4. Risk Manager validates trade against account limits
5. Execution Agent places trade via Alpaca's paper trading MCP tools

⚙️ Technical Implementation

• Custom MCP Server: Built using the official MCP Python SDK
• WebSocket Connection: Real-time options trade data from Alpaca
• Paper Trading: All execution uses Alpaca's safe paper trading environment
• Risk Management: Comprehensive position sizing and loss controls
• Modular Design: Each component can be tested and extended independently

Files

• alpaca_options_flow_engine.py - WebSocket connection and flow detection logic
• alpaca_options_mcp_server.py - Custom MCP server exposing detect_unusual_flow tool
• flow_detection_agent.py - Agent that uses the custom MCP tool
• strategy_selector.py - Chooses optimal options strategies based on signals
• execution_agent.py - Places trades using Alpaca's standard MCP tools
• risk_manager.py - Enforces position limits, daily loss limits, etc.
• main_agent.py - Orchestrates all components
• demo.py - Interactive demonstration of the system
• requirements.txt - Python dependencies

Setup & Installation

1. Clone the repository

   git clone <repository-url>
   cd alpaca_options_flow_agent

2. Install dependencies

   pip install -r requirements.txt

3. Set up Alpaca API credentials

   cp .env.example .env
   # Edit .env and add your Alpaca paper trading API keys

4. Run the demo

   python demo.py

5. Run the full agent

   python main_agent.py

Hackathon Demo Strategy

What Judges Will See

1. Live options flow detection showing sweeps/block trades in real-time
2. Automatic signal generation from detected flow patterns
3. Strategy selection showing defined-risk options spreads
4. Risk management validation before trade execution
5. Paper trading execution demonstrating Alpaca MCP integration
6. Performance tracking showing win/loss ratios and P&L

Key Talking Points

• "We didn't just use Alpaca's MCP - we extended it with a custom options flow detection tool"
• "Our system sees unusual options activity before it affects stock prices"
• "Every trade uses defined-risk strategies only - we never sell naked options"
• "We built a complete multi-agent system that flows from detection to execution"
• "All trading happens in Alpaca's paper trading environment for zero-risk demonstration"

Risk Management Details

Position Sizing

• Maximum 5% of account equity at risk per trade
• Automatically scales position based on strategy max risk

Daily Limits

• Maximum 10% of starting equity lost per day
• Automatic trading halt if daily loss limit exceeded

Portfolio Controls

• Maximum 3 concurrent open positions
• Sector exposure limits to prevent over-concentration
• Regular position monitoring and automatic stop-loss/profit-taking

Strategy Safety

• Only defined-risk options strategies (vertical spreads, calendars, iron condors)
• No naked options selling
• No leverage beyond the defined spread width

Extensibility

The system is designed to be easily extended:

• Add more sophisticated flow detection algorithms
• Integrate additional data sources (news, social sentiment, technical indicators)
• Enhance strategy selection with machine learning or backtesting
• Add more complex options strategies (butterflies, ratio spreads)