Sentinel Execution Mcp

Sentinel Execution MCP

[CI] [License: MIT]

A production-grade algorithmic trading control plane exposed as an MCP server — so Claude can manage watchlists, classify market regimes, validate risk, and submit paper orders through natural language.

What It Is

Sentinel is a two-package monorepo:

Claude (or any MCP-compatible agent) talks to the MCP server. The MCP server talks to the engine. The engine owns the database and cache.

Architecture

  Claude Desktop (or any MCP agent)           │           │  MCP protocol (stdio or SSE)           ▼  ┌─────────────────────────┐  │   MCP Server            │  TypeScript · Zod validation · tool routing  │   (packages/mcp)        │  └────────────┬────────────┘               │  HTTP REST (localhost:8100)               ▼  ┌─────────────────────────┐  │   Engine API            │  Python · FastAPI · all trading logic  │   (packages/engine)     │  └──────────┬──────────────┘             │     ┌───────┴────────┐     ▼                ▼ PostgreSQL          Redis (orders,           (kill switch,  positions,         rate limits,  strategies,        cache)  audit log)

If the engine is unavailable, every MCP tool call returns an error immediately. There is no fallback or partial execution.

Quick Start (Docker — recommended)

The fastest way to get running. Requires Docker and Node.js 20+.

# 1. Clone and configuregit clone https://github.com/rohith1125/sentinel-execution-mcp.gitcd sentinel-execution-mcpcp .env.example .env          # defaults work out of the box — no edits needed
# 2. Start Postgres + Redis + engine (runs migrations automatically)docker compose -f docker/docker-compose.yml up -d db redis engine
# Wait ~10 seconds, then verify the engine is healthy:curl http://localhost:8100/health# {"status": "ok", "provider": "mock", ...}
# 3. Build the MCP server (one-time)cd packages/mcpnpm installnpm run build

Then add Sentinel to Claude Desktop (see Connect Claude Desktop below) and restart Claude. That's it — all 40 tools are live.

Manual Setup (no Docker)

Use this if you have Postgres and Redis already running locally.

Prerequisites:

1. Clone and configure

git clone https://github.com/rohith1125/sentinel-execution-mcp.gitcd sentinel-execution-mcpcp .env.example .env# Default values work for local paper-trading development — no edits required

2. Set up the engine

cd packages/enginepython3.12 -m venv .venvsource .venv/bin/activate        # Windows: .venv\Scripts\activatepip install -e ".[dev]"

3. Run database migrations

# From packages/engine with the venv activealembic upgrade head

4. Start the engine

uvicorn sentinel.api:app --reload --port 8100

Verify it is running:

curl http://localhost:8100/health# {"status": "ok", "env": "paper"}

5. Build and start the MCP server

Open a second terminal:

cd packages/mcpnpm installnpm run buildnpm run dev     # stdio transport — for direct Claude Desktop integration

Connect Claude Desktop

Add the following to your Claude Desktop configuration file.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Get the correct path by running this in your terminal:

echo "$(pwd)/packages/mcp/dist/index.js"

Then paste it into the config:

{  "mcpServers": {    "sentinel": {      "command": "node",      "args": ["/absolute/path/to/sentinel-execution-mcp/packages/mcp/dist/index.js"],      "env": {        "ENGINE_BASE_URL": "http://localhost:8100",        "APP_ENV": "paper"      }    }  }}

Restart Claude Desktop after saving. You should see a hammer icon (🔨) in the chat input — click it to confirm Sentinel's 40 tools are loaded.

MCP Tools Reference

Sentinel exposes 40+ tools across nine categories. The MCP server name is sentinel.

Full tool documentation with parameter schemas: docs/mcp-tools.md

Environment Variables

Engine (packages/engine/.env)

MCP Server (packages/mcp/.env)

See .env.example at the repo root for the complete annotated reference.

Example Workflow (Paper Trading)

# 1. Add symbolswatchlist.add(symbols=["NVDA", "MSFT", "AAPL"], group="tech")
# 2. Classify regimeregime.evaluate(symbol="NVDA", timeframe="1Day")
# 3. Scan for signalsstrategy.scan(group="tech", strategy="momentum_v1")
# 4. Validate before submittingrisk.validate_trade(symbol="NVDA", side="buy", qty=10, order_type="market")
# 5. Submit paper orderexecution.paper_order(symbol="NVDA", side="buy", qty=10, order_type="market")
# 6. Review portfolioportfolio.status()
# 7. Inspect the audit trailaudit.recent_events(symbol="NVDA", limit=1)audit.explain_trade(audit_event_id="evt-...")

Running Tests

Engine (Python)

cd packages/enginesource .venv/bin/activatepytest tests/ -v

MCP Server (TypeScript)

cd packages/mcppnpm test

Full CI (lint + type check + test)

# From repo rootmake check

Repository Structure

sentinel-execution-mcp/├── packages/│   ├── engine/          # Python FastAPI trading engine│   │   ├── sentinel/    # Application source│   │   ├── tests/       # Pytest test suite│   │   └── alembic/     # Database migrations│   └── mcp/             # TypeScript MCP server│       └── src/│           └── tools/   # One file per tool category├── docker/              # Dockerfiles and docker-compose├── docs/                # Architecture, tool reference, risk model├── scripts/             # Setup and reset helpers└── .env.example         # Annotated environment variable reference

Safety Disclaimer

This software is for paper trading and research only unless you fully understand every component. Setting APP_ENV=live with real Alpaca credentials will place real orders with real money. The hard-coded risk limits are conservative defaults — verify they match your own risk tolerance before use. The authors accept no liability for financial losses.

License

MIT. See LICENSE.