@beneat/risk-mcp-server

Risk enforcement and behavioral coaching for AI trading agents. 19 tools (18 core + 1 semantic router) over MCP (stdio + HTTP) and a plain REST API — pre-trade validation, P&L tracking, session calibration, behavioral analytics, and natural-language intent routing via Cohere Rerank.

The reference implementation is wired to Solana + Drift Protocol. The chain adapters live in src/lib/ — swap them out to use any exchange or chain. See Adapting to Other Chains.

Your agent trades. Beneat makes sure it doesn't blow up.

Hosted Instance

Beneat MCP is live at https://beneat-mcp.onrender.com. No installation required.

Add to any MCP client config:

{
  "mcpServers": {
    "beneat": {
      "type": "streamable-http",
      "url": "https://beneat-mcp.onrender.com/mcp"
    }
  }
}

REST API

curl https://beneat-mcp.onrender.com/health                                         # Health check
curl https://beneat-mcp.onrender.com/api/tools                                      # Tool manifest
curl -X POST https://beneat-mcp.onrender.com/api/tools/beneat_get_status \
  -H "Content-Type: application/json" -d '{"wallet_address":"YOUR_WALLET"}'          # Call any tool
curl -X POST https://beneat-mcp.onrender.com/api/route \
  -H "Content-Type: application/json" -d '{"intent":"am I safe to trade?"}'          # Semantic routing

Self-Host

cd mcp-server
npm install && npm run build
npm run start:http    # HTTP on localhost:3001
npm run start         # stdio transport

Self-hosted REST API uses http://localhost:3001 instead of the hosted URL.

Then add one line to your agent's system prompt:

Before executing any trade, call beneat_check_trade with your wallet address. After every trade, call beneat_record_trade with the P&L.

Zero code changes to your trading logic. The MCP server handles enforcement.

How It Works

Agent wants to trade
  │
  ├─ beneat_calibrate ──→ Sets risk rules (daily loss limit, max trades, cooldown)
  │                        Returns unsigned TXs to deploy on-chain
  │
  ├─ beneat_check_trade ──→ Pre-flight: lockout? cooldown? budget left?
  │                          Returns approved/denied + coaching context
  │
  ├─ [Agent executes trade]
  │
  ├─ beneat_record_trade ──→ Logs P&L in session tracker
  │                           Daily loss limit breached?
  │                             ├─ YES → Lockout triggered → AgentWallet FROZEN
  │                             └─ NO  → Continue trading
  │
  └─ beneat_check_trade ──→ DENIED (vault locked, wallet frozen)
                             Agent blocked until lockout expires

Vault-Optional Mode

7 tools work without a Beneat vault account, falling back to Helius transaction history analysis:

Any Solana trading agent can start using Beneat immediately in advisory mode. Create a vault to unlock full enforcement.

Tools (19)

Core Enforcement

Agent Coaching

Discovery & Monitoring

Admin & Registration

Semantic Routing

Also available as POST /api/route for REST clients outside MCP.

Calibration Tiers

The calibration engine adapts to the agent's trade history:

Strategy presets:

Risk tolerance levels:

Quick Start

# Build
cd mcp-server
npm install
npm run build

# Run the demo (full enforcement lifecycle)
npm run demo

# Run E2E tests (all 19 tools)
npm run test:e2e

# Start the server (stdio transport)
npm run start

# Start HTTP server (REST + MCP-over-HTTP)
npm run start:http

# Open MCP Inspector UI
npm run inspect

Environment Variables

Architecture

src/
├── index.ts                    # Server setup, 19 tool registrations, --http flag
├── http-server.ts              # HTTP server: REST endpoints + /api/route semantic routing
├── tool-registry.ts            # ToolDefinition interface, TOOL_REGISTRY, tool document builder
├── tools/                      # One file per tool
│   ├── check-trade.ts          # Core: pre-flight authorization
│   ├── record-trade.ts         # Core: P&L logging + lockout trigger
│   ├── calibrate.ts            # Core: 3-tier auto-calibration
│   ├── analytics.ts            # Behavioral analysis + directives
│   ├── playbook.ts             # Personalized trading playbook
│   ├── session-strategy.ts     # Dynamic session limits
│   ├── smart-route.ts          # Semantic tool routing via Cohere Rerank
│   └── ...                     # 12 more tools
├── lib/
│   ├── quant-engine.ts         # Calibration + analytics engine (~1250 lines)
│   ├── vault-reader.ts         # On-chain vault/profile/Drift deserialization
│   ├── transaction-builder.ts  # Unsigned VersionedTransaction construction
│   ├── session-store.ts        # In-memory session tracking + inferSessionState()
│   ├── reranker.ts             # Cohere Rerank client with graceful fallback
│   ├── helius-client.ts        # Helius API with circuit breaker
│   ├── agentwallet-client.ts   # AgentWallet policy enforcement
│   ├── scoring.ts              # Trust score (0-100) computation
│   ├── types.ts                # All TypeScript interfaces
│   ├── constants.ts            # Program IDs, seeds, strategy defaults
│   ├── utils.ts                # safeCall, bigintReplacer, jsonContent helpers
│   └── pda.ts                  # Vault & profile PDA derivation
└── generated/vault/            # Codama-generated IDL types (do not edit)

Key Design Decisions

Never signs transactions. The server builds unsigned VersionedTransaction objects (base64-encoded) for the caller to sign. Private keys never touch the MCP server.

Vault-optional fallback. When no vault exists, tools fall back to Helius transaction history for analytics and advisory-mode enforcement. Agents can start without any on-chain setup.

Machine-readable output. Analytics returns structured directives[] (e.g., { type: "avoid_market", severity: "warning", params: { market: "PUMP_FUN" } }) that agents can consume programmatically.

Session state classification. The coaching engine classifies agents into 5 states (normal, post_loss, tilt, hot_streak, post_lockout_recovery) and adjusts position sizing, trade limits, and market recommendations accordingly.

On-Chain Programs

PDA seeds: ["vault", owner] and ["trader_profile", authority]

Adapting to Other Chains

The business logic — calibration, session state, behavioral analytics, coaching, scoring, semantic routing — is chain-agnostic. Only four files in src/lib/ are Solana-specific. Fork and replace them to target any exchange or chain:

Everything in quant-engine.ts, session-store.ts, scoring.ts, reranker.ts, and all src/tools/ stays the same.

Advisory Mode (no chain required)

14 of 19 tools run entirely on in-memory session state — no wallet, no RPC, no API keys needed. Useful for testing, CEX agents, or any context where on-chain state isn't available.

Dependencies

License

MIT