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.

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

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

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