Riskstate

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

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:

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

Claude Code

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

Set the API key in your environment:

export RISKSTATE_API_KEY=your-api-key

Global install (alternative)

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

{
  "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:

1. If policy_level starts with BLOCK → do not open new positions
2. Use max_size_pct to cap position sizing
3. Check blocked_actions before executing
4. 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.

Links

• Landing page: riskstate.ai
• API docs: riskstate.ai/docs/api
• SKILL.md: agentskills.io

License

MIT