Guardian MCP

Guardian MCP is a policy-bounded AI trading gateway for Alpaca paper trading. AI agents can propose stock, ETF, and crypto trades, but deterministic rules decide whether the trade is blocked, approved for human review, or submitted to Alpaca paper trading.

Why this exists

Most AI trading demos give the model too much authority. Guardian separates the workflow:

AI proposes a TradeIntent
Guardian validates the intent
Policy engine approves or blocks
Alpaca paper trading receives only approved low-risk orders
Every decision becomes an audit receipt

Related MCP server: alpaca-mcp-server

Current scope

• US equities and ETFs

• Crypto pairs on Alpaca, including BTC/USD, ETH/USD, and SOL/USD

• Paper trading only

• Mock Alpaca execution when API keys are missing

• Local JSON audit log for the first demo

• Official Alpaca Skills alignment for paper-only safety gates

Getting started

npm install
npm run dev

Open http://localhost:3000.

To connect Alpaca paper trading, create .env.local:

ALPACA_API_KEY=your_key
ALPACA_SECRET_KEY=your_secret
ALPACA_PAPER_BASE_URL=https://paper-api.alpaca.markets
ALPACA_PAPER_TRADE=true
TELEGRAM_BOT_TOKEN=your_botfather_token

Alpaca's official skills also use APCA_API_KEY_ID and APCA_API_SECRET_KEY; Guardian supports those names too.

Do not paste API keys into chat or commit them. Guardian blocks live Alpaca configuration and only supports paper trading.

Demo flow

1. Pick a mock AI trade proposal.

2. Run the guard.

3. See allowed trades submitted to mock or real Alpaca paper trading.

4. See blocked trades recorded with exact policy reasons.

Telegram bot

Guardian can also run as a Telegram bot for the chat-first demo:

npm run telegram

Bot commands:

/account
/portfolio
/policy
/preview buy SOL/USD 50
/confirm guardian-tg-...

The bot uses long polling, so it should run on your Google VM, not Vercel. It never submits silently: /preview creates the paper order preview and /confirm is required before Guardian can submit to Alpaca paper trading.

To run beside another process on the VM:

pm2 start npm --name guardian-telegram -- run telegram
pm2 save

Policy defaults

• Paper-only mode

• Max trade notional: $500

• Human approval above: $100

• Max daily loss: 2%

• Max position exposure: 15%

• Max crypto trade notional: $100

• Max crypto portfolio exposure: 20%

• Crypto cooldown: 15 minutes

Hackathon pitch

Guardian MCP lets AI trading agents operate through Alpaca without giving the model unchecked control over an account. The model can research and propose trades; Guardian enforces deterministic user policy before execution and records every decision in a replayable audit trail.

Alpaca Skills

This repo is aligned with Alpaca's official agent skills. See docs/alpaca-skills.md for the paper-trading guardrails and the remaining Alpaca-specific work.

MCP Server

Guardian includes its own MCP server:

npm run mcp

See docs/mcp.md for tool names and MCP client configuration.