Safety-First MCP Quant Risk Orchestration Engine

This project is a production-like paper-trading and risk orchestration platform designed around deterministic pre-trade validation, auditability, and fail-closed operational controls. It includes a browser dashboard, REST API, MCP tools, PostgreSQL persistence, Redis controls, and Docker deployment.

Safety posture: live order routing is disabled by default and hard-coded to paper mode. This repository is designed to support controlled paper trading and operational validation, not live broker execution.

Architecture Overview

MCP Client / Agent
      |
      v
FastMCP Server
      |
      +--> Risk Engine (VaR, drawdown, max position)
      +--> Order State Machine (QUEUED -> VALIDATED -> APPROVED -> PAPER_FILLED)
      +--> PostgreSQL persistence (orders, positions, audit_logs)
      +--> Redis cache and token-bucket rate limiter
      +--> FastAPI gateway (dashboard, REST API, /healthz, /metrics)
      +--> Prometheus + Grafana observability

Related MCP server: trading-mcp-server

Portfolio Application

The FastAPI gateway serves the dashboard at http://localhost:8000/. The dashboard provides:

• synthetic market state and order-book depth

• risk evaluation before execution

• paper-order submission

• open positions and recent orders

• immutable audit events

• portfolio and circuit-breaker status

• explicit PAPER MODE and FAIL-CLOSED safety indicators

The dashboard is intentionally a live paper-trading console, not a real-money trading interface.

Is the website hard-coded?

The UI does not fabricate order results. It calls the FastAPI endpoints, which execute the risk engine and persist orders, positions, and audit events in PostgreSQL. Redis supplies rate limiting and alert publishing.

The market feed is intentionally synthetic and deterministic. A ticker produces a repeatable demonstration quote, depth, spread, and feature vector instead of connecting to an exchange. This keeps the demo safe and reproducible. Replacing _market_state() with a validated market-data adapter is the production integration boundary.

Browser-only workflow

You can use the complete paper-trading application from the website without an MCP client:

1. Enter a ticker to inspect its market state.

2. Evaluate a BUY or SELL order against the risk controls.

3. Submit the order through guarded paper execution.

4. View the persisted order, position, and audit records.

5. Run a portfolio risk report.

6. Run a deterministic stress scenario.

7. Monitor the circuit breaker and system status.

MCP clients and the website are two interfaces over the same workflow skills. The website is the easiest human interface; MCP is the automation interface for agents.

REST API

The dashboard uses these HTTP endpoints:

Example PowerShell request:

$body = @{ ticker = "AAPL"; side = "BUY"; qty = 10 } | ConvertTo-Json
Invoke-RestMethod http://localhost:8000/api/orders/paper -Method Post `
      -Headers @{ "X-Idempotency-Key" = "demo-aapl-order-001" } `
  -ContentType "application/json" -Body $body

Each order key is cached in Redis for 24 hours. Repeating the same key returns the original completed payload without re-running risk or filling another order. Execution also acquires lock:position:{ticker} with a 500ms deadline; if another worker holds that ticker lock, the API returns 409 Conflict and records distributed_lock_timeout in the audit log.

MCP Tools and Skills

MCP tools are the machine-callable skills of this application. An MCP client or agent can discover and invoke them through the FastMCP server. They all use the same risk and order-control concepts as the dashboard API:

The same catalog is available to browser and API clients at:

GET /api/skills

Example skill-oriented agent flow:

1. list_skills
2. get_market_state("AAPL")
3. evaluate_risk("AAPL", "BUY", 10)
4. execute_trade("AAPL", "BUY", 10)
5. portfolio_risk_report()
6. stress_test_portfolio(-5)

Skills are intentionally workflow-level capabilities, while tools remain the individual callable operations. Both entry points use the same fail-closed risk engine, order state machine, PostgreSQL records, Redis controls, and audit events.

The reusable skill pattern is:

request -> rate limit -> risk evaluation -> state transition -> persistence -> audit + alert

You can add future skills as new @mcp.tool() functions and corresponding REST routes, but they should call shared domain services rather than duplicate risk logic. Current higher-level skills include portfolio-risk reporting and scenario stress testing. Appropriate future skills include reconciliation checks, operator health summaries, and model-drift checks.

Order State Machine

The order lifecycle is deliberately strict and fail-closed:

QUEUED -> VALIDATED -> APPROVED -> PAPER_FILLED
   \-> REJECTED

VALIDATED -> REJECTED
APPROVED -> REJECTED
REJECTED -> * (terminal)
PAPER_FILLED -> * (terminal)

Any invalid transition raises an explicit domain exception via OrderStateTransitionError.

Risk Architecture

The risk engine enforces:

• max position size per asset

• account-level VaR threshold

• dynamic daily drawdown circuit breaker

• audit-log immutability for rejected trades

• Redis pub/sub alerting on risk breaches

If any limit is breached, the system writes the rejection event to audit_logs, rejects the order, and triggers the alert channel.

Database Layout

The project uses PostgreSQL + SQLAlchemy Async ORM. Core schema:

• orders: id, ticker, side, qty, price, status, created_at, updated_at

• positions: ticker, qty, avg_entry_price, unrealized_pnl

• audit_logs: id, order_id, event_type, details (JSONB), timestamp

A SQL migration script is provided in migrations/001_init_schema.sql.

Runtime Components

• mcp_server.py: MCP tools and higher-level skills for market state, risk, execution, reporting, and stress testing

• core/risk.py: deterministic risk engine and fail-closed breaker

• core/cache.py: Redis-backed state and token-bucket limiter

• core/db.py: Async SQLAlchemy session and table definitions

• core/state_machine.py: order lifecycle enforcement

• api/gateway.py: FastAPI dashboard, REST API, health, and Prometheus metrics endpoints

• frontend/: responsive browser dashboard served by FastAPI

• migrations/001_init_schema.sql: PostgreSQL schema migration

• .github/workflows/ci.yml: automated tests, formatting, and lint checks

Quick Start

python -m venv .venv
source .venv/bin/activate  # or .\.venv\Scripts\Activate.ps1 on Windows
python -m pip install -e .[dev]
cp .env.example .env
python -m uvicorn api.gateway:app --host 0.0.0.0 --port 8000

Open the dashboard at http://localhost:8000/.

Local MCP runner:

python mcp_server.py

Testing and Quality Gates

pytest -q
black --check .
flake8 .

The verified local integration flow is:

healthz -> market state -> paper order -> PostgreSQL order/position/audit records

The test suite covers state transitions, risk rejection, drawdown/VaR controls, Redis rate limiting, and database initialization.

Deployment Stack

The repository includes container health checks and a full local observability stack:

• PostgreSQL

• Redis

• Prometheus

• Grafana

• trading-engine service

Run the full stack:

docker compose up --build

If port 8000 is already used on your machine, choose another host port in PowerShell:

$env:APP_PORT = "8001"
docker compose up -d --build

Then open http://localhost:8001/.

For a detached deployment:

docker compose up -d --build

Then visit:

• http://localhost:8000/healthz

• http://localhost:8000/metrics

• http://localhost:3000 (Grafana)

• http://localhost:9090 (Prometheus)

Check the running stack:

Invoke-RestMethod http://localhost:8000/healthz | ConvertTo-Json

Expected health response includes:

{"status":"ok","database":true,"redis":true,"paper_mode":true}

Operational Safety Guarantees

This design intentionally enforces the following:

1. paper-only execution by default

2. explicit validation before execution

3. immutable audit records for every risk decision

4. fail-closed circuit breaker for drawdown and VaR violations

5. Redis-backed rate limiting for order spam mitigation

6. structured telemetry for trade execution and risk rejection events

Production Hardening Path

This project is production-oriented but still intentionally constrained to paper trading. It is resume-ready as a deployed portfolio application, but it is not a live brokerage system. Before any real-money integration, the next milestones are:

1. migrate from synthetic market data to a validated feed provider

2. add durable approvals and secrets management

3. enforce multi-party sign-off for live execution

4. replace process-local risk state with fully shared transactional state

5. add authentication, authorization, HTTPS, restricted CORS, and managed secrets

6. add broker execution, idempotency, reconciliation, and exchange-level controls

Never set a public demo to live mode. The intended public deployment is a paper-trading demonstration with protected infrastructure dependencies.

See docs/architecture.md, docs/operational-controls.md, and docs/threat-model.md.