RiskState — Crypto Risk Engine

Official3 toolsLive

by riskstate

Live BTC/ETH risk state: risk policy, market structure and trading playbooks. Keyless free tier.

Captured live from the server via tools/list.

get_risk_state

Current risk state of Bitcoin (BTC) or Ethereum (ETH): 5-level risk policy (BLOCK to GREEN) with max position size, leverage limit, direction bias and allowed/blocked actions, plus composite score (0-100), structural and tactical scores, market regime (BULL/SIDEWAYS/BEAR), volatility regime, cycle phase and macro state. Computed from 9+ real-time data sources (price, funding, RSI, MVRV, ETF flows, on-chain, macro). Use whenever the user asks how BTC or ETH is doing, whether it is a good time to buy/sell/hold, or how much risk to take.

Parameters1

asset

string

optional

Asset to assess (default BTC)

Raw schema

{
  "type": "object",
  "properties": {
    "asset": {
      "type": "string",
      "enum": [
        "BTC",
        "ETH"
      ],
      "description": "Asset to assess (default BTC)"
    }
  }
}

get_market_structure

Market Structure Engine view for BTC or ETH: validated structural events firing now (breakouts, breakdowns, cycle bottom/top, funding resets), expected asymmetry, distance to the next bullish/bearish triggers, key structural levels (ATH, 200W MA, 180d range) and a friction map of confluence-scored support/resistance walls between spot and the triggers. Use for questions about levels, support/resistance, breakouts or what would change the picture.

Parameters1

asset

string

optional

Asset to analyze (default BTC)

Raw schema

{
  "type": "object",
  "properties": {
    "asset": {
      "type": "string",
      "enum": [
        "BTC",
        "ETH"
      ],
      "description": "Asset to analyze (default BTC)"
    }
  }
}

get_playbook_status

Trading Playbook Engine status: the registry of rule-based trade setups (playbooks) for BTC and ETH and which ones are firing right now, with structure-gate verdicts, cooldown state and why non-firing setups do not match (failed predicates with live market readings). Strategy-level only — no prices, sizes or portfolio data. Use for questions about active trade setups or what the playbooks are watching.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

README.md5 KBView on GitHub

RiskState MCP Server

MCP server for RiskState — pre-trade risk permissions for BTC/USD and ETH/USD. Spot, perpetual futures (perps), and DeFi borrowing aware.

Your system asks: "How much can I risk right now?" RiskState answers with: policy level, max exposure, leverage limits, blocked actions — computed from 30+ real-time signals.

What it does

Wraps the RiskState /v1/risk-state API as an MCP tool. One tool: get_risk_policy.

Field	Description
`policy_level`	5 levels: BLOCK_SURVIVAL, BLOCK_DEFENSIVE, CAUTIOUS, GREEN_SELECTIVE, GREEN_EXPANSION
`max_size_pct`	Maximum position size as % of portfolio (0-100)
`leverage_max`	Maximum allowed leverage multiplier
`allowed_actions`	What the agent CAN do at this policy level
`blocked_actions`	What the agent CANNOT do
`confidence_score`	Signal agreement x data quality (0-1)

The API aggregates 9+ real-time data sources server-side. See API docs for details.

What this wrapper does (and doesn't)

This is a thin wrapper — it translates MCP tool calls into REST API requests to POST /v1/risk-state and returns the response. All computation (scoring, policy engine, data ingestion) happens server-side.

This wrapper adds:

MCP protocol compliance (stdio transport for Claude Desktop/Code)
Input validation via Zod schemas
Human-readable policy summary prepended to responses
Specific error messages (auth, rate limit, timeout) for agent recovery

This wrapper does NOT:

Cache responses (the API has 60s server-side cache)
Perform any scoring or computation locally
Guarantee response schema stability (follows API versioning)

Installation

bash

npm install @riskstate/mcp-server

Configuration

Environment Variables

Variable	Required	Description
`RISKSTATE_API_KEY`	Yes	API key from riskstate.ai (free during beta)
`RISKSTATE_API_URL`	No	Custom API base URL (default: `https://api.riskstate.ai`)

Claude Desktop

Add to ~/.config/Claude/claude_desktop_config.json:

json

{
  "mcpServers": {
    "riskstate": {
      "command": "npx",
      "args": ["-p", "@riskstate/mcp-server", "riskstate-mcp"],
      "env": {
        "RISKSTATE_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

bash

claude mcp add riskstate -- npx -p @riskstate/mcp-server riskstate-mcp

Set the API key in your environment:

bash

export RISKSTATE_API_KEY=your-api-key

Global install (alternative)

bash

npm install -g @riskstate/mcp-server
riskstate-mcp  # starts MCP server on stdio

Usage

The server exposes one tool: get_risk_policy

Parameters

Parameter	Type	Required	Description
`asset`	`"BTC"` \| `"ETH"`	Yes	Asset to analyze
`wallet_address`	string	No	DeFi wallet for on-chain position data
`protocol`	`"spark"` \| `"aave"`	No	Lending protocol (default: spark)
`include_details`	boolean	No	Include full breakdown (subscores, macro, risk flags)

Example Response

json

{
  "exposure_policy": {
    "policy_level": "CAUTIOUS",
    "max_size_pct": 35,
    "leverage_max": 1.5,
    "allowed_actions": ["DCA", "WAIT", "SPOT_LONG_CONFIRMED"],
    "blocked_actions": ["LEVERAGE_GT_2X", "NEW_POSITIONS_UNCONFIRMED"]
  },
  "classification": {
    "cycle_phase": "MID",
    "market_regime": "RANGE",
    "macro_regime": "NEUTRAL",
    "direction": "SIDEWAYS"
  },
  "auditability": {
    "composite_score": 52,
    "confidence_score": 0.72,
    "policy_hash": "a3f8c2...",
    "ttl_seconds": 60
  }
}

How Agents Should Use This

Call get_risk_policy before every trade:

If policy_level starts with BLOCK → do not open new positions
Use max_size_pct to cap position sizing
Check blocked_actions before executing
Re-query after ttl_seconds (60s cache)

Limitations

v1 scope: BTC/USD and ETH/USD only (USD-denominated assessment). More assets planned.
Markets: Spot, perpetual futures, and DeFi borrowing. Same response — interpretation differs by market (see API docs).
Protocols: Spark and Aave V3 only for DeFi position data.
Rate limit: 60 requests/minute per API key.
Latency: ~1-3s per request (9+ upstream data source aggregation).
Tested with: Claude Desktop, Claude Code. Should work with any MCP-compatible client.

License

MIT

Install

Tools (3)

get_risk_stateget_market_structureget_playbook_status

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://api.riskstate.ai/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.riskstate.ai/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

get_risk_state

get_market_structure

get_playbook_status

RiskState MCP Server

What it does

What this wrapper does (and doesn't)

Installation

Configuration

Environment Variables

Claude Desktop

Claude Code

Global install (alternative)

Usage

Parameters

Example Response

How Agents Should Use This

Limitations

Links

License

Install

Remote endpoint